Runtime APIs
SCL coordinates role-play content, evaluation, credentials, analytics, and voice services. The learner-facing application uses the selected role-play identifier as the correlation point across these boundaries.
Evaluation API
The public APIM route is versioned under /roleplay-evaluation/v1; deployments can configure the frontend with a base URL that already includes this prefix.
| Method | Route | Purpose | Access |
|---|---|---|---|
GET | /roleplays?page=1&pageSize=4 | List active role-plays, up to 100 per page | Bearer token |
GET | /roleplays/{rolePlayId} | Load one active role-play for the learner journey | Bearer token |
POST | /roleplays/{rolePlayId}/evaluate | Evaluate a completed transcript | Bearer token and valid Accept-Language |
POST | /roleplays/{rolePlayId}/analytics/unload | Record an interrupted analytics session during page unload | Anonymous route with bearer token in the body |
APIM subscription headers are also used by the deployed browser client. They are client-visible controls and must not replace user authentication or authorization.
Role-play response
The role-play detail includes:
- ID, name, description, active analytics tenant, and session timing.
- Localized scenario, objectives, challenges, tips, skills, competency, character profile, and interaction context.
- Localized contextual help.
- SCAI agent identity, organization/environment references, voice endpoints, and DNIS.
Evaluation criteria are deliberately not returned to the browser. The backend loads them only when an evaluation is requested.
When Accept-Language contains an exact xx-XX locale, the API filters briefing and help maps to that locale. The current frontend loads all locales and performs its own fallback selection.
Evaluation request
Accept-Language is required in xx-XX form. The body requires non-negative elapsed seconds and at least one conversation turn; sessionId is included when analytics created one for the attempt.
{
"sessionId": "analytics-session-id",
"elapsedTimeSeconds": 180,
"conversation": [
{
"speaker": "Customer",
"text": "The learner's utterance",
"timestamp": "2026-01-01T10:00:00.000Z"
},
{
"speaker": "Agent",
"text": "The simulated customer's response",
"timestamp": "2026-01-01T10:00:05.000Z"
}
]
}Customer is the human learner. Agent is the AI character. This mapping must remain consistent in every integration and evaluation fixture.
Evaluation response
| Field | Current behaviour |
|---|---|
score | Required integer from 1 to 5 |
description | Required non-empty overall explanation |
performanceIndicators | API requires a non-empty list; the prompt additionally requests criterion order, name, 1–5 score, status, and description |
qualitativeAnalysis | Strengths and improvements requested by the active prompt; not separately required by API validation |
actionPlan | Actionable items requested by the active prompt; not separately required by API validation |
summaryItems | Supported by the API contract but may be empty |
recommendedCourses | Supported by the API and UI but may be empty |
A valid evaluation attempts completion enqueue before returning and independently publishes backend analytics when configured. Neither path waits for downstream delivery, and failures are logged without replacing the evaluation result.
Integration Credentials
| Method | Route shape | Purpose |
|---|---|---|
GET | /credentials/token/scai/{environment} | Obtain SCAI application credentials |
POST | /credentials/token/scai/{environment}/refresh | Refresh SCAI credentials |
GET | /credentials/token/analytics/{environment} | Obtain an analytics technical token |
GET | /credentials/token/ai-factory/{environment} | Obtain an AI Factory technical token from the backend |
The learner bearer token and APIM subscription header authenticate these exchanges. The browser uses the SCAI token for voice practice. Analytics token acquisition and Analytics delivery are backend responsibilities; the browser uses the Evaluation API analytics proxy instead of receiving an Analytics technical token.
Error contract
Evaluation API errors use ProblemDetails and these functional categories:
| Status | Meaning |
|---|---|
| 400 | Invalid pagination, locale, transcript, elapsed time, or unload payload |
| 401 | Missing/rejected user identity or technical-token authentication failure |
| 404 | Role-play or associated active configuration not found |
| 422 | AI evaluation output could not be mapped or validated |
| 502 | Integration Credentials or AI Factory dependency failure |
| 500 | Unexpected server error |
Clients should treat evaluation as non-idempotent unless the service owner defines an idempotency contract. The current API does not expose an evaluation history identifier or retry key.