{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Egma Platform API", "version": "1.0.0", "description": "The customer-facing HTTP interface used by Egma's web app, CLI, and outside clients." }, "servers": [ { "url": "/" } ], "paths": { "/v1/provider-keys": { "get": { "operationId": "listProviderKeys", "summary": "List organization provider API keys", "tags": [ "Provider API keys" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Supported providers and masked credential metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "deepgram", "cartesia" ] }, "label": { "type": "string" }, "credential": { "anyOf": [ { "type": "object", "properties": { "hint": { "type": "string" }, "revision": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "hint", "revision", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "provider", "label", "credential" ], "additionalProperties": false } }, "mayManageProviderKeys": { "type": "boolean" } }, "required": [ "providers", "mayManageProviderKeys" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/provider-keys/{provider}": { "put": { "operationId": "putProviderKey", "summary": "Add or replace an organization provider API key", "tags": [ "Provider API keys" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "openai", "deepgram", "cartesia" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 8, "maxLength": 4096 }, "expectedRevision": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "expectedRevision" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The saved credential metadata. Secret values are never returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "deepgram", "cartesia" ] }, "label": { "type": "string" }, "credential": { "anyOf": [ { "type": "object", "properties": { "hint": { "type": "string" }, "revision": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "hint", "revision", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "provider", "label", "credential" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "delete": { "operationId": "deleteProviderKey", "summary": "Remove an organization provider API key", "tags": [ "Provider API keys" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "openai", "deepgram", "cartesia" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "string" } }, "required": [ "expectedRevision" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The provider with no saved credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "deepgram", "cartesia" ] }, "label": { "type": "string" }, "credential": { "anyOf": [ { "type": "object", "properties": { "hint": { "type": "string" }, "revision": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "hint", "revision", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "provider", "label", "credential" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/agents:discover": { "post": { "operationId": "discoverAgents", "summary": "Discover agents on an agent platform", "description": "List the Retell agents and connection candidates available to a provider API key. Supply credentials.apiKey or an existing agentId. This request does not register agents or save credentials.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "Project to act in. A project-scoped API key already identifies its project." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentPlatform": { "type": "string", "enum": [ "retell" ], "description": "Provider to query. Agent discovery currently supports Retell." }, "credentials": { "type": "object", "description": "Retell account credential for this discovery request. Omit it when using agentId to reuse a saved key.", "properties": { "apiKey": { "type": "string", "description": "Retell API key with access to the agents you want to list.", "examples": [ "YOUR_RETELL_API_KEY" ] } }, "required": [ "apiKey" ], "additionalProperties": false }, "agentId": { "type": "string", "minLength": 1, "description": "Existing Egma agent whose stored Retell key should be used. Omit credentials when supplying this field.", "examples": [ "agt_01M0E4J0BBE1FVDVTZ1BSS5C97" ] } }, "required": [ "agentPlatform" ], "additionalProperties": false, "examples": [ { "agentPlatform": "retell", "credentials": { "apiKey": "YOUR_RETELL_API_KEY" } }, { "agentPlatform": "retell", "agentId": "agt_01M0E4J0BBE1FVDVTZ1BSS5C97" } ] } } } }, "responses": { "200": { "description": "The agents and supported simulation connection candidates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "platformAgentId": { "type": "string" }, "name": { "type": "string" }, "modality": { "type": "string", "enum": [ "chat", "voice" ], "description": "The modality Retell reports for this agent, including when no supported connection candidate is available yet." }, "connectionCandidates": { "type": "array", "items": { "type": "object", "properties": { "agentPlatform": { "type": "string", "enum": [ "retell" ] }, "connectionType": { "type": "string", "enum": [ "retell_text_mode", "retell_web_call", "phone_number" ] }, "accessVariant": { "type": "string", "enum": [ "retell_text_mode.api_key", "retell_web_call.api_key", "phone_number.public_e164" ] }, "modality": { "type": "string", "enum": [ "chat", "voice" ] }, "productLabel": { "type": "string" }, "config": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Confirmed non-secret settings for this candidate. Copy these with its connection type, access variant, and modality when creating the connection." } }, "required": [ "agentPlatform", "connectionType", "accessVariant", "modality", "productLabel", "config" ], "additionalProperties": false } } }, "required": [ "platformAgentId", "name", "modality", "connectionCandidates" ], "additionalProperties": false } } }, "required": [ "agents" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "503": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/connection-options": { "get": { "operationId": "listConnectionOptions", "summary": "List supported connection options", "description": "List the connection options supported by this server. Use each option’s fields and credentialFields to configure an agent connection. This catalog does not check provider accounts or deployment credentials.", "tags": [ "Connections" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "The server-owned connection option catalog.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "agentPlatform": { "anyOf": [ { "type": "string", "enum": [ "retell", "livekit" ] }, { "type": "null" } ] }, "agentPlatformLabel": { "type": "string" }, "connectionType": { "type": "string", "enum": [ "retell_text_mode", "retell_web_call", "phone_number", "livekit_room" ] }, "accessVariant": { "type": "string", "enum": [ "retell_text_mode.api_key", "retell_web_call.api_key", "phone_number.public_e164", "livekit_room.project_credentials", "livekit_room.customer_token_endpoint" ] }, "accessVariantLabel": { "type": "string" }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "productLabel": { "type": "string" }, "topology": { "type": "string", "enum": [ "agent-dials-out", "hosted-broker", "egma-dials-in" ] }, "simulatorAdapter": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Property name to include in the connection request's config object." }, "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "text", "url", "e164", "json" ] }, "required": { "type": "boolean", "description": "Whether this config field must be supplied for the selected option." }, "help": { "type": "string" }, "afterCredentials": { "type": "boolean", "description": "Whether provider credentials are needed before the setup flow can resolve choices for this field." } }, "required": [ "key", "label", "kind", "required", "help", "afterCredentials" ], "additionalProperties": false } }, "credentialRule": { "type": "string", "enum": [ "required", "forbidden", "optional" ], "description": "Whether the connection stores credentials for this access variant. Retell phone setup can still need an agent-level provider key to confirm the phone route." }, "credentialHelp": { "type": "string" }, "credentialFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Property name in the connection request's credentials object." }, "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "secret", "json" ], "description": "Input type. JSON credential values such as headers are encoded as strings containing JSON." }, "required": { "type": "boolean", "description": "Whether this credential field is required for the selected option." }, "help": { "type": "string" } }, "required": [ "field", "label", "kind", "required", "help" ], "additionalProperties": false } } }, "required": [ "agentPlatform", "agentPlatformLabel", "connectionType", "accessVariant", "accessVariantLabel", "modality", "productLabel", "topology", "simulatorAdapter", "fields", "credentialRule", "credentialHelp", "credentialFields" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/agents": { "post": { "operationId": "registerAgent", "summary": "Register an agent", "description": "Register an agent in your project, with an optional first connection. An existing provider identity can be reused. Check result to see whether Egma created an agent, added a connection, or reused one.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "Project to act in. A project-scoped API key already identifies its project." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the agent in Egma.", "examples": [ "Receptionist" ] }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ], "description": "The product or framework that runs your agent." }, "connection": { "type": "object", "description": "Choose one supported agentPlatform, connectionType, accessVariant, and modality from List supported connection options. Its fields describe config and its credentialFields describe credentials. Egma validates the complete combination before saving it.", "properties": { "name": { "type": "string", "description": "Optional connection display name. If omitted, Egma chooses the next available numbered name.", "examples": [ "Staging voice" ] }, "agentPlatform": { "anyOf": [ { "type": "string", "enum": [ "retell", "livekit" ], "description": "The platform that runs the agent. It must be compatible with the selected connection type and agent." }, { "type": "null" } ] }, "connectionType": { "type": "string", "description": "Connection type from the options catalog. Retell text mode tests a voice agent through chat; a Retell web call uses voice. LiveKit room connections can use voice or chat.", "enum": [ "retell_text_mode", "retell_web_call", "phone_number", "livekit_room" ] }, "accessVariant": { "type": "string", "description": "Credential method for the connection type, copied from the same catalog entry.", "enum": [ "retell_text_mode.api_key", "retell_web_call.api_key", "phone_number.public_e164", "livekit_room.project_credentials", "livekit_room.customer_token_endpoint" ] }, "modality": { "type": "string", "enum": [ "voice", "chat" ], "description": "How simulations communicate with the agent. Use a modality offered by the selected catalog entry." }, "environment": { "type": "string", "description": "Optional label identifying the environment this connection reaches.", "examples": [ "staging" ] }, "config": { "type": "object", "additionalProperties": true, "description": "Non-secret settings for the selected access variant. Use only its catalog fields. Retell API variants use retellAgentId; a Retell phone connection uses phoneNumber. LiveKit project credentials use url and agentName. LiveKit token endpoints use tokenEndpoint and agentName; tokenEndpoint must be a public HTTPS URL. agentName must match the name registered by your LiveKit worker. When platformAgentId is supplied for a Retell API variant, Egma derives and confirms retellAgentId from that selection.", "examples": [ { "retellAgentId": "agent_receptionist" }, { "url": "wss://example.livekit.cloud", "agentName": "receptionist" }, { "tokenEndpoint": "https://voice.example.com/egma/token", "agentName": "receptionist" } ] }, "credentials": { "type": "object", "additionalProperties": true, "description": "Secret fields for the selected access variant. Retell uses apiKey. LiveKit project credentials use apiKey and apiSecret. A LiveKit token endpoint requires headers: a JSON-encoded string containing a non-empty object of header names to string values. For an additional Retell connection, platformAgentId can reuse the agent's saved Retell key when credentials are omitted. For a Retell phone connection, the key confirms provider identity and is held on the agent; the phone connection itself stores no key. Responses return credential presence and hints, never the secret values.", "examples": [ { "apiKey": "YOUR_RETELL_API_KEY" }, { "apiKey": "YOUR_LIVEKIT_API_KEY", "apiSecret": "YOUR_LIVEKIT_API_SECRET" }, { "headers": "{\"Authorization\":\"Bearer YOUR_ENDPOINT_TOKEN\"}" } ] }, "platformAgentId": { "type": "string", "description": "Retell's agent ID from Discover agents, not an Egma agent ID. Supply it with the selected candidate to confirm the provider agent and save its identity on the Egma agent. Required for Retell phone connections. Egma uses credentials.apiKey or the key already saved on that agent. A different Retell identity on the same Egma agent is refused. Do not send this together with agentPlatformSelection.", "examples": [ "agent_receptionist" ] }, "pullProductionCalls": { "type": "boolean", "description": "Start pulling this agent's production calls with the same save. Off unless the request says otherwise; the first switch-on imports the fixed 30-day history." }, "agentPlatformSelection": { "type": "object", "description": "Superseded by platformAgentId beside credentials, and still accepted. Egma revalidates the selected provider agent and route during creation, then discards this object.", "properties": { "platformAgentId": { "type": "string" }, "credentials": { "type": "object", "properties": { "apiKey": { "type": "string" } }, "required": [ "apiKey" ], "additionalProperties": false } }, "required": [ "platformAgentId", "credentials" ], "additionalProperties": false } }, "required": [ "agentPlatform", "connectionType", "accessVariant", "modality" ], "additionalProperties": false, "examples": [ { "name": "Retell chat", "agentPlatform": "retell", "connectionType": "retell_text_mode", "accessVariant": "retell_text_mode.api_key", "modality": "chat", "platformAgentId": "agent_receptionist", "config": { "retellAgentId": "agent_receptionist" }, "credentials": { "apiKey": "YOUR_RETELL_API_KEY" } }, { "name": "LiveKit voice", "agentPlatform": "livekit", "connectionType": "livekit_room", "accessVariant": "livekit_room.project_credentials", "modality": "voice", "config": { "url": "wss://example.livekit.cloud", "agentName": "receptionist" }, "credentials": { "apiKey": "YOUR_LIVEKIT_API_KEY", "apiSecret": "YOUR_LIVEKIT_API_SECRET" } }, { "name": "LiveKit token endpoint", "agentPlatform": "livekit", "connectionType": "livekit_room", "accessVariant": "livekit_room.customer_token_endpoint", "modality": "voice", "config": { "tokenEndpoint": "https://voice.example.com/egma/token", "agentName": "receptionist" }, "credentials": { "headers": "{\"Authorization\":\"Bearer YOUR_ENDPOINT_TOKEN\"}" } } ] } }, "required": [ "name", "agentPlatform" ], "additionalProperties": false, "examples": [ { "name": "Receptionist", "agentPlatform": "retell" }, { "name": "Receptionist", "agentPlatform": "livekit", "connection": { "agentPlatform": "livekit", "connectionType": "livekit_room", "accessVariant": "livekit_room.project_credentials", "modality": "voice", "config": { "url": "wss://example.livekit.cloud", "agentName": "receptionist" }, "credentials": { "apiKey": "YOUR_LIVEKIT_API_KEY", "apiSecret": "YOUR_LIVEKIT_API_SECRET" } } } ] } } } }, "responses": { "200": { "description": "An existing agent reused by the registration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "enum": [ "reused" ] }, "agent": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ] }, "platformAgentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retellModality": { "anyOf": [ { "type": "string", "enum": [ "voice", "chat" ] }, { "type": "null" } ] }, "monitoringKeyPresent": { "type": "boolean" }, "monitoringApiKeyHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pullProductionCalls": { "type": "boolean" }, "monitoringConfigured": { "type": "boolean" }, "lastReceivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "name", "agentPlatform", "platformAgentId", "retellModality", "monitoringKeyPresent", "monitoringApiKeyHint", "pullProductionCalls", "monitoringConfigured", "lastReceivedAt", "archived", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "connection": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ] }, "connectionType": { "type": "string", "enum": [ "retell_chat_api", "retell_text_mode", "retell_web_call", "phone_number", "livekit_room" ] }, "accessVariant": { "type": "string", "enum": [ "retell_chat_api.api_key", "retell_text_mode.api_key", "retell_web_call.api_key", "phone_number.public_e164", "livekit_room.project_credentials", "livekit_room.customer_token_endpoint" ] }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "productLabel": { "type": "string" }, "topology": { "type": "string", "enum": [ "agent-dials-out", "hosted-broker", "egma-dials-in" ] }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "config": { "type": "object", "additionalProperties": { "type": "string" } }, "credentialPresent": { "type": "boolean" }, "credentialsHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "projectId", "name", "agentPlatform", "connectionType", "accessVariant", "modality", "productLabel", "topology", "environment", "config", "credentialPresent", "credentialsHint", "archived", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "result", "agent", "connection" ], "additionalProperties": false } } } }, "201": { "description": "An agent or connection created by the registration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "enum": [ "created", "connection_added" ] }, "agent": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ] }, "platformAgentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retellModality": { "anyOf": [ { "type": "string", "enum": [ "voice", "chat" ] }, { "type": "null" } ] }, "monitoringKeyPresent": { "type": "boolean" }, "monitoringApiKeyHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pullProductionCalls": { "type": "boolean" }, "monitoringConfigured": { "type": "boolean" }, "lastReceivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "name", "agentPlatform", "platformAgentId", "retellModality", "monitoringKeyPresent", "monitoringApiKeyHint", "pullProductionCalls", "monitoringConfigured", "lastReceivedAt", "archived", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "connection": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ] }, "connectionType": { "type": "string", "enum": [ "retell_chat_api", "retell_text_mode", "retell_web_call", "phone_number", "livekit_room" ] }, "accessVariant": { "type": "string", "enum": [ "retell_chat_api.api_key", "retell_text_mode.api_key", "retell_web_call.api_key", "phone_number.public_e164", "livekit_room.project_credentials", "livekit_room.customer_token_endpoint" ] }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "productLabel": { "type": "string" }, "topology": { "type": "string", "enum": [ "agent-dials-out", "hosted-broker", "egma-dials-in" ] }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "config": { "type": "object", "additionalProperties": { "type": "string" } }, "credentialPresent": { "type": "boolean" }, "credentialsHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "projectId", "name", "agentPlatform", "connectionType", "accessVariant", "modality", "productLabel", "topology", "environment", "config", "credentialPresent", "credentialsHint", "archived", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "result", "agent" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "503": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "get": { "operationId": "listAgents", "summary": "List agents", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "archived", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "One page of agents and their active connections.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ] }, "platformAgentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retellModality": { "anyOf": [ { "type": "string", "enum": [ "voice", "chat" ] }, { "type": "null" } ] }, "monitoringKeyPresent": { "type": "boolean" }, "monitoringApiKeyHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pullProductionCalls": { "type": "boolean" }, "monitoringConfigured": { "type": "boolean" }, "lastReceivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ] }, "connectionType": { "type": "string", "enum": [ "retell_chat_api", "retell_text_mode", "retell_web_call", "phone_number", "livekit_room" ] }, "accessVariant": { "type": "string", "enum": [ "retell_chat_api.api_key", "retell_text_mode.api_key", "retell_web_call.api_key", "phone_number.public_e164", "livekit_room.project_credentials", "livekit_room.customer_token_endpoint" ] }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "productLabel": { "type": "string" }, "topology": { "type": "string", "enum": [ "agent-dials-out", "hosted-broker", "egma-dials-in" ] }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "config": { "type": "object", "additionalProperties": { "type": "string" } }, "credentialPresent": { "type": "boolean" }, "credentialsHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "projectId", "name", "agentPlatform", "connectionType", "accessVariant", "modality", "productLabel", "topology", "environment", "config", "credentialPresent", "credentialsHint", "archived", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "id", "projectId", "name", "agentPlatform", "platformAgentId", "retellModality", "monitoringKeyPresent", "monitoringApiKeyHint", "pullProductionCalls", "monitoringConfigured", "lastReceivedAt", "archived", "archivedAt", "createdAt", "updatedAt", "connections" ], "additionalProperties": false } }, "nextPageToken": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "agents", "nextPageToken" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/agents/{agentId}": { "get": { "operationId": "getAgent", "summary": "Get an agent", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The Egma agent ID returned by Register an agent or List agents.", "examples": [ "agt_01M0E4J0BBE1FVDVTZ1BSS5C97" ] } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "archived", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "The agent and the requested set of connections.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ] }, "platformAgentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retellModality": { "anyOf": [ { "type": "string", "enum": [ "voice", "chat" ] }, { "type": "null" } ] }, "monitoringKeyPresent": { "type": "boolean" }, "monitoringApiKeyHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pullProductionCalls": { "type": "boolean" }, "monitoringConfigured": { "type": "boolean" }, "lastReceivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "name", "agentPlatform", "platformAgentId", "retellModality", "monitoringKeyPresent", "monitoringApiKeyHint", "pullProductionCalls", "monitoringConfigured", "lastReceivedAt", "archived", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ] }, "connectionType": { "type": "string", "enum": [ "retell_chat_api", "retell_text_mode", "retell_web_call", "phone_number", "livekit_room" ] }, "accessVariant": { "type": "string", "enum": [ "retell_chat_api.api_key", "retell_text_mode.api_key", "retell_web_call.api_key", "phone_number.public_e164", "livekit_room.project_credentials", "livekit_room.customer_token_endpoint" ] }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "productLabel": { "type": "string" }, "topology": { "type": "string", "enum": [ "agent-dials-out", "hosted-broker", "egma-dials-in" ] }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "config": { "type": "object", "additionalProperties": { "type": "string" } }, "credentialPresent": { "type": "boolean" }, "credentialsHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "projectId", "name", "agentPlatform", "connectionType", "accessVariant", "modality", "productLabel", "topology", "environment", "config", "credentialPresent", "credentialsHint", "archived", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "agent", "connections" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "patch": { "operationId": "updateAgent", "summary": "Update an agent", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The Egma agent ID returned by Register an agent or List agents.", "examples": [ "agt_01M0E4J0BBE1FVDVTZ1BSS5C97" ] } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "Project to act in. A project-scoped API key already identifies its project." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The updated agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ] }, "platformAgentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retellModality": { "anyOf": [ { "type": "string", "enum": [ "voice", "chat" ] }, { "type": "null" } ] }, "monitoringKeyPresent": { "type": "boolean" }, "monitoringApiKeyHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pullProductionCalls": { "type": "boolean" }, "monitoringConfigured": { "type": "boolean" }, "lastReceivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "name", "agentPlatform", "platformAgentId", "retellModality", "monitoringKeyPresent", "monitoringApiKeyHint", "pullProductionCalls", "monitoringConfigured", "lastReceivedAt", "archived", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "agent" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "503": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/agents/{agentId}/connections": { "post": { "operationId": "addConnection", "summary": "Add an agent connection", "description": "Add a simulation connection to an agent. Use the connection catalog for required fields, Retell discovery for platformAgentId, or your LiveKit worker’s dispatch name for config.agentName.", "tags": [ "Connections" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The Egma agent ID returned by Register an agent or List agents.", "examples": [ "agt_01M0E4J0BBE1FVDVTZ1BSS5C97" ] } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "Project to act in. A project-scoped API key already identifies its project." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Choose one supported agentPlatform, connectionType, accessVariant, and modality from List supported connection options. Its fields describe config and its credentialFields describe credentials. Egma validates the complete combination before saving it.", "properties": { "name": { "type": "string", "description": "Optional connection display name. If omitted, Egma chooses the next available numbered name.", "examples": [ "Staging voice" ] }, "agentPlatform": { "anyOf": [ { "type": "string", "enum": [ "retell", "livekit" ], "description": "The platform that runs the agent. It must be compatible with the selected connection type and agent." }, { "type": "null" } ] }, "connectionType": { "type": "string", "description": "Connection type from the options catalog. Retell text mode tests a voice agent through chat; a Retell web call uses voice. LiveKit room connections can use voice or chat.", "enum": [ "retell_text_mode", "retell_web_call", "phone_number", "livekit_room" ] }, "accessVariant": { "type": "string", "description": "Credential method for the connection type, copied from the same catalog entry.", "enum": [ "retell_text_mode.api_key", "retell_web_call.api_key", "phone_number.public_e164", "livekit_room.project_credentials", "livekit_room.customer_token_endpoint" ] }, "modality": { "type": "string", "enum": [ "voice", "chat" ], "description": "How simulations communicate with the agent. Use a modality offered by the selected catalog entry." }, "environment": { "type": "string", "description": "Optional label identifying the environment this connection reaches.", "examples": [ "staging" ] }, "config": { "type": "object", "additionalProperties": true, "description": "Non-secret settings for the selected access variant. Use only its catalog fields. Retell API variants use retellAgentId; a Retell phone connection uses phoneNumber. LiveKit project credentials use url and agentName. LiveKit token endpoints use tokenEndpoint and agentName; tokenEndpoint must be a public HTTPS URL. agentName must match the name registered by your LiveKit worker. When platformAgentId is supplied for a Retell API variant, Egma derives and confirms retellAgentId from that selection.", "examples": [ { "retellAgentId": "agent_receptionist" }, { "url": "wss://example.livekit.cloud", "agentName": "receptionist" }, { "tokenEndpoint": "https://voice.example.com/egma/token", "agentName": "receptionist" } ] }, "credentials": { "type": "object", "additionalProperties": true, "description": "Secret fields for the selected access variant. Retell uses apiKey. LiveKit project credentials use apiKey and apiSecret. A LiveKit token endpoint requires headers: a JSON-encoded string containing a non-empty object of header names to string values. For an additional Retell connection, platformAgentId can reuse the agent's saved Retell key when credentials are omitted. For a Retell phone connection, the key confirms provider identity and is held on the agent; the phone connection itself stores no key. Responses return credential presence and hints, never the secret values.", "examples": [ { "apiKey": "YOUR_RETELL_API_KEY" }, { "apiKey": "YOUR_LIVEKIT_API_KEY", "apiSecret": "YOUR_LIVEKIT_API_SECRET" }, { "headers": "{\"Authorization\":\"Bearer YOUR_ENDPOINT_TOKEN\"}" } ] }, "platformAgentId": { "type": "string", "description": "Retell's agent ID from Discover agents, not an Egma agent ID. Supply it with the selected candidate to confirm the provider agent and save its identity on the Egma agent. Required for Retell phone connections. Egma uses credentials.apiKey or the key already saved on that agent. A different Retell identity on the same Egma agent is refused. Do not send this together with agentPlatformSelection.", "examples": [ "agent_receptionist" ] }, "pullProductionCalls": { "type": "boolean", "description": "Start pulling this agent's production calls with the same save. Off unless the request says otherwise; the first switch-on imports the fixed 30-day history." }, "agentPlatformSelection": { "type": "object", "description": "Superseded by platformAgentId beside credentials, and still accepted. Egma revalidates the selected provider agent and route during creation, then discards this object.", "properties": { "platformAgentId": { "type": "string" }, "credentials": { "type": "object", "properties": { "apiKey": { "type": "string" } }, "required": [ "apiKey" ], "additionalProperties": false } }, "required": [ "platformAgentId", "credentials" ], "additionalProperties": false } }, "required": [ "agentPlatform", "connectionType", "accessVariant", "modality" ], "additionalProperties": false, "examples": [ { "name": "Retell chat", "agentPlatform": "retell", "connectionType": "retell_text_mode", "accessVariant": "retell_text_mode.api_key", "modality": "chat", "platformAgentId": "agent_receptionist", "config": { "retellAgentId": "agent_receptionist" }, "credentials": { "apiKey": "YOUR_RETELL_API_KEY" } }, { "name": "LiveKit voice", "agentPlatform": "livekit", "connectionType": "livekit_room", "accessVariant": "livekit_room.project_credentials", "modality": "voice", "config": { "url": "wss://example.livekit.cloud", "agentName": "receptionist" }, "credentials": { "apiKey": "YOUR_LIVEKIT_API_KEY", "apiSecret": "YOUR_LIVEKIT_API_SECRET" } }, { "name": "LiveKit token endpoint", "agentPlatform": "livekit", "connectionType": "livekit_room", "accessVariant": "livekit_room.customer_token_endpoint", "modality": "voice", "config": { "tokenEndpoint": "https://voice.example.com/egma/token", "agentName": "receptionist" }, "credentials": { "headers": "{\"Authorization\":\"Bearer YOUR_ENDPOINT_TOKEN\"}" } } ] } } } }, "responses": { "201": { "description": "The new connection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ] }, "connectionType": { "type": "string", "enum": [ "retell_chat_api", "retell_text_mode", "retell_web_call", "phone_number", "livekit_room" ] }, "accessVariant": { "type": "string", "enum": [ "retell_chat_api.api_key", "retell_text_mode.api_key", "retell_web_call.api_key", "phone_number.public_e164", "livekit_room.project_credentials", "livekit_room.customer_token_endpoint" ] }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "productLabel": { "type": "string" }, "topology": { "type": "string", "enum": [ "agent-dials-out", "hosted-broker", "egma-dials-in" ] }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "config": { "type": "object", "additionalProperties": { "type": "string" } }, "credentialPresent": { "type": "boolean" }, "credentialsHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "projectId", "name", "agentPlatform", "connectionType", "accessVariant", "modality", "productLabel", "topology", "environment", "config", "credentialPresent", "credentialsHint", "archived", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "connection" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "503": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/agents/{agentId}/archive": { "post": { "operationId": "archiveAgent", "summary": "Archive an agent", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The Egma agent ID returned by Register an agent or List agents.", "examples": [ "agt_01M0E4J0BBE1FVDVTZ1BSS5C97" ] } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "Project to act in. A project-scoped API key already identifies its project." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "The archived agent and the work stopped with it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ] }, "platformAgentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retellModality": { "anyOf": [ { "type": "string", "enum": [ "voice", "chat" ] }, { "type": "null" } ] }, "monitoringKeyPresent": { "type": "boolean" }, "monitoringApiKeyHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pullProductionCalls": { "type": "boolean" }, "monitoringConfigured": { "type": "boolean" }, "lastReceivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "name", "agentPlatform", "platformAgentId", "retellModality", "monitoringKeyPresent", "monitoringApiKeyHint", "pullProductionCalls", "monitoringConfigured", "lastReceivedAt", "archived", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "archivedConnections": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "canceledRunCount": { "type": "integer", "minimum": 0 } }, "required": [ "agent", "archivedConnections", "canceledRunCount" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "503": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/agents/{agentId}/restore": { "post": { "operationId": "restoreAgent", "summary": "Restore an agent", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The Egma agent ID returned by Register an agent or List agents.", "examples": [ "agt_01M0E4J0BBE1FVDVTZ1BSS5C97" ] } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "Project to act in. A project-scoped API key already identifies its project." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The restored agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ] }, "platformAgentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retellModality": { "anyOf": [ { "type": "string", "enum": [ "voice", "chat" ] }, { "type": "null" } ] }, "monitoringKeyPresent": { "type": "boolean" }, "monitoringApiKeyHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pullProductionCalls": { "type": "boolean" }, "monitoringConfigured": { "type": "boolean" }, "lastReceivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "name", "agentPlatform", "platformAgentId", "retellModality", "monitoringKeyPresent", "monitoringApiKeyHint", "pullProductionCalls", "monitoringConfigured", "lastReceivedAt", "archived", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "agent" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "503": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/agents/{agentId}/connections/{connectionId}": { "get": { "operationId": "getConnection", "summary": "Get an agent connection", "tags": [ "Connections" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "Project to act in. A project-scoped API key already identifies its project." } } ], "responses": { "200": { "description": "The connection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ] }, "connectionType": { "type": "string", "enum": [ "retell_chat_api", "retell_text_mode", "retell_web_call", "phone_number", "livekit_room" ] }, "accessVariant": { "type": "string", "enum": [ "retell_chat_api.api_key", "retell_text_mode.api_key", "retell_web_call.api_key", "phone_number.public_e164", "livekit_room.project_credentials", "livekit_room.customer_token_endpoint" ] }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "productLabel": { "type": "string" }, "topology": { "type": "string", "enum": [ "agent-dials-out", "hosted-broker", "egma-dials-in" ] }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "config": { "type": "object", "additionalProperties": { "type": "string" } }, "credentialPresent": { "type": "boolean" }, "credentialsHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "projectId", "name", "agentPlatform", "connectionType", "accessVariant", "modality", "productLabel", "topology", "environment", "config", "credentialPresent", "credentialsHint", "archived", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "connection" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "patch": { "operationId": "updateConnection", "summary": "Update an agent connection", "tags": [ "Connections" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "Project to act in. A project-scoped API key already identifies its project." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "config": { "type": "object", "additionalProperties": true }, "credentials": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The updated connection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ] }, "connectionType": { "type": "string", "enum": [ "retell_chat_api", "retell_text_mode", "retell_web_call", "phone_number", "livekit_room" ] }, "accessVariant": { "type": "string", "enum": [ "retell_chat_api.api_key", "retell_text_mode.api_key", "retell_web_call.api_key", "phone_number.public_e164", "livekit_room.project_credentials", "livekit_room.customer_token_endpoint" ] }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "productLabel": { "type": "string" }, "topology": { "type": "string", "enum": [ "agent-dials-out", "hosted-broker", "egma-dials-in" ] }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "config": { "type": "object", "additionalProperties": { "type": "string" } }, "credentialPresent": { "type": "boolean" }, "credentialsHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "projectId", "name", "agentPlatform", "connectionType", "accessVariant", "modality", "productLabel", "topology", "environment", "config", "credentialPresent", "credentialsHint", "archived", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "connection" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "503": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/agents/{agentId}/connections/{connectionId}/archive": { "post": { "operationId": "archiveConnection", "summary": "Archive an agent connection", "tags": [ "Connections" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "Project to act in. A project-scoped API key already identifies its project." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "The archived connection and the runs stopped with it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ] }, "connectionType": { "type": "string", "enum": [ "retell_chat_api", "retell_text_mode", "retell_web_call", "phone_number", "livekit_room" ] }, "accessVariant": { "type": "string", "enum": [ "retell_chat_api.api_key", "retell_text_mode.api_key", "retell_web_call.api_key", "phone_number.public_e164", "livekit_room.project_credentials", "livekit_room.customer_token_endpoint" ] }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "productLabel": { "type": "string" }, "topology": { "type": "string", "enum": [ "agent-dials-out", "hosted-broker", "egma-dials-in" ] }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "config": { "type": "object", "additionalProperties": { "type": "string" } }, "credentialPresent": { "type": "boolean" }, "credentialsHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "projectId", "name", "agentPlatform", "connectionType", "accessVariant", "modality", "productLabel", "topology", "environment", "config", "credentialPresent", "credentialsHint", "archived", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "canceledRunCount": { "type": "integer", "minimum": 0 } }, "required": [ "connection", "canceledRunCount" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "503": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/agents/{agentId}/connections/{connectionId}/restore": { "post": { "operationId": "restoreConnection", "summary": "Restore an agent connection", "tags": [ "Connections" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "Project to act in. A project-scoped API key already identifies its project." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "credential": { "oneOf": [ { "type": "object", "properties": { "choice": { "const": "replace" }, "credentials": { "type": "object", "additionalProperties": true } }, "required": [ "choice", "credentials" ], "additionalProperties": false }, { "type": "object", "properties": { "choice": { "const": "clear" } }, "required": [ "choice" ], "additionalProperties": false } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The restored connection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ] }, "connectionType": { "type": "string", "enum": [ "retell_chat_api", "retell_text_mode", "retell_web_call", "phone_number", "livekit_room" ] }, "accessVariant": { "type": "string", "enum": [ "retell_chat_api.api_key", "retell_text_mode.api_key", "retell_web_call.api_key", "phone_number.public_e164", "livekit_room.project_credentials", "livekit_room.customer_token_endpoint" ] }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "productLabel": { "type": "string" }, "topology": { "type": "string", "enum": [ "agent-dials-out", "hosted-broker", "egma-dials-in" ] }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "config": { "type": "object", "additionalProperties": { "type": "string" } }, "credentialPresent": { "type": "boolean" }, "credentialsHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "projectId", "name", "agentPlatform", "connectionType", "accessVariant", "modality", "productLabel", "topology", "environment", "config", "credentialPresent", "credentialsHint", "archived", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "connection" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "503": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/keys": { "get": { "operationId": "listApiKeys", "summary": "List API keys", "tags": [ "API keys" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "The API keys visible to the requester.", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope": { "type": "string", "enum": [ "organization", "project" ] }, "organizationId": { "type": "string", "minLength": 1 }, "projectId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "looksLike": { "type": "string" }, "createdByUserId": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdByEmail": { "type": "string" } }, "required": [ "id", "name", "scope", "organizationId", "projectId", "looksLike", "createdByUserId", "createdAt", "lastUsedAt", "revokedAt", "createdByEmail" ], "additionalProperties": false } } }, "required": [ "keys" ], "additionalProperties": false } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "post": { "operationId": "createApiKey", "summary": "Create an API key", "tags": [ "API keys" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "projectId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "monitoringAgentId": { "type": "string", "minLength": 1, "description": "The living LiveKit agent this worker key serves. Egma derives and reserves its key-name prefix on the server." } }, "required": [ "name", "projectId", "monitoringAgentId" ], "additionalProperties": false } ] } } } }, "responses": { "201": { "description": "The new API key and its one-time secret.", "headers": { "Cache-Control": { "description": "Prevents storage of the one-time secret response.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope": { "type": "string", "enum": [ "organization", "project" ] }, "organizationId": { "type": "string", "minLength": 1 }, "projectId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "looksLike": { "type": "string" }, "createdByUserId": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "secret": { "type": "string" } }, "required": [ "id", "name", "scope", "organizationId", "projectId", "looksLike", "createdByUserId", "createdAt", "lastUsedAt", "revokedAt", "secret" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/keys/{apiKeyId}/revoke": { "post": { "operationId": "revokeApiKey", "summary": "Revoke an API key", "tags": [ "API keys" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "apiKeyId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope": { "type": "string", "enum": [ "organization", "project" ] }, "organizationId": { "type": "string", "minLength": 1 }, "projectId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "looksLike": { "type": "string" }, "createdByUserId": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "scope", "organizationId", "projectId", "looksLike", "createdByUserId", "createdAt", "lastUsedAt", "revokedAt" ], "additionalProperties": false } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/grader-form": { "get": { "operationId": "getGraderForm", "summary": "Get grader model choices", "description": "Read supported provider/model pairs and default settings before creating or configuring an LLM grader.", "tags": [ "Graders" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Supported grader model pairs and the default LLM contract.", "content": { "application/json": { "schema": { "type": "object", "properties": { "modelCatalog": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "label": { "type": "string" } }, "required": [ "provider", "model", "label" ], "additionalProperties": false } }, "settingDefinitions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "valueType": { "type": "string", "enum": [ "integer", "number", "string" ] }, "defaultValue": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "key", "label", "valueType", "defaultValue", "unit", "minimum", "maximum" ], "additionalProperties": false } } }, "required": [ "modelCatalog", "settingDefinitions" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/grader-library": { "get": { "operationId": "listGraderLibrary", "summary": "List the grader library for a project", "description": "Includes Egma's built-in graders and custom graders owned by this project. activeProjectGraderId identifies a definition already in use by this project; null means it can be added.", "tags": [ "Graders" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Grader definitions visible to the project, with current-project use state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "graderLibraryEntries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "owner": { "type": "string", "enum": [ "egma", "project" ] }, "type": { "type": "string", "enum": [ "llm_as_judge", "code" ] }, "scopeEditable": { "type": "boolean" }, "currentDefinitionVersion": { "type": "integer", "minimum": 1 }, "definitionVersion": { "type": "integer", "minimum": 1 }, "modalities": { "type": "array", "items": { "type": "string", "enum": [ "chat", "voice" ] }, "minItems": 1, "uniqueItems": true }, "gradingInstructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requiredEvidence": { "type": "array", "items": { "type": "string", "enum": [ "transcript", "ending_outcome", "tool_calls", "observed_metrics", "test_expected_behaviors", "turn_response_latency" ] } }, "settingDefinitions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "valueType": { "type": "string", "enum": [ "integer", "number", "string" ] }, "defaultValue": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "key", "label", "valueType", "defaultValue", "unit", "minimum", "maximum" ], "additionalProperties": false } }, "activeProjectGraderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "owner", "type", "scopeEditable", "currentDefinitionVersion", "definitionVersion", "modalities", "gradingInstructions", "requiredEvidence", "settingDefinitions", "activeProjectGraderId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextPageToken": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "graderLibraryEntries", "nextPageToken" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/grader-library/{graderDefinitionId}": { "get": { "operationId": "getGraderLibraryEntry", "summary": "Get one grader library entry", "description": "Read the current definition or request an exact definitionVersion from historical grade evidence. Setting definitions describe the values needed when adding the grader to a project.", "tags": [ "Graders" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "graderDefinitionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "definitionVersion", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "The grader definition and its current-project use state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "owner": { "type": "string", "enum": [ "egma", "project" ] }, "type": { "type": "string", "enum": [ "llm_as_judge", "code" ] }, "scopeEditable": { "type": "boolean" }, "currentDefinitionVersion": { "type": "integer", "minimum": 1 }, "definitionVersion": { "type": "integer", "minimum": 1 }, "modalities": { "type": "array", "items": { "type": "string", "enum": [ "chat", "voice" ] }, "minItems": 1, "uniqueItems": true }, "gradingInstructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requiredEvidence": { "type": "array", "items": { "type": "string", "enum": [ "transcript", "ending_outcome", "tool_calls", "observed_metrics", "test_expected_behaviors", "turn_response_latency" ] } }, "settingDefinitions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "valueType": { "type": "string", "enum": [ "integer", "number", "string" ] }, "defaultValue": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "key", "label", "valueType", "defaultValue", "unit", "minimum", "maximum" ], "additionalProperties": false } }, "activeProjectGraderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "owner", "type", "scopeEditable", "currentDefinitionVersion", "definitionVersion", "modalities", "gradingInstructions", "requiredEvidence", "settingDefinitions", "activeProjectGraderId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "patch": { "operationId": "updateGraderDefinition", "summary": "Update grader instructions", "description": "Edit the current custom definition's prompt or display labels. Send its definitionVersion as baseDefinitionVersion. A changed prompt creates a version; label edits do not. Egma-owned definitions are read-only.", "tags": [ "Graders" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "graderDefinitionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "baseDefinitionVersion": { "type": "integer", "minimum": 1 }, "gradingInstructions": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "baseDefinitionVersion" ], "minProperties": 2, "additionalProperties": false } } } }, "responses": { "200": { "description": "The current core. A prompt change creates the next immutable version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "owner": { "type": "string", "enum": [ "egma", "project" ] }, "type": { "type": "string", "enum": [ "llm_as_judge", "code" ] }, "scopeEditable": { "type": "boolean" }, "currentDefinitionVersion": { "type": "integer", "minimum": 1 }, "definitionVersion": { "type": "integer", "minimum": 1 }, "modalities": { "type": "array", "items": { "type": "string", "enum": [ "chat", "voice" ] }, "minItems": 1, "uniqueItems": true }, "gradingInstructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requiredEvidence": { "type": "array", "items": { "type": "string", "enum": [ "transcript", "ending_outcome", "tool_calls", "observed_metrics", "test_expected_behaviors", "turn_response_latency" ] } }, "settingDefinitions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "valueType": { "type": "string", "enum": [ "integer", "number", "string" ] }, "defaultValue": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "key", "label", "valueType", "defaultValue", "unit", "minimum", "maximum" ], "additionalProperties": false } }, "activeProjectGraderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "owner", "type", "scopeEditable", "currentDefinitionVersion", "definitionVersion", "modalities", "gradingInstructions", "requiredEvidence", "settingDefinitions", "activeProjectGraderId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/grader-library/{graderDefinitionId}/use": { "post": { "operationId": "useGraderInProject", "summary": "Use a grader in the current project", "description": "Adds an available definition with this project's scope, settings, and pass threshold. These settings apply to future work; adding a grader does not change earlier simulation plans. A definition can be active only once per project. The example settings are for Response latency.", "tags": [ "Graders" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "graderDefinitionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "object", "properties": { "simulations": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "all" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "test_suite" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "test" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false } ] } }, "production": { "anyOf": [ { "type": "object", "properties": { "samplePercent": { "type": "number", "minimum": 1, "maximum": 100 } }, "required": [ "samplePercent" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "simulations", "production" ], "additionalProperties": false, "description": "Select all simulations, particular test suites or tests, and/or a production sample from 1 through 100 percent. production: null disables production grading." }, "settings": { "type": "object", "additionalProperties": true, "description": "Complete values for the definition's settingDefinitions. Omit settings to save the declared defaults on first use. LLM graders use llm_provider and llm_model; Response latency uses maximum_response_time_ms." }, "passThreshold": { "type": "number", "minimum": 0, "maximum": 1, "description": "The minimum score for this grader's individual result to pass." } }, "required": [ "scope", "passThreshold" ], "additionalProperties": false, "examples": [ { "scope": { "simulations": [ { "kind": "all" } ], "production": null }, "settings": { "maximum_response_time_ms": 3000 }, "passThreshold": 1 } ] } } } }, "responses": { "201": { "description": "The new current-project grader policy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "graderDefinitionId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "owner": { "type": "string", "enum": [ "egma", "project" ] }, "type": { "type": "string", "enum": [ "llm_as_judge", "code" ] }, "modalities": { "type": "array", "items": { "type": "string", "enum": [ "chat", "voice" ] }, "minItems": 1, "uniqueItems": true }, "scopeEditable": { "type": "boolean" }, "removable": { "type": "boolean" }, "scope": { "type": "object", "properties": { "simulations": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "all" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "test_suite" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "test" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false } ] } }, "production": { "anyOf": [ { "type": "object", "properties": { "samplePercent": { "type": "number", "minimum": 1, "maximum": 100 } }, "required": [ "samplePercent" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "simulations", "production" ], "additionalProperties": false }, "settings": { "type": "object", "additionalProperties": true }, "passThreshold": { "type": "number", "minimum": 0, "maximum": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "graderDefinitionId", "name", "description", "owner", "type", "modalities", "scopeEditable", "removable", "scope", "settings", "passThreshold", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/grader-library/custom": { "post": { "operationId": "createCustomGrader", "summary": "Create and use a custom LLM grader", "description": "Create a custom LLM grader owned by this project. Set its instructions, model, scope, and pass threshold. Omit settings to save the declared model defaults at creation.", "tags": [ "Graders" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gradingInstructions": { "type": "string", "description": "One rule to decide and the conversation evidence to inspect." }, "passesWhen": { "type": "string", "description": "The evidence that makes the rule pass. Include how to handle a conversation where the checked action never occurs." }, "failsWhen": { "type": "string", "description": "The evidence that makes the rule fail." }, "settings": { "type": "object", "additionalProperties": true, "description": "A complete llm_provider and llm_model pair from Get grader model choices. Omit settings to use the declared defaults." }, "scope": { "type": "object", "properties": { "simulations": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "all" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "test_suite" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "test" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false } ] } }, "production": { "anyOf": [ { "type": "object", "properties": { "samplePercent": { "type": "number", "minimum": 1, "maximum": 100 } }, "required": [ "samplePercent" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "simulations", "production" ], "additionalProperties": false, "description": "The future simulations and/or production sample this project should grade." }, "passThreshold": { "type": "number", "minimum": 0, "maximum": 1, "description": "The minimum score for this grader's individual result to pass." } }, "required": [ "name", "gradingInstructions", "passesWhen", "failsWhen", "scope", "passThreshold" ], "additionalProperties": false, "examples": [ { "name": "Appointment recap", "gradingInstructions": "Decide whether the agent repeats the chosen appointment date and time and asks the caller to confirm them. Use the transcript.", "passesWhen": "The agent repeats the chosen date and time and asks for confirmation. If no appointment is chosen, the rule is met.", "failsWhen": "An appointment is chosen and the agent ends the conversation without repeating both its date and time and asking for confirmation.", "scope": { "simulations": [ { "kind": "all" } ], "production": null }, "passThreshold": 1 } ] } } } }, "responses": { "201": { "description": "The custom definition and its current-project policy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "definition": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "owner": { "type": "string", "enum": [ "egma", "project" ] }, "type": { "type": "string", "enum": [ "llm_as_judge", "code" ] }, "scopeEditable": { "type": "boolean" }, "currentDefinitionVersion": { "type": "integer", "minimum": 1 }, "definitionVersion": { "type": "integer", "minimum": 1 }, "modalities": { "type": "array", "items": { "type": "string", "enum": [ "chat", "voice" ] }, "minItems": 1, "uniqueItems": true }, "gradingInstructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requiredEvidence": { "type": "array", "items": { "type": "string", "enum": [ "transcript", "ending_outcome", "tool_calls", "observed_metrics", "test_expected_behaviors", "turn_response_latency" ] } }, "settingDefinitions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "valueType": { "type": "string", "enum": [ "integer", "number", "string" ] }, "defaultValue": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "key", "label", "valueType", "defaultValue", "unit", "minimum", "maximum" ], "additionalProperties": false } }, "activeProjectGraderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "owner", "type", "scopeEditable", "currentDefinitionVersion", "definitionVersion", "modalities", "gradingInstructions", "requiredEvidence", "settingDefinitions", "activeProjectGraderId", "createdAt", "updatedAt" ], "additionalProperties": false }, "grader": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "graderDefinitionId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "owner": { "type": "string", "enum": [ "egma", "project" ] }, "type": { "type": "string", "enum": [ "llm_as_judge", "code" ] }, "modalities": { "type": "array", "items": { "type": "string", "enum": [ "chat", "voice" ] }, "minItems": 1, "uniqueItems": true }, "scopeEditable": { "type": "boolean" }, "removable": { "type": "boolean" }, "scope": { "type": "object", "properties": { "simulations": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "all" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "test_suite" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "test" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false } ] } }, "production": { "anyOf": [ { "type": "object", "properties": { "samplePercent": { "type": "number", "minimum": 1, "maximum": 100 } }, "required": [ "samplePercent" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "simulations", "production" ], "additionalProperties": false }, "settings": { "type": "object", "additionalProperties": true }, "passThreshold": { "type": "number", "minimum": 0, "maximum": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "graderDefinitionId", "name", "description", "owner", "type", "modalities", "scopeEditable", "removable", "scope", "settings", "passThreshold", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "definition", "grader" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/grader-library/{graderDefinitionId}/clone": { "post": { "operationId": "cloneGrader", "summary": "Clone a grader", "description": "Copy the current LLM definition and this project's effective settings into an independent custom grader. Historical versions and code graders cannot be cloned. The clone receives no source updates.", "tags": [ "Graders" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "graderDefinitionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "The independent custom definition and its copied project settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "definition": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "owner": { "type": "string", "enum": [ "egma", "project" ] }, "type": { "type": "string", "enum": [ "llm_as_judge", "code" ] }, "scopeEditable": { "type": "boolean" }, "currentDefinitionVersion": { "type": "integer", "minimum": 1 }, "definitionVersion": { "type": "integer", "minimum": 1 }, "modalities": { "type": "array", "items": { "type": "string", "enum": [ "chat", "voice" ] }, "minItems": 1, "uniqueItems": true }, "gradingInstructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requiredEvidence": { "type": "array", "items": { "type": "string", "enum": [ "transcript", "ending_outcome", "tool_calls", "observed_metrics", "test_expected_behaviors", "turn_response_latency" ] } }, "settingDefinitions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "valueType": { "type": "string", "enum": [ "integer", "number", "string" ] }, "defaultValue": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "key", "label", "valueType", "defaultValue", "unit", "minimum", "maximum" ], "additionalProperties": false } }, "activeProjectGraderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "owner", "type", "scopeEditable", "currentDefinitionVersion", "definitionVersion", "modalities", "gradingInstructions", "requiredEvidence", "settingDefinitions", "activeProjectGraderId", "createdAt", "updatedAt" ], "additionalProperties": false }, "grader": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "graderDefinitionId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "owner": { "type": "string", "enum": [ "egma", "project" ] }, "type": { "type": "string", "enum": [ "llm_as_judge", "code" ] }, "modalities": { "type": "array", "items": { "type": "string", "enum": [ "chat", "voice" ] }, "minItems": 1, "uniqueItems": true }, "scopeEditable": { "type": "boolean" }, "removable": { "type": "boolean" }, "scope": { "type": "object", "properties": { "simulations": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "all" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "test_suite" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "test" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false } ] } }, "production": { "anyOf": [ { "type": "object", "properties": { "samplePercent": { "type": "number", "minimum": 1, "maximum": 100 } }, "required": [ "samplePercent" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "simulations", "production" ], "additionalProperties": false }, "settings": { "type": "object", "additionalProperties": true }, "passThreshold": { "type": "number", "minimum": 0, "maximum": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "graderDefinitionId", "name", "description", "owner", "type", "modalities", "scopeEditable", "removable", "scope", "settings", "passThreshold", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "definition", "grader" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/graders": { "get": { "operationId": "listGraders", "summary": "List project graders", "description": "Returns active project policies, including scope, settings, and individual pass thresholds. Use /v1/grader-library to find definitions that are not yet active in this project.", "tags": [ "Graders" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Project graders, ordered by name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "graders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "graderDefinitionId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "owner": { "type": "string", "enum": [ "egma", "project" ] }, "type": { "type": "string", "enum": [ "llm_as_judge", "code" ] }, "modalities": { "type": "array", "items": { "type": "string", "enum": [ "chat", "voice" ] }, "minItems": 1, "uniqueItems": true }, "scopeEditable": { "type": "boolean" }, "removable": { "type": "boolean" }, "scope": { "type": "object", "properties": { "simulations": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "all" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "test_suite" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "test" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false } ] } }, "production": { "anyOf": [ { "type": "object", "properties": { "samplePercent": { "type": "number", "minimum": 1, "maximum": 100 } }, "required": [ "samplePercent" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "simulations", "production" ], "additionalProperties": false }, "settings": { "type": "object", "additionalProperties": true }, "passThreshold": { "type": "number", "minimum": 0, "maximum": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "graderDefinitionId", "name", "description", "owner", "type", "modalities", "scopeEditable", "removable", "scope", "settings", "passThreshold", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextPageToken": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "graders", "nextPageToken" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/graders/{graderId}": { "patch": { "operationId": "updateGrader", "summary": "Update a project grader's policy", "description": "Change model settings, scope, or threshold for future work. Existing simulation plans keep their selected definitions and settings, including when regraded. Expected behaviors has fixed scope; its model and threshold are editable.", "tags": [ "Graders" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "graderId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "object", "properties": { "simulations": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "all" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "test_suite" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "test" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false } ] } }, "production": { "anyOf": [ { "type": "object", "properties": { "samplePercent": { "type": "number", "minimum": 1, "maximum": 100 } }, "required": [ "samplePercent" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "simulations", "production" ], "additionalProperties": false, "description": "Simulation selectors and an optional production sample. Only graders with scopeEditable set to true accept scope changes." }, "settings": { "type": "object", "additionalProperties": true, "description": "Complete values for the definition's settingDefinitions. LLM graders use llm_provider and llm_model. Response latency uses maximum_response_time_ms, a positive integer in milliseconds. These settings belong to this project and do not create a definition version." }, "passThreshold": { "type": "number", "minimum": 0, "maximum": 1, "description": "This grader passes when its score is at least this value. There is no overall run pass threshold." } }, "minProperties": 1, "additionalProperties": false, "examples": [ { "passThreshold": 1 } ] } } } }, "responses": { "200": { "description": "The updated project grader.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "graderDefinitionId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "owner": { "type": "string", "enum": [ "egma", "project" ] }, "type": { "type": "string", "enum": [ "llm_as_judge", "code" ] }, "modalities": { "type": "array", "items": { "type": "string", "enum": [ "chat", "voice" ] }, "minItems": 1, "uniqueItems": true }, "scopeEditable": { "type": "boolean" }, "removable": { "type": "boolean" }, "scope": { "type": "object", "properties": { "simulations": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "all" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "test_suite" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "test" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false } ] } }, "production": { "anyOf": [ { "type": "object", "properties": { "samplePercent": { "type": "number", "minimum": 1, "maximum": 100 } }, "required": [ "samplePercent" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "simulations", "production" ], "additionalProperties": false }, "settings": { "type": "object", "additionalProperties": true }, "passThreshold": { "type": "number", "minimum": 0, "maximum": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "graderDefinitionId", "name", "description", "owner", "type", "modalities", "scopeEditable", "removable", "scope", "settings", "passThreshold", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "delete": { "operationId": "removeGrader", "summary": "Remove an optional grader from a project", "description": "Stops selecting this grader for future project work. Existing grades and frozen simulation plans remain readable. Expected behaviors cannot be removed.", "tags": [ "Graders" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "graderId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "204": { "description": "The optional project grader was removed." }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/members": { "get": { "operationId": "listMembers", "summary": "List organization members", "tags": [ "Members" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "The organization's members.", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "email": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] }, "joinedAt": { "type": "string", "format": "date-time" }, "deactivatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "userId", "email", "name", "role", "joinedAt", "deactivatedAt" ], "additionalProperties": false } }, "mayManageMembers": { "type": "boolean" } }, "required": [ "members", "mayManageMembers" ], "additionalProperties": false } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/invitations": { "get": { "operationId": "listInvitations", "summary": "List pending invitations", "tags": [ "Members" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Pending invitations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invitations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdBy": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "email", "role", "expiresAt", "createdBy", "createdAt" ], "additionalProperties": false } } }, "required": [ "invitations" ], "additionalProperties": false } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "post": { "operationId": "createInvitation", "summary": "Invite an organization member", "tags": [ "Members" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] } }, "required": [ "email" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "The new invitation.", "headers": { "Cache-Control": { "description": "Prevents storage of the invitation acceptance URL.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdBy": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "delivered": { "type": "boolean" }, "acceptUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "email", "role", "expiresAt", "createdBy", "createdAt", "delivered" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/members/{userId}/role": { "post": { "operationId": "changeMemberRole", "summary": "Change a member role", "tags": [ "Members" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] } }, "required": [ "role" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The changed member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "email": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] }, "joinedAt": { "type": "string", "format": "date-time" }, "deactivatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "userId", "email", "name", "role", "joinedAt", "deactivatedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/members/{userId}/remove": { "post": { "operationId": "removeMember", "summary": "Remove an organization member", "tags": [ "Members" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The removed member and revoked key count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "keysRevoked": { "type": "integer", "minimum": 0 } }, "required": [ "userId", "keysRevoked" ], "additionalProperties": false } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/members/{userId}/deactivate": { "post": { "operationId": "deactivateMember", "summary": "Deactivate a member account", "tags": [ "Members" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The deactivated member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "email": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] }, "joinedAt": { "type": "string", "format": "date-time" }, "deactivatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "userId", "email", "name", "role", "joinedAt", "deactivatedAt" ], "additionalProperties": false } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/monitoring/retell/discover": { "post": { "operationId": "discoverRetellVoiceAgents", "summary": "Discover Retell voice agents", "tags": [ "Monitoring" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string" } }, "required": [ "apiKey" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Retell voice-agent identities.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "registeredAgentId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "registeredAgentName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pullProductionCalls": { "type": "boolean" } }, "required": [ "id", "name", "registeredAgentId", "registeredAgentName", "pullProductionCalls" ], "additionalProperties": false } } }, "required": [ "agents" ], "additionalProperties": false } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "503": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/monitoring/start": { "post": { "operationId": "startMonitoring", "summary": "Start pulling an agent's production calls", "tags": [ "Monitoring" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentPlatform": { "type": "string", "enum": [ "retell" ] }, "apiKey": { "type": "string", "description": "A Retell key for new agents. It may be omitted only when every watch entry names an existing agent that already stores its monitoring key." }, "watch": { "type": "array", "items": { "type": "object", "properties": { "platformAgentId": { "type": "string" }, "name": { "type": "string" }, "agentId": { "type": "string", "minLength": 1 } }, "required": [ "platformAgentId" ], "additionalProperties": false } } }, "required": [ "agentPlatform", "watch" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "What each ticked platform agent turned out to be: the ones now pulling their production calls, and the ones refused.", "content": { "application/json": { "schema": { "type": "object", "properties": { "watching": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "agentName": { "type": "string" }, "platformAgentId": { "type": "string" }, "created": { "type": "boolean" }, "pullProductionCalls": { "type": "boolean" } }, "required": [ "agentId", "agentName", "platformAgentId", "created", "pullProductionCalls" ], "additionalProperties": false } }, "refused": { "type": "array", "items": { "type": "object", "properties": { "platformAgentId": { "type": "string" }, "reason": { "type": "string", "enum": [ "contested", "name_taken", "not_found", "archived" ] }, "message": { "type": "string" } }, "required": [ "platformAgentId", "reason", "message" ], "additionalProperties": false } } }, "required": [ "watching", "refused" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "503": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/monitoring/agents/{agentId}/stop": { "post": { "operationId": "stopMonitoring", "summary": "Stop pulling an agent's production calls", "tags": [ "Monitoring" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "The agent, with its pull switch off.", "content": { "application/json": { "schema": { "type": "object", "properties": { "monitoring": { "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "pullProductionCalls": { "type": "boolean" }, "agentPlatform": { "type": "string", "enum": [ "retell", "livekit" ] }, "platformAgentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "monitoringApiKeyHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastReceivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "agentId", "pullProductionCalls", "agentPlatform", "platformAgentId", "monitoringApiKeyHint", "lastReceivedAt" ], "additionalProperties": false } }, "required": [ "monitoring" ], "additionalProperties": false } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/organization": { "get": { "operationId": "getOrganization", "summary": "Get the requester's organization", "tags": [ "Organization" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "The requester's organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "mayManageOrganization": { "type": "boolean" } }, "required": [ "id", "name", "slug", "createdAt", "mayManageOrganization" ], "additionalProperties": false } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "patch": { "operationId": "updateOrganization", "summary": "Update the requester's organization", "tags": [ "Organization" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The updated organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "mayManageOrganization": { "type": "boolean" } }, "required": [ "id", "name", "slug", "createdAt", "mayManageOrganization" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/personas/{personaId}/use": { "post": { "operationId": "usePersona", "summary": "Use a persona", "description": "Save this project's first model settings for the persona. Omit models to use its declared defaults. Repeated use returns the existing settings; use Update a persona to change them.", "tags": [ "Personas" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "personaId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 }, "models": { "type": "object", "description": "The complete language, speech recognition, and speech synthesis selections. Read /v1/persona-form for available choices and recommendations.", "properties": { "llm": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "stt": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "tts": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "voiceId": { "type": "string", "description": "A voice identifier supported by the selected text-to-speech provider." }, "speed": { "type": "number", "description": "Speech rate from 0.6 through 1.5. Use 1 for the normal rate." } }, "required": [ "provider", "model", "voiceId", "speed" ], "additionalProperties": false } }, "required": [ "llm", "stt", "tts" ], "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The persona with its saved project settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "versionId": { "type": "string", "minLength": 1 }, "identityName": { "type": "string", "description": "The human name the caller gives the agent, separate from the library name." }, "personality": { "type": "string", "description": "How the caller behaves and speaks. Put the situation and goal in the test scenario." }, "language": { "type": "string", "description": "The caller's language, such as en-US." }, "parameterContract": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "valueType": { "type": "string", "enum": [ "integer", "number", "string" ] }, "defaultValue": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "key", "label", "valueType", "defaultValue", "unit", "minimum", "maximum" ], "additionalProperties": false } }, "settings": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "models": { "type": "object", "description": "The complete language, speech recognition, and speech synthesis selections. Read /v1/persona-form for available choices and recommendations.", "properties": { "llm": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "stt": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "tts": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "voiceId": { "type": "string", "description": "A voice identifier supported by the selected text-to-speech provider." }, "speed": { "type": "number", "description": "Speech rate from 0.6 through 1.5. Use 1 for the normal rate." } }, "required": [ "provider", "model", "voiceId", "speed" ], "additionalProperties": false } }, "required": [ "llm", "stt", "tts" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "models", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "This project's saved model and voice settings. Null before first use. Settings changes do not create a behavior version." }, "owner": { "type": "string", "enum": [ "egma", "organization" ] }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "name", "description", "version", "versionId", "identityName", "personality", "language", "parameterContract", "settings", "owner", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/personas": { "get": { "operationId": "listPersonas", "summary": "List personas", "tags": [ "Personas" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of personas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "personas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "versionId": { "type": "string", "minLength": 1 }, "identityName": { "type": "string", "description": "The human name the caller gives the agent, separate from the library name." }, "personality": { "type": "string", "description": "How the caller behaves and speaks. Put the situation and goal in the test scenario." }, "language": { "type": "string", "description": "The caller's language, such as en-US." }, "parameterContract": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "valueType": { "type": "string", "enum": [ "integer", "number", "string" ] }, "defaultValue": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "key", "label", "valueType", "defaultValue", "unit", "minimum", "maximum" ], "additionalProperties": false } }, "settings": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "models": { "type": "object", "description": "The complete language, speech recognition, and speech synthesis selections. Read /v1/persona-form for available choices and recommendations.", "properties": { "llm": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "stt": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "tts": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "voiceId": { "type": "string", "description": "A voice identifier supported by the selected text-to-speech provider." }, "speed": { "type": "number", "description": "Speech rate from 0.6 through 1.5. Use 1 for the normal rate." } }, "required": [ "provider", "model", "voiceId", "speed" ], "additionalProperties": false } }, "required": [ "llm", "stt", "tts" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "models", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "This project's saved model and voice settings. Null before first use. Settings changes do not create a behavior version." }, "owner": { "type": "string", "enum": [ "egma", "organization" ] }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "name", "description", "version", "versionId", "identityName", "personality", "language", "parameterContract", "settings", "owner", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextPageToken": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "personas", "nextPageToken" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "post": { "operationId": "createPersona", "summary": "Create a persona", "description": "Create a project-owned persona with its first behavior version and complete model settings. Omit models to use the declared defaults. Add its ID or unambiguous name to a test to use it.", "tags": [ "Personas" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "description": "Your team's label in the persona library. The caller does not speak this label." }, "description": { "type": "string" }, "identityName": { "type": "string", "description": "The human name the caller gives the agent, separate from the library name." }, "personality": { "type": "string", "description": "How the caller behaves and speaks. Put the situation and goal in the test scenario." }, "language": { "type": "string", "description": "The caller's language, such as en-US." }, "models": { "type": "object", "description": "The complete language, speech recognition, and speech synthesis selections. Read /v1/persona-form for available choices and recommendations.", "properties": { "llm": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "stt": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "tts": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "voiceId": { "type": "string", "description": "A voice identifier supported by the selected text-to-speech provider." }, "speed": { "type": "number", "description": "Speech rate from 0.6 through 1.5. Use 1 for the normal rate." } }, "required": [ "provider", "model", "voiceId", "speed" ], "additionalProperties": false } }, "required": [ "llm", "stt", "tts" ], "additionalProperties": false } }, "required": [ "name", "identityName", "personality", "language" ], "additionalProperties": false, "examples": [ { "name": "Caller in a hurry", "description": "A caller who wants a brief appointment booking conversation.", "identityName": "Morgan Chen", "personality": "Answers briefly, asks for the earliest appointment, and stays polite when asking the agent to get to the point.", "language": "en-US", "models": { "llm": { "provider": "openai", "model": "gpt-4o-mini" }, "stt": { "provider": "openai", "model": "gpt-4o-mini-transcribe" }, "tts": { "provider": "openai", "model": "gpt-4o-mini-tts", "voiceId": "alloy", "speed": 1 } } } ] } } } }, "responses": { "201": { "description": "The new persona.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "versionId": { "type": "string", "minLength": 1 }, "identityName": { "type": "string", "description": "The human name the caller gives the agent, separate from the library name." }, "personality": { "type": "string", "description": "How the caller behaves and speaks. Put the situation and goal in the test scenario." }, "language": { "type": "string", "description": "The caller's language, such as en-US." }, "parameterContract": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "valueType": { "type": "string", "enum": [ "integer", "number", "string" ] }, "defaultValue": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "key", "label", "valueType", "defaultValue", "unit", "minimum", "maximum" ], "additionalProperties": false } }, "settings": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "models": { "type": "object", "description": "The complete language, speech recognition, and speech synthesis selections. Read /v1/persona-form for available choices and recommendations.", "properties": { "llm": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "stt": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "tts": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "voiceId": { "type": "string", "description": "A voice identifier supported by the selected text-to-speech provider." }, "speed": { "type": "number", "description": "Speech rate from 0.6 through 1.5. Use 1 for the normal rate." } }, "required": [ "provider", "model", "voiceId", "speed" ], "additionalProperties": false } }, "required": [ "llm", "stt", "tts" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "models", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "This project's saved model and voice settings. Null before first use. Settings changes do not create a behavior version." }, "owner": { "type": "string", "enum": [ "egma", "organization" ] }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "name", "description", "version", "versionId", "identityName", "personality", "language", "parameterContract", "settings", "owner", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/persona-form": { "get": { "operationId": "getPersonaForm", "summary": "Get persona authoring choices", "description": "Use this response to choose supported models, a recommended voice, and a valid speech rate before creating or updating a persona.", "tags": [ "Personas" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The supported persona model choices.", "content": { "application/json": { "schema": { "type": "object", "properties": { "modelCatalog": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "job": { "type": "string", "enum": [ "llm", "stt", "tts" ] }, "model": { "type": "string" }, "label": { "type": "string" }, "modelLabel": { "type": "string" }, "recommendedVoiceId": { "type": "string" } }, "required": [ "provider", "job", "model", "label" ], "additionalProperties": false } }, "recommendedModels": { "type": "object", "description": "The complete language, speech recognition, and speech synthesis selections. Read /v1/persona-form for available choices and recommendations.", "properties": { "llm": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "stt": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "tts": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "voiceId": { "type": "string", "description": "A voice identifier supported by the selected text-to-speech provider." }, "speed": { "type": "number", "description": "Speech rate from 0.6 through 1.5. Use 1 for the normal rate." } }, "required": [ "provider", "model", "voiceId", "speed" ], "additionalProperties": false } }, "required": [ "llm", "stt", "tts" ], "additionalProperties": false }, "speedRange": { "type": "object", "properties": { "slowest": { "type": "number" }, "fastest": { "type": "number" } }, "required": [ "slowest", "fastest" ], "additionalProperties": false } }, "required": [ "modelCatalog", "recommendedModels", "speedRange" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/personas/{personaId}": { "get": { "operationId": "getPersona", "summary": "Get a persona", "tags": [ "Personas" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "personaId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The persona.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "versionId": { "type": "string", "minLength": 1 }, "identityName": { "type": "string", "description": "The human name the caller gives the agent, separate from the library name." }, "personality": { "type": "string", "description": "How the caller behaves and speaks. Put the situation and goal in the test scenario." }, "language": { "type": "string", "description": "The caller's language, such as en-US." }, "parameterContract": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "valueType": { "type": "string", "enum": [ "integer", "number", "string" ] }, "defaultValue": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "key", "label", "valueType", "defaultValue", "unit", "minimum", "maximum" ], "additionalProperties": false } }, "settings": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "models": { "type": "object", "description": "The complete language, speech recognition, and speech synthesis selections. Read /v1/persona-form for available choices and recommendations.", "properties": { "llm": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "stt": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "tts": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "voiceId": { "type": "string", "description": "A voice identifier supported by the selected text-to-speech provider." }, "speed": { "type": "number", "description": "Speech rate from 0.6 through 1.5. Use 1 for the normal rate." } }, "required": [ "provider", "model", "voiceId", "speed" ], "additionalProperties": false } }, "required": [ "llm", "stt", "tts" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "models", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "This project's saved model and voice settings. Null before first use. Settings changes do not create a behavior version." }, "owner": { "type": "string", "enum": [ "egma", "organization" ] }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "name", "description", "version", "versionId", "identityName", "personality", "language", "parameterContract", "settings", "owner", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "patch": { "operationId": "updatePersona", "summary": "Update a persona", "description": "Change project model settings or the current custom behavior. Behavior edits require expectedVersionId and create a version when changed. Model settings and display labels create no version. Egma-owned behavior is read-only; its project settings are editable.", "tags": [ "Personas" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "personaId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "description": "Your team's label in the persona library. The caller does not speak this label." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "identityName": { "type": "string", "description": "The human name the caller gives the agent, separate from the library name." }, "personality": { "type": "string", "description": "How the caller behaves and speaks. Put the situation and goal in the test scenario." }, "language": { "type": "string", "description": "The caller's language, such as en-US." }, "models": { "type": "object", "description": "The complete language, speech recognition, and speech synthesis selections. Read /v1/persona-form for available choices and recommendations.", "properties": { "llm": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "stt": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "tts": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "voiceId": { "type": "string", "description": "A voice identifier supported by the selected text-to-speech provider." }, "speed": { "type": "number", "description": "Speech rate from 0.6 through 1.5. Use 1 for the normal rate." } }, "required": [ "provider", "model", "voiceId", "speed" ], "additionalProperties": false } }, "required": [ "llm", "stt", "tts" ], "additionalProperties": false }, "expectedVersionId": { "type": "string", "minLength": 1, "description": "The current versionId from Get a persona. Required when editing identityName, personality, or language. A stale value returns 409 version_conflict." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The updated persona.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "versionId": { "type": "string", "minLength": 1 }, "identityName": { "type": "string", "description": "The human name the caller gives the agent, separate from the library name." }, "personality": { "type": "string", "description": "How the caller behaves and speaks. Put the situation and goal in the test scenario." }, "language": { "type": "string", "description": "The caller's language, such as en-US." }, "parameterContract": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "valueType": { "type": "string", "enum": [ "integer", "number", "string" ] }, "defaultValue": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "key", "label", "valueType", "defaultValue", "unit", "minimum", "maximum" ], "additionalProperties": false } }, "settings": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "models": { "type": "object", "description": "The complete language, speech recognition, and speech synthesis selections. Read /v1/persona-form for available choices and recommendations.", "properties": { "llm": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "stt": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "tts": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "voiceId": { "type": "string", "description": "A voice identifier supported by the selected text-to-speech provider." }, "speed": { "type": "number", "description": "Speech rate from 0.6 through 1.5. Use 1 for the normal rate." } }, "required": [ "provider", "model", "voiceId", "speed" ], "additionalProperties": false } }, "required": [ "llm", "stt", "tts" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "models", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "This project's saved model and voice settings. Null before first use. Settings changes do not create a behavior version." }, "owner": { "type": "string", "enum": [ "egma", "organization" ] }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "name", "description", "version", "versionId", "identityName", "personality", "language", "parameterContract", "settings", "owner", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "delete": { "operationId": "deletePersona", "summary": "Permanently delete a persona from authoring", "description": "The persona leaves every authoring list and picker permanently. Existing run evidence stays readable.", "tags": [ "Personas" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "personaId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "204": { "description": "The persona was deleted." }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/personas/{personaId}/versions": { "get": { "operationId": "listPersonaVersions", "summary": "List persona versions", "tags": [ "Personas" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "personaId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "A page of frozen persona versions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "personaId": { "type": "string", "minLength": 1 }, "version": { "type": "integer", "minimum": 1 }, "identityName": { "type": "string", "description": "The human name the caller gives the agent, separate from the library name." }, "personality": { "type": "string", "description": "How the caller behaves and speaks. Put the situation and goal in the test scenario." }, "language": { "type": "string", "description": "The caller's language, such as en-US." }, "parameterContract": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "valueType": { "type": "string", "enum": [ "integer", "number", "string" ] }, "defaultValue": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "key", "label", "valueType", "defaultValue", "unit", "minimum", "maximum" ], "additionalProperties": false } }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "personaId", "version", "identityName", "personality", "language", "parameterContract", "createdAt" ], "additionalProperties": false } }, "nextPageToken": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "versions", "nextPageToken" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/personas/{personaId}/usage": { "get": { "operationId": "getPersonaUsage", "summary": "Get a persona's test usage", "tags": [ "Personas" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "personaId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The active tests that use the persona.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "required": [ "tests" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/persona-versions/{versionId}": { "get": { "operationId": "getPersonaVersion", "summary": "Get a persona version", "tags": [ "Personas" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The frozen persona version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "personaId": { "type": "string", "minLength": 1 }, "version": { "type": "integer", "minimum": 1 }, "identityName": { "type": "string", "description": "The human name the caller gives the agent, separate from the library name." }, "personality": { "type": "string", "description": "How the caller behaves and speaks. Put the situation and goal in the test scenario." }, "language": { "type": "string", "description": "The caller's language, such as en-US." }, "parameterContract": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "valueType": { "type": "string", "enum": [ "integer", "number", "string" ] }, "defaultValue": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "key", "label", "valueType", "defaultValue", "unit", "minimum", "maximum" ], "additionalProperties": false } }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "personaId", "version", "identityName", "personality", "language", "parameterContract", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/personas/{personaId}/fork": { "post": { "operationId": "forkPersona", "summary": "Clone a persona", "description": "Creates an editable custom copy of the persona's current behavior and model settings. The original persona and tests that select it stay unchanged.", "tags": [ "Personas" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "personaId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "The new custom persona.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "versionId": { "type": "string", "minLength": 1 }, "identityName": { "type": "string", "description": "The human name the caller gives the agent, separate from the library name." }, "personality": { "type": "string", "description": "How the caller behaves and speaks. Put the situation and goal in the test scenario." }, "language": { "type": "string", "description": "The caller's language, such as en-US." }, "parameterContract": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "valueType": { "type": "string", "enum": [ "integer", "number", "string" ] }, "defaultValue": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "key", "label", "valueType", "defaultValue", "unit", "minimum", "maximum" ], "additionalProperties": false } }, "settings": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "models": { "type": "object", "description": "The complete language, speech recognition, and speech synthesis selections. Read /v1/persona-form for available choices and recommendations.", "properties": { "llm": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "stt": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "tts": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "voiceId": { "type": "string", "description": "A voice identifier supported by the selected text-to-speech provider." }, "speed": { "type": "number", "description": "Speech rate from 0.6 through 1.5. Use 1 for the normal rate." } }, "required": [ "provider", "model", "voiceId", "speed" ], "additionalProperties": false } }, "required": [ "llm", "stt", "tts" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "models", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "This project's saved model and voice settings. Null before first use. Settings changes do not create a behavior version." }, "owner": { "type": "string", "enum": [ "egma", "organization" ] }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "name", "description", "version", "versionId", "identityName", "personality", "language", "parameterContract", "settings", "owner", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/projects": { "get": { "operationId": "listProjects", "summary": "List projects", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Every project in the requester's organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "organizationId": { "type": "string", "minLength": 1 }, "revision": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "slug", "description", "organizationId", "revision", "createdAt" ], "additionalProperties": false } }, "mayManageProjects": { "type": "boolean" } }, "required": [ "projects", "mayManageProjects" ], "additionalProperties": false } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "post": { "operationId": "createProject", "summary": "Create a project", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "The new project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "organizationId": { "type": "string", "minLength": 1 }, "revision": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "slug", "description", "organizationId", "revision", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/projects/{projectId}": { "get": { "operationId": "getProject", "summary": "Get a project", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "organizationId": { "type": "string", "minLength": 1 }, "revision": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "mayManageProjects": { "type": "boolean" } }, "required": [ "id", "name", "slug", "description", "organizationId", "revision", "createdAt", "mayManageProjects" ], "additionalProperties": false } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "patch": { "operationId": "updateProject", "summary": "Update a project", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expectedRevision": { "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "organizationId": { "type": "string", "minLength": 1 }, "revision": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "slug", "description", "organizationId", "revision", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/simulations/{simulationId}/recording": { "get": { "operationId": "getSimulationRecording", "summary": "Get a simulation recording link", "tags": [ "Recordings" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "simulationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "A short-lived link to the recording.", "content": { "application/json": { "schema": { "type": "object", "properties": { "simulationId": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "simulationId", "url", "expiresAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "503": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/repository/change-set": { "post": { "operationId": "applyRepositoryChangeSet", "summary": "Apply the complete authored state from a repository", "description": "The complete authored suites and tests are applied atomically. Each test carries its own mock tools and env. Missing resources refuse rather than delete.", "tags": [ "Repository" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "suites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "tests": { "type": "array", "items": { "type": "object", "properties": { "clientRef": { "type": "string" }, "suiteId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "scenario": { "type": "string" }, "expectedBehaviors": { "type": "array", "items": { "type": "string" } }, "personas": { "type": "array", "items": { "type": "string" } }, "mockTools": { "type": "array", "items": { "description": "One named tool's fixed response for this test. Supply exactly one of answer or error. Tools without a mock run normally.", "oneOf": [ { "type": "object", "properties": { "tool": { "type": "string" }, "answer": {}, "error": { "not": {} } }, "required": [ "tool", "answer" ], "additionalProperties": false }, { "type": "object", "properties": { "tool": { "type": "string" }, "answer": { "not": {} }, "error": { "type": "string" } }, "required": [ "tool", "error" ], "additionalProperties": false } ] } }, "env": { "anyOf": [ { "type": "object", "properties": { "retell_dynamic_variables": { "type": "object", "description": "String values supplied to the Retell agent before the conversation. Variable names beginning with egma_ are reserved.", "additionalProperties": { "type": "string" } }, "job_dispatch_metadata": { "type": "object", "description": "Context delivered to the LiveKit worker in ctx.job.metadata.", "additionalProperties": true } }, "additionalProperties": false }, { "type": "null" } ] }, "expectedVersionId": { "type": "string", "minLength": 1 }, "expectedRevision": { "type": "string", "minLength": 1 } }, "required": [ "clientRef", "suiteId", "name", "description", "scenario", "expectedBehaviors", "personas", "mockTools", "env" ], "additionalProperties": false } } }, "required": [ "suites", "tests" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The tests after the change set was applied.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tests": { "type": "array", "items": { "type": "object", "properties": { "clientRef": { "type": "string" }, "test": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "suiteId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "versionId": { "type": "string", "minLength": 1 }, "scenario": { "type": "string" }, "expectedBehaviors": { "type": "array", "items": { "type": "string" } }, "personas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "archivedAt" ], "additionalProperties": false } }, "mockTools": { "type": "array", "items": { "description": "One named tool's fixed response for this test. Supply exactly one of answer or error. Tools without a mock run normally.", "oneOf": [ { "type": "object", "properties": { "tool": { "type": "string" }, "answer": {}, "error": { "not": {} } }, "required": [ "tool", "answer" ], "additionalProperties": false }, { "type": "object", "properties": { "tool": { "type": "string" }, "answer": { "not": {} }, "error": { "type": "string" } }, "required": [ "tool", "error" ], "additionalProperties": false } ] } }, "env": { "anyOf": [ { "type": "object", "properties": { "retell_dynamic_variables": { "type": "object", "description": "String values supplied to the Retell agent before the conversation. Variable names beginning with egma_ are reserved.", "additionalProperties": { "type": "string" } }, "job_dispatch_metadata": { "type": "object", "description": "Context delivered to the LiveKit worker in ctx.job.metadata.", "additionalProperties": true } }, "additionalProperties": false }, { "type": "null" } ] }, "revision": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "suiteId", "name", "description", "version", "versionId", "scenario", "expectedBehaviors", "personas", "mockTools", "env", "revision", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "clientRef", "test" ], "additionalProperties": false } } }, "required": [ "tests" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/runs": { "post": { "operationId": "createRun", "summary": "Create a run", "description": "Run every active test in a suite against one agent connection. Execution and grading continue after this request returns. Keep the returned id to follow progress and inspect results.", "tags": [ "Runs" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "Project to act in. A project-scoped API key already identifies its project." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "suiteId": { "type": "string", "minLength": 1, "description": "The active, non-empty test suite to execute in full. It must belong to the selected project.", "examples": [ "ste_01M0E4J0BBE1FVDVTZ1BSS5C97" ] }, "agentId": { "type": "string", "minLength": 1, "description": "The Egma agent to test, not its Retell provider ID or LiveKit dispatch name.", "examples": [ "agt_01M0E4J0BBE1FVDVTZ1BSS5C97" ] }, "connectionId": { "type": "string", "minLength": 1, "description": "An active connection on that agent in the same project. Its modality determines whether simulations use voice or chat.", "examples": [ "con_01M0E4J0BBE1FVDVTZ1BSS5C97" ] }, "name": { "type": "string", "description": "Optional display name for the run.", "examples": [ "Appointment booking release check" ] }, "expectedTestVersions": { "type": "array", "items": { "type": "object", "properties": { "testId": { "type": "string", "minLength": 1, "description": "The test identity to check." }, "versionId": { "type": "string", "minLength": 1, "description": "The current test version expected at run creation." } }, "required": [ "testId", "versionId" ], "additionalProperties": false }, "description": "Optional exact list of the suite's test IDs and current version IDs. Each test and version must appear once. The request is refused if the suite membership or any version changed. Omit this field to use the current suite." } }, "required": [ "suiteId", "agentId", "connectionId" ], "additionalProperties": false, "examples": [ { "suiteId": "ste_01M0E4J0BBE1FVDVTZ1BSS5C97", "agentId": "agt_01M0E4J0BBE1FVDVTZ1BSS5C97", "connectionId": "con_01M0E4J0BBE1FVDVTZ1BSS5C97", "name": "Appointment booking release check" } ] } } } }, "responses": { "201": { "description": "The run header for a new request or an idempotent replay. The run may still be executing or grading.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "suiteId": { "type": "string", "minLength": 1 }, "suiteName": { "type": "string" }, "suiteDeleted": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "canceled" ], "description": "Simulation execution status. A completed run can contain failed simulations, and grading may still be in progress." }, "agentId": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "minLength": 1 }, "connectionName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agentPlatform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "connectionType": { "type": "string" }, "accessVariant": { "type": "string" }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "productLabel": { "type": "string" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agentVersion": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "expectedSimulationCount": { "type": "integer", "description": "Number of test-and-persona combinations captured when the run started." }, "completedCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "failedCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "canceledCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "simulationCounts": { "type": "object", "properties": { "queued": { "type": "integer" }, "claimed": { "type": "integer" }, "running": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "canceled": { "type": "integer" } }, "required": [ "queued", "claimed", "running", "completed", "failed", "canceled" ], "additionalProperties": false }, "finishedCount": { "type": "integer", "description": "Simulations whose execution completed, failed, or was canceled." }, "gradableCount": { "type": "integer", "description": "Simulations eligible for grading under the run's frozen grader selection." }, "gradedCount": { "type": "integer", "description": "Gradable simulations whose grading is complete or errored. This is not a count of passed simulations." }, "resultsUrl": { "type": "string", "description": "Open this URL in a browser to follow the run and inspect its results." }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "projectId", "suiteId", "suiteName", "suiteDeleted", "name", "status", "agentId", "connectionId", "connectionName", "agentPlatform", "connectionType", "accessVariant", "modality", "productLabel", "environment", "agentVersion", "expectedSimulationCount", "completedCount", "failedCount", "canceledCount", "simulationCounts", "finishedCount", "gradableCount", "gradedCount", "resultsUrl", "createdAt", "startedAt", "finishedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "503": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "get": { "operationId": "listRuns", "summary": "List runs", "tags": [ "Runs" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "suiteId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "agentId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "connectionId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "testId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "running", "completed", "canceled" ], "description": "Simulation execution status. A completed run can contain failed simulations, and grading may still be in progress." } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "A bounded page of run headers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "suiteId": { "type": "string", "minLength": 1 }, "suiteName": { "type": "string" }, "suiteDeleted": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "canceled" ], "description": "Simulation execution status. A completed run can contain failed simulations, and grading may still be in progress." }, "agentId": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "minLength": 1 }, "connectionName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agentPlatform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "connectionType": { "type": "string" }, "accessVariant": { "type": "string" }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "productLabel": { "type": "string" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agentVersion": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "expectedSimulationCount": { "type": "integer", "description": "Number of test-and-persona combinations captured when the run started." }, "completedCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "failedCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "canceledCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "simulationCounts": { "type": "object", "properties": { "queued": { "type": "integer" }, "claimed": { "type": "integer" }, "running": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "canceled": { "type": "integer" } }, "required": [ "queued", "claimed", "running", "completed", "failed", "canceled" ], "additionalProperties": false }, "finishedCount": { "type": "integer", "description": "Simulations whose execution completed, failed, or was canceled." }, "gradableCount": { "type": "integer", "description": "Simulations eligible for grading under the run's frozen grader selection." }, "gradedCount": { "type": "integer", "description": "Gradable simulations whose grading is complete or errored. This is not a count of passed simulations." }, "resultsUrl": { "type": "string", "description": "Open this URL in a browser to follow the run and inspect its results." }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "projectId", "suiteId", "suiteName", "suiteDeleted", "name", "status", "agentId", "connectionId", "connectionName", "agentPlatform", "connectionType", "accessVariant", "modality", "productLabel", "environment", "agentVersion", "expectedSimulationCount", "completedCount", "failedCount", "canceledCount", "simulationCounts", "finishedCount", "gradableCount", "gradedCount", "resultsUrl", "createdAt", "startedAt", "finishedAt" ], "additionalProperties": false } }, "nextPageToken": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "runs", "nextPageToken" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/runs/{runId}": { "get": { "operationId": "getRun", "summary": "Get a run", "tags": [ "Runs" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Run ID returned by Create a run or List runs.", "examples": [ "run_01M0E4J0BBE1FVDVTZ1BSS5C97" ] } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "Project to act in. A project-scoped API key already identifies its project." } } ], "responses": { "200": { "description": "The bounded run header and target context.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "suiteId": { "type": "string", "minLength": 1 }, "suiteName": { "type": "string" }, "suiteDeleted": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "canceled" ], "description": "Simulation execution status. A completed run can contain failed simulations, and grading may still be in progress." }, "agentId": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "minLength": 1 }, "connectionName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agentPlatform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "connectionType": { "type": "string" }, "accessVariant": { "type": "string" }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "productLabel": { "type": "string" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agentVersion": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "expectedSimulationCount": { "type": "integer", "description": "Number of test-and-persona combinations captured when the run started." }, "completedCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "failedCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "canceledCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "simulationCounts": { "type": "object", "properties": { "queued": { "type": "integer" }, "claimed": { "type": "integer" }, "running": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "canceled": { "type": "integer" } }, "required": [ "queued", "claimed", "running", "completed", "failed", "canceled" ], "additionalProperties": false }, "finishedCount": { "type": "integer", "description": "Simulations whose execution completed, failed, or was canceled." }, "gradableCount": { "type": "integer", "description": "Simulations eligible for grading under the run's frozen grader selection." }, "gradedCount": { "type": "integer", "description": "Gradable simulations whose grading is complete or errored. This is not a count of passed simulations." }, "resultsUrl": { "type": "string", "description": "Open this URL in a browser to follow the run and inspect its results." }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "eventThrough": { "type": "integer" }, "workBlock": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "enum": [ "allowance_spent", "providers_unfunded" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "tempMockAgentVersion": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "tempMockAgentVersionCleanup": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "mockMetadata": { "anyOf": [ { "type": "object", "properties": { "engine": { "type": "object", "properties": { "type": { "type": "string" }, "engineId": { "type": "string" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "type", "engineId", "version" ], "additionalProperties": false } }, "required": [ "engine" ], "additionalProperties": false }, { "type": "null" } ] }, "connectionSnapshot": { "type": "object", "properties": { "agentPlatform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "connectionType": { "type": "string" }, "accessVariant": { "type": "string" }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "topology": { "type": "string" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "config": {} }, "required": [ "agentPlatform", "connectionType", "accessVariant", "modality", "topology", "environment", "config" ], "additionalProperties": false }, "agent": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "archived": { "type": "boolean" } }, "required": [ "id", "name", "archived" ], "additionalProperties": false }, { "type": "null" } ] }, "connection": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "archived": { "type": "boolean" }, "productLabel": { "type": "string" } }, "required": [ "id", "name", "archived", "productLabel" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "projectId", "suiteId", "suiteName", "suiteDeleted", "name", "status", "agentId", "connectionId", "connectionName", "agentPlatform", "connectionType", "accessVariant", "modality", "productLabel", "environment", "agentVersion", "expectedSimulationCount", "completedCount", "failedCount", "canceledCount", "simulationCounts", "finishedCount", "gradableCount", "gradedCount", "resultsUrl", "createdAt", "startedAt", "finishedAt", "eventThrough", "workBlock", "tempMockAgentVersion", "tempMockAgentVersionCleanup", "mockMetadata", "connectionSnapshot", "agent", "connection" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/runs/{runId}/simulations": { "get": { "operationId": "listRunSimulations", "summary": "List simulations in a run", "tags": [ "Runs" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Run ID returned by Create a run or List runs.", "examples": [ "run_01M0E4J0BBE1FVDVTZ1BSS5C97" ] } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "A bounded page of simulations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "simulations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "position": { "type": "integer" }, "testId": { "type": "string", "minLength": 1 }, "testName": { "type": "string" }, "testVersionId": { "type": "string", "minLength": 1 }, "personaId": { "type": "string", "minLength": 1 }, "personaName": { "type": "string" }, "personaVersionId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "queued", "claimed", "running", "completed", "failed", "canceled" ] }, "gradingState": { "anyOf": [ { "type": "string", "enum": [ "not_requested", "pending", "running", "complete", "error" ] }, { "type": "null" } ] }, "combinedScore": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "gradeTally": { "anyOf": [ { "type": "object", "properties": { "passed": { "type": "integer" }, "failed": { "type": "integer" }, "errored": { "type": "integer" }, "selected": { "type": "integer" } }, "required": [ "passed", "failed", "errored", "selected" ], "additionalProperties": false }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string", "enum": [ "persona_concluded", "agent_ended", "limit_reached", "agent_never_joined", "not_answered", "capacity", "simulator_error", "orphaned", "dispatch_failed", "provider_key_unavailable" ] }, { "type": "null" } ] }, "executionFailure": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "hasRecording": { "type": "boolean" } }, "required": [ "id", "position", "testId", "testName", "testVersionId", "personaId", "personaName", "personaVersionId", "status", "gradingState", "combinedScore", "gradeTally", "reason", "executionFailure", "startedAt", "endedAt", "modality", "hasRecording" ], "additionalProperties": false } }, "nextPageToken": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "simulations", "nextPageToken" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/runs/{runId}/events": { "get": { "operationId": "listRunEvents", "summary": "List run events", "description": "Read run events in sequence order. Pass each response’s next value as after. Continue until done is true, then inspect the simulation grades for pass or fail results.", "tags": [ "Runs" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Run ID returned by Create a run or List runs.", "examples": [ "run_01M0E4J0BBE1FVDVTZ1BSS5C97" ] } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "Project to act in. A project-scoped API key already identifies its project." } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "description": "Return events with a sequence greater than this value. Use zero or omit it for the first page; use the previous response's next value to continue.", "examples": [ 0 ] } } ], "responses": { "200": { "description": "The run events after the requested sequence.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "seq": { "type": "integer" }, "at": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": [ "run" ] }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "canceled" ], "description": "Simulation execution status. A completed run can contain failed simulations, and grading may still be in progress." } }, "required": [ "seq", "at", "kind", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "integer" }, "at": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": [ "simulation" ] }, "simulationId": { "type": "string", "minLength": 1 }, "testName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "personaName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "queued", "claimed", "running", "completed", "failed", "canceled" ] }, "reason": { "anyOf": [ { "type": "string", "enum": [ "persona_concluded", "agent_ended", "limit_reached", "agent_never_joined", "not_answered", "capacity", "simulator_error", "orphaned", "dispatch_failed", "provider_key_unavailable" ] }, { "type": "null" } ] }, "executionFailure": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "seq", "at", "kind", "simulationId", "testName", "personaName", "status", "reason", "executionFailure" ], "additionalProperties": false } ] } }, "next": { "type": "integer", "description": "Cursor to send as after on the next request. An empty page returns the same cursor." }, "caughtUp": { "type": "boolean", "description": "This page includes all execution events available when it was read. More events or grades may arrive later." }, "done": { "type": "boolean", "description": "Execution finished, no execution events remain in the backlog, and every gradable simulation has complete or errored grading. Inspect individual grades to decide whether the run meets your requirements." } }, "required": [ "events", "next", "caughtUp", "done" ], "additionalProperties": false, "examples": [ { "events": [], "next": 12, "caughtUp": true, "done": false } ] } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/runs/{runId}/cancel": { "post": { "operationId": "cancelRun", "summary": "Cancel a run", "tags": [ "Runs" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Run ID returned by Create a run or List runs.", "examples": [ "run_01M0E4J0BBE1FVDVTZ1BSS5C97" ] } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "Project to act in. A project-scoped API key already identifies its project." } } ], "responses": { "200": { "description": "The bounded header for the canceled run.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "suiteId": { "type": "string", "minLength": 1 }, "suiteName": { "type": "string" }, "suiteDeleted": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "canceled" ], "description": "Simulation execution status. A completed run can contain failed simulations, and grading may still be in progress." }, "agentId": { "type": "string", "minLength": 1 }, "connectionId": { "type": "string", "minLength": 1 }, "connectionName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agentPlatform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "connectionType": { "type": "string" }, "accessVariant": { "type": "string" }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "productLabel": { "type": "string" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agentVersion": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "expectedSimulationCount": { "type": "integer", "description": "Number of test-and-persona combinations captured when the run started." }, "completedCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "failedCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "canceledCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "simulationCounts": { "type": "object", "properties": { "queued": { "type": "integer" }, "claimed": { "type": "integer" }, "running": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "canceled": { "type": "integer" } }, "required": [ "queued", "claimed", "running", "completed", "failed", "canceled" ], "additionalProperties": false }, "finishedCount": { "type": "integer", "description": "Simulations whose execution completed, failed, or was canceled." }, "gradableCount": { "type": "integer", "description": "Simulations eligible for grading under the run's frozen grader selection." }, "gradedCount": { "type": "integer", "description": "Gradable simulations whose grading is complete or errored. This is not a count of passed simulations." }, "resultsUrl": { "type": "string", "description": "Open this URL in a browser to follow the run and inspect its results." }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "projectId", "suiteId", "suiteName", "suiteDeleted", "name", "status", "agentId", "connectionId", "connectionName", "agentPlatform", "connectionType", "accessVariant", "modality", "productLabel", "environment", "agentVersion", "expectedSimulationCount", "completedCount", "failedCount", "canceledCount", "simulationCounts", "finishedCount", "gradableCount", "gradedCount", "resultsUrl", "createdAt", "startedAt", "finishedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/simulations/{simulationId}": { "get": { "operationId": "getSimulation", "summary": "Get a simulation", "description": "Read a simulation’s test, persona, connection, metrics, transcript, and grades. Execution status and gradingState are separate: a completed simulation may still be grading.", "tags": [ "Simulations" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "simulationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Simulation ID returned by List simulations in a run.", "examples": [ "sim_01M0E4J0BBE1FVDVTZ1BSS5C97" ] } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The simulation and its available evidence. Check spansTruncated before treating the returned span tree as complete.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "runId": { "type": "string", "minLength": 1 }, "runName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "position": { "type": "integer" }, "status": { "type": "string", "enum": [ "queued", "claimed", "running", "completed", "failed", "canceled" ] }, "workBlock": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "enum": [ "allowance_spent", "providers_unfunded" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "gradingState": { "anyOf": [ { "type": "string", "enum": [ "not_requested", "pending", "running", "complete", "error" ] }, { "type": "null" } ] }, "evidenceError": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "evidence_collection_error" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "grades": { "type": "array", "items": { "type": "object", "properties": { "projectGraderId": { "type": "string", "minLength": 1 }, "graderDefinitionId": { "type": "string", "minLength": 1 }, "graderDefinitionVersion": { "type": "integer", "minimum": 1 }, "parameterValues": { "type": "object", "additionalProperties": true, "description": "The model or numeric settings used for this grading attempt. Retained for successful and errored grades, including after temporary jobs are removed. Contains no credentials." }, "graderName": { "type": "string" }, "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "details": { "type": "object", "properties": { "rationale": { "type": "string" }, "assertions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "decision": { "type": "string", "enum": [ "met", "not_met", "cannot_determine" ] }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, "rationale": { "type": "string" }, "citedSpanIds": { "type": "array", "items": { "type": "string" } }, "citedTurns": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "error": { "type": "string" } }, "required": [ "key" ], "additionalProperties": false } }, "error": { "type": "string" } }, "additionalProperties": true }, "passThreshold": { "type": "number", "minimum": 0, "maximum": 1 }, "result": { "type": "string", "enum": [ "passed", "failed", "errored" ] }, "gradedAt": { "type": "string", "format": "date-time" } }, "required": [ "projectGraderId", "graderDefinitionId", "graderDefinitionVersion", "parameterValues", "graderName", "score", "details", "passThreshold", "result", "gradedAt" ], "additionalProperties": false }, "description": "The current result for each selected grader. Each grade has its own score, frozen threshold, result, and supporting details." }, "gradeHistory": { "type": "array", "items": { "type": "object", "properties": { "projectGraderId": { "type": "string", "minLength": 1 }, "graderDefinitionId": { "type": "string", "minLength": 1 }, "graderDefinitionVersion": { "type": "integer", "minimum": 1 }, "parameterValues": { "type": "object", "additionalProperties": true, "description": "The model or numeric settings used for this grading attempt. Retained for successful and errored grades, including after temporary jobs are removed. Contains no credentials." }, "graderName": { "type": "string" }, "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "details": { "type": "object", "properties": { "rationale": { "type": "string" }, "assertions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "decision": { "type": "string", "enum": [ "met", "not_met", "cannot_determine" ] }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, "rationale": { "type": "string" }, "citedSpanIds": { "type": "array", "items": { "type": "string" } }, "citedTurns": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "error": { "type": "string" } }, "required": [ "key" ], "additionalProperties": false } }, "error": { "type": "string" } }, "additionalProperties": true }, "passThreshold": { "type": "number", "minimum": 0, "maximum": 1 }, "result": { "type": "string", "enum": [ "passed", "failed", "errored" ] }, "gradedAt": { "type": "string", "format": "date-time" } }, "required": [ "projectGraderId", "graderDefinitionId", "graderDefinitionVersion", "parameterValues", "graderName", "score", "details", "passThreshold", "result", "gradedAt" ], "additionalProperties": false }, "description": "Recorded grade results, including previous grading attempts. Regrading preserves this history." }, "combinedScore": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ], "description": "Display-only arithmetic mean when every selected grader has a current score. Null while a required score is missing or errored. This is not an overall pass/fail result." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "executionFailure": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "providerReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hasRecording": { "type": "boolean" }, "agentPovComplete": { "type": "boolean" }, "agentPovIncomplete": { "type": "boolean" }, "measures": { "type": "object", "properties": { "durationMs": { "type": "integer" }, "turnCount": { "type": "integer" }, "toolCallCount": { "type": "integer" }, "erroredStepCount": { "type": "integer" }, "humanTurnCount": { "type": "integer" }, "agentTurnCount": { "type": "integer" } }, "additionalProperties": false }, "metrics": { "type": "array", "items": { "type": "object", "description": "One metric from one side of the conversation. Simulation metrics prefer the persona's series when available. Production traces use the agent's evidence. A second series stays separate in otherPov.", "properties": { "measure": { "type": "string", "description": "Metric identifier. turn_response_latency measures the wait from the end of the caller's turn to the agent's reply. For voice simulations, it runs from the end of the caller's played audio, including trailing padding, to the arrival of the agent's audio. first_response_latency measures the wait from conversation start to the first reply. Both use milliseconds." }, "unit": { "type": "string" }, "derived": { "type": "boolean" }, "pov": { "type": "string", "enum": [ "persona", "agent" ], "description": "The source of these measurements: agent for the agent's own evidence, or persona for Egma's simulated caller. The samples and summary values describe only this source." }, "reportedBy": { "type": "string" }, "samples": { "type": "array", "items": { "type": "number" } }, "spanIds": { "type": "array", "items": { "type": "string" } }, "mean": { "type": "number" }, "p50": { "type": "number" }, "p90": { "type": "number" }, "partial": { "type": "boolean" }, "otherPov": { "type": "object", "properties": { "pov": { "type": "string", "enum": [ "persona", "agent" ] }, "derived": { "type": "boolean" }, "reportedBy": { "type": "string" }, "samples": { "type": "array", "items": { "type": "number" } }, "spanIds": { "type": "array", "items": { "type": "string" } }, "partial": { "type": "boolean" } }, "required": [ "pov", "derived", "samples", "spanIds", "partial" ], "additionalProperties": false, "description": "The same metric measured from the other side of a simulation. Keep its samples separate from the primary series. Absent when only one side measured the conversation, including production traces." } }, "required": [ "measure", "unit", "derived", "pov", "samples", "spanIds", "mean", "p50", "p90", "partial" ], "additionalProperties": false }, "description": "Observed facts about the conversation, such as latency and duration. Metrics are separate from grader results." }, "test": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scenario": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expectedBehaviors": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "versionId", "name", "scenario", "expectedBehaviors" ], "additionalProperties": false }, "persona": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "versionId": { "type": "string", "minLength": 1 }, "identityName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "personality": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "versionId", "identityName", "personality", "language" ], "additionalProperties": false }, "agent": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archived": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "id", "name", "archived" ], "additionalProperties": false }, "connection": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archived": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "id", "name", "archived" ], "additionalProperties": false }, "connectionSnapshot": { "type": "object", "properties": { "agentPlatform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "connectionType": { "type": "string" }, "accessVariant": { "type": "string" }, "modality": { "type": "string", "enum": [ "voice", "chat" ] }, "topology": { "type": "string" }, "environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "config": {} }, "required": [ "agentPlatform", "connectionType", "accessVariant", "modality", "topology", "environment", "config" ], "additionalProperties": false }, "gradingPlan": { "anyOf": [ { "type": "object", "description": "The grader definitions, versions, and pass thresholds frozen when the run started. Regrading uses this selection.", "properties": { "capturedAt": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "type": "object", "properties": { "projectGraderId": { "type": "string", "minLength": 1 }, "graderDefinitionId": { "type": "string", "minLength": 1 }, "graderDefinitionVersion": { "type": "integer", "minimum": 1 }, "graderName": { "type": "string" }, "passThreshold": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "projectGraderId", "graderDefinitionId", "graderDefinitionVersion", "graderName", "passThreshold" ], "additionalProperties": false } } }, "required": [ "capturedAt", "items" ], "additionalProperties": false }, { "type": "null" } ] }, "transcript": { "anyOf": [ { "type": "object", "properties": { "traceId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": "string", "format": "date-time" }, "durationNs": { "type": "string" }, "spanCount": { "type": "integer" }, "turnCounts": { "type": "object", "properties": { "human": { "type": "integer" }, "agent": { "type": "integer" } }, "required": [ "human", "agent" ], "additionalProperties": false }, "toolSpanCount": { "type": "integer" }, "erroredSpanCount": { "type": "integer" }, "turns": { "type": "array", "items": { "$ref": "#/components/schemas/traceSpan" } }, "spans": { "type": "array", "items": { "$ref": "#/components/schemas/traceSpan" } }, "spansTruncated": { "type": "boolean", "description": "True when the response's span limit prevented the complete trace tree from being returned." } }, "required": [ "traceId", "startedAt", "endedAt", "durationNs", "spanCount", "turnCounts", "toolSpanCount", "erroredSpanCount", "turns", "spans", "spansTruncated" ], "additionalProperties": false }, { "type": "null" } ], "description": "The conversation and tool evidence available for this simulation. Null when no trace is available." } }, "required": [ "id", "projectId", "runId", "runName", "position", "status", "gradingState", "evidenceError", "grades", "gradeHistory", "combinedScore", "reason", "executionFailure", "workBlock", "modality", "createdAt", "startedAt", "endedAt", "providerReference", "hasRecording", "agentPovComplete", "agentPovIncomplete", "measures", "metrics", "test", "persona", "agent", "connection", "connectionSnapshot", "gradingPlan", "transcript" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/simulations/{simulationId}/regrade": { "post": { "operationId": "regradeSimulation", "summary": "Regrade a simulation", "description": "Grade a completed simulation again with its original grader selection and recorded evidence. Later grader settings do not apply. Send no body, then follow gradingState with Get a simulation.", "tags": [ "Simulations" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "simulationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Simulation ID returned by List simulations in a run.", "examples": [ "sim_01M0E4J0BBE1FVDVTZ1BSS5C97" ] } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The grading request was accepted. The response does not wait for new grades.", "content": { "application/json": { "schema": { "type": "object", "properties": { "simulationId": { "type": "string", "minLength": 1, "description": "The simulation whose existing trace will be graded." }, "reopened": { "type": "integer", "description": "1 if an existing finished grading job was reopened; 0 otherwise. A newly created job can also return 0." }, "alreadyWaiting": { "type": "integer", "description": "1 if grading was already pending or claimed, so no duplicate job was created; 0 otherwise." } }, "required": [ "simulationId", "reopened", "alreadyWaiting" ], "additionalProperties": false, "examples": [ { "simulationId": "sim_01M0E4J0BBE1FVDVTZ1BSS5C97", "reopened": 1, "alreadyWaiting": 0 } ] } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/test-suites": { "get": { "operationId": "listTestSuites", "summary": "List test suites", "tags": [ "Test Suites" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "A page of active test suites.", "content": { "application/json": { "schema": { "type": "object", "properties": { "testSuites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "name", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextPageToken": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "testSuites", "nextPageToken" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "post": { "operationId": "createTestSuite", "summary": "Create a test suite", "description": "Creates an empty suite in the current project. Add tests before starting a run. A suite stores no agent or connection; each run selects those and executes every active test in the suite.", "tags": [ "Test Suites" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The suite's display name. Its stable ID identifies it across renames." } }, "required": [ "name" ], "additionalProperties": false, "examples": [ { "name": "Appointment booking" } ] } } } }, "responses": { "201": { "description": "The new test suite.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "name", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/test-suites/{suiteId}": { "get": { "operationId": "getTestSuite", "summary": "Get a test suite", "tags": [ "Test Suites" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "suiteId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The test suite.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "name", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "patch": { "operationId": "updateTestSuite", "summary": "Rename a test suite", "description": "Changes the display name without changing the suite's ID or membership. Earlier runs display the current suite name.", "tags": [ "Test Suites" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "suiteId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The suite's display name. Its stable ID identifies it across renames." } }, "required": [ "name" ], "additionalProperties": false, "examples": [ { "name": "Appointment booking" } ] } } } }, "responses": { "200": { "description": "The renamed test suite.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "name", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "delete": { "operationId": "deleteTestSuite", "summary": "Permanently delete a test suite from authoring", "description": "The suite and its tests leave authoring permanently. Existing run evidence stays readable.", "tags": [ "Test Suites" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "suiteId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "204": { "description": "The test suite was deleted." }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/tests": { "get": { "operationId": "listTests", "summary": "List the active tests in a test suite", "tags": [ "Tests" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "suiteId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The test suite to read. Tests are listed one suite at a time." } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "A page of tests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "suiteId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "versionId": { "type": "string", "minLength": 1 }, "scenario": { "type": "string" }, "expectedBehaviors": { "type": "array", "items": { "type": "string" } }, "personas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "archivedAt" ], "additionalProperties": false } }, "mockTools": { "type": "array", "items": { "description": "One named tool's fixed response for this test. Supply exactly one of answer or error. Tools without a mock run normally.", "oneOf": [ { "type": "object", "properties": { "tool": { "type": "string" }, "answer": {}, "error": { "not": {} } }, "required": [ "tool", "answer" ], "additionalProperties": false }, { "type": "object", "properties": { "tool": { "type": "string" }, "answer": { "not": {} }, "error": { "type": "string" } }, "required": [ "tool", "error" ], "additionalProperties": false } ] } }, "env": { "anyOf": [ { "type": "object", "properties": { "retell_dynamic_variables": { "type": "object", "description": "String values supplied to the Retell agent before the conversation. Variable names beginning with egma_ are reserved.", "additionalProperties": { "type": "string" } }, "job_dispatch_metadata": { "type": "object", "description": "Context delivered to the LiveKit worker in ctx.job.metadata.", "additionalProperties": true } }, "additionalProperties": false }, { "type": "null" } ] }, "revision": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "suiteId", "name", "description", "version", "versionId", "scenario", "expectedBehaviors", "personas", "mockTools", "env", "revision", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextPageToken": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "tests", "nextPageToken" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "post": { "operationId": "createTest", "summary": "Create a test in a test suite", "description": "Creates the test and its first content version in an existing suite. Choose at least one persona. The agent and connection are selected when starting a run, not when creating the test.", "tags": [ "Tests" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "suiteId": { "type": "string", "minLength": 1, "description": "An existing active test suite in the current project." }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scenario": { "type": "string", "description": "The situation and goal the synthetic caller acts out." }, "expectedBehaviors": { "type": "array", "items": { "type": "string" }, "description": "Statements checked independently against the completed conversation. Include at least one non-empty statement." }, "personas": { "type": "array", "items": { "type": "string" }, "description": "At least one available persona ID or unambiguous current name. Each selected persona creates one simulation for this test in a run." }, "mockTools": { "type": "array", "items": { "description": "One named tool's fixed response for this test. Supply exactly one of answer or error. Tools without a mock run normally.", "oneOf": [ { "type": "object", "properties": { "tool": { "type": "string" }, "answer": {}, "error": { "not": {} } }, "required": [ "tool", "answer" ], "additionalProperties": false }, { "type": "object", "properties": { "tool": { "type": "string" }, "answer": { "not": {} }, "error": { "type": "string" } }, "required": [ "tool", "error" ], "additionalProperties": false } ] }, "description": "Test-owned tool answers. Use an empty array to remove existing mocks on update. Applying mocks requires a supported connection and, for LiveKit, tool instrumentation." }, "env": { "anyOf": [ { "type": "object", "properties": { "retell_dynamic_variables": { "type": "object", "description": "String values supplied to the Retell agent before the conversation. Variable names beginning with egma_ are reserved.", "additionalProperties": { "type": "string" } }, "job_dispatch_metadata": { "type": "object", "description": "Context delivered to the LiveKit worker in ctx.job.metadata.", "additionalProperties": true } }, "additionalProperties": false }, { "type": "null" } ], "description": "Non-secret startup context for the agent's provider. Omit to keep existing context on update, or send null to clear it." } }, "required": [ "suiteId", "name", "scenario", "expectedBehaviors", "personas" ], "additionalProperties": false, "examples": [ { "suiteId": "ste_01M0E4EVJ6ECGVJEA4NSBTC0CC", "name": "No available appointments", "description": "The caller asks for an appointment when the calendar is full.", "scenario": "Ask Harbor Clinic for an afternoon appointment. If none is available, ask how to arrange a callback.", "expectedBehaviors": [ "The agent calls check_availability.", "The agent says that no appointments are available and does not offer a time." ], "personas": [ "Everyday caller" ], "mockTools": [ { "tool": "check_availability", "answer": { "slots": [] } } ], "env": { "retell_dynamic_variables": { "clinic_name": "Harbor Clinic" } } } ] } } } }, "responses": { "201": { "description": "The new test.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "suiteId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "versionId": { "type": "string", "minLength": 1 }, "scenario": { "type": "string" }, "expectedBehaviors": { "type": "array", "items": { "type": "string" } }, "personas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "archivedAt" ], "additionalProperties": false } }, "mockTools": { "type": "array", "items": { "description": "One named tool's fixed response for this test. Supply exactly one of answer or error. Tools without a mock run normally.", "oneOf": [ { "type": "object", "properties": { "tool": { "type": "string" }, "answer": {}, "error": { "not": {} } }, "required": [ "tool", "answer" ], "additionalProperties": false }, { "type": "object", "properties": { "tool": { "type": "string" }, "answer": { "not": {} }, "error": { "type": "string" } }, "required": [ "tool", "error" ], "additionalProperties": false } ] } }, "env": { "anyOf": [ { "type": "object", "properties": { "retell_dynamic_variables": { "type": "object", "description": "String values supplied to the Retell agent before the conversation. Variable names beginning with egma_ are reserved.", "additionalProperties": { "type": "string" } }, "job_dispatch_metadata": { "type": "object", "description": "Context delivered to the LiveKit worker in ctx.job.metadata.", "additionalProperties": true } }, "additionalProperties": false }, { "type": "null" } ] }, "revision": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "suiteId", "name", "description", "version", "versionId", "scenario", "expectedBehaviors", "personas", "mockTools", "env", "revision", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/test-versions/{versionId}": { "get": { "operationId": "getTestVersion", "summary": "Get a test version", "description": "Read the frozen scenario, expected behaviors, persona selections, mocks, and context used by a simulation. Later test edits do not change this version.", "tags": [ "Tests" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The frozen test version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "testId": { "type": "string", "minLength": 1 }, "suiteId": { "type": "string", "minLength": 1 }, "testName": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "current": { "type": "boolean" }, "scenario": { "type": "string" }, "expectedBehaviors": { "type": "array", "items": { "type": "string" } }, "personas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "archivedAt" ], "additionalProperties": false } }, "mockTools": { "type": "array", "items": { "description": "One named tool's fixed response for this test. Supply exactly one of answer or error. Tools without a mock run normally.", "oneOf": [ { "type": "object", "properties": { "tool": { "type": "string" }, "answer": {}, "error": { "not": {} } }, "required": [ "tool", "answer" ], "additionalProperties": false }, { "type": "object", "properties": { "tool": { "type": "string" }, "answer": { "not": {} }, "error": { "type": "string" } }, "required": [ "tool", "error" ], "additionalProperties": false } ] } }, "env": { "anyOf": [ { "type": "object", "properties": { "retell_dynamic_variables": { "type": "object", "description": "String values supplied to the Retell agent before the conversation. Variable names beginning with egma_ are reserved.", "additionalProperties": { "type": "string" } }, "job_dispatch_metadata": { "type": "object", "description": "Context delivered to the LiveKit worker in ctx.job.metadata.", "additionalProperties": true } }, "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "testId", "suiteId", "testName", "version", "current", "scenario", "expectedBehaviors", "personas", "mockTools", "env", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/tests/{testId}": { "get": { "operationId": "getTest", "summary": "Get a test", "tags": [ "Tests" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "testId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The test.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "suiteId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "versionId": { "type": "string", "minLength": 1 }, "scenario": { "type": "string" }, "expectedBehaviors": { "type": "array", "items": { "type": "string" } }, "personas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "archivedAt" ], "additionalProperties": false } }, "mockTools": { "type": "array", "items": { "description": "One named tool's fixed response for this test. Supply exactly one of answer or error. Tools without a mock run normally.", "oneOf": [ { "type": "object", "properties": { "tool": { "type": "string" }, "answer": {}, "error": { "not": {} } }, "required": [ "tool", "answer" ], "additionalProperties": false }, { "type": "object", "properties": { "tool": { "type": "string" }, "answer": { "not": {} }, "error": { "type": "string" } }, "required": [ "tool", "error" ], "additionalProperties": false } ] } }, "env": { "anyOf": [ { "type": "object", "properties": { "retell_dynamic_variables": { "type": "object", "description": "String values supplied to the Retell agent before the conversation. Variable names beginning with egma_ are reserved.", "additionalProperties": { "type": "string" } }, "job_dispatch_metadata": { "type": "object", "description": "Context delivered to the LiveKit worker in ctx.job.metadata.", "additionalProperties": true } }, "additionalProperties": false }, { "type": "null" } ] }, "revision": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "suiteId", "name", "description", "version", "versionId", "scenario", "expectedBehaviors", "personas", "mockTools", "env", "revision", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "patch": { "operationId": "updateTest", "summary": "Update a test", "description": "Omitted fields keep their current values. Content changes create an immutable version and require expectedVersionId from the last read. Name and description changes keep the content version. Existing simulations retain their original evidence.", "tags": [ "Tests" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "testId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scenario": { "type": "string", "description": "The situation and goal the synthetic caller acts out." }, "expectedBehaviors": { "type": "array", "items": { "type": "string" }, "description": "Statements checked independently against the completed conversation. Include at least one non-empty statement." }, "personas": { "type": "array", "items": { "type": "string" }, "description": "At least one available persona ID or unambiguous current name. Each selected persona creates one simulation for this test in a run." }, "mockTools": { "type": "array", "items": { "description": "One named tool's fixed response for this test. Supply exactly one of answer or error. Tools without a mock run normally.", "oneOf": [ { "type": "object", "properties": { "tool": { "type": "string" }, "answer": {}, "error": { "not": {} } }, "required": [ "tool", "answer" ], "additionalProperties": false }, { "type": "object", "properties": { "tool": { "type": "string" }, "answer": { "not": {} }, "error": { "type": "string" } }, "required": [ "tool", "error" ], "additionalProperties": false } ] }, "description": "Test-owned tool answers. Use an empty array to remove existing mocks on update. Applying mocks requires a supported connection and, for LiveKit, tool instrumentation." }, "env": { "anyOf": [ { "type": "object", "properties": { "retell_dynamic_variables": { "type": "object", "description": "String values supplied to the Retell agent before the conversation. Variable names beginning with egma_ are reserved.", "additionalProperties": { "type": "string" } }, "job_dispatch_metadata": { "type": "object", "description": "Context delivered to the LiveKit worker in ctx.job.metadata.", "additionalProperties": true } }, "additionalProperties": false }, { "type": "null" } ], "description": "Non-secret startup context for the agent's provider. Omit to keep existing context on update, or send null to clear it." }, "expectedVersionId": { "type": "string", "minLength": 1, "description": "The versionId returned by the test read. Required when changing scenario, expectedBehaviors, personas, mockTools, or env; a stale value returns 409." }, "expectedRevision": { "type": "string", "minLength": 1, "description": "The revision returned by the test read. Supply it to reject an update if the test's live identity changed since that read." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The updated test.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "suiteId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "versionId": { "type": "string", "minLength": 1 }, "scenario": { "type": "string" }, "expectedBehaviors": { "type": "array", "items": { "type": "string" } }, "personas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "archivedAt" ], "additionalProperties": false } }, "mockTools": { "type": "array", "items": { "description": "One named tool's fixed response for this test. Supply exactly one of answer or error. Tools without a mock run normally.", "oneOf": [ { "type": "object", "properties": { "tool": { "type": "string" }, "answer": {}, "error": { "not": {} } }, "required": [ "tool", "answer" ], "additionalProperties": false }, { "type": "object", "properties": { "tool": { "type": "string" }, "answer": { "not": {} }, "error": { "type": "string" } }, "required": [ "tool", "error" ], "additionalProperties": false } ] } }, "env": { "anyOf": [ { "type": "object", "properties": { "retell_dynamic_variables": { "type": "object", "description": "String values supplied to the Retell agent before the conversation. Variable names beginning with egma_ are reserved.", "additionalProperties": { "type": "string" } }, "job_dispatch_metadata": { "type": "object", "description": "Context delivered to the LiveKit worker in ctx.job.metadata.", "additionalProperties": true } }, "additionalProperties": false }, { "type": "null" } ] }, "revision": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "projectId", "suiteId", "name", "description", "version", "versionId", "scenario", "expectedBehaviors", "personas", "mockTools", "env", "revision", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The test content or identity moved after the write was based on it.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "const": "version_conflict" }, "message": { "type": "string" }, "test": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "expectedVersionId": { "type": "string", "minLength": 1 }, "currentVersionId": { "type": "string", "minLength": 1 } }, "required": [ "error", "message", "test", "expectedVersionId", "currentVersionId" ], "additionalProperties": false }, { "$ref": "#/components/schemas/Refusal" } ] } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "delete": { "operationId": "deleteTest", "summary": "Permanently delete a test from authoring", "description": "The test leaves authoring permanently only while expectedVersionId and expectedRevision are both still current. Existing run evidence stays readable.", "tags": [ "Tests" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "testId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "expectedVersionId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "expectedRevision", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "204": { "description": "The test was deleted." }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "The test content or identity moved after the write was based on it.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "const": "version_conflict" }, "message": { "type": "string" }, "test": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "expectedVersionId": { "type": "string", "minLength": 1 }, "currentVersionId": { "type": "string", "minLength": 1 } }, "required": [ "error", "message", "test", "expectedVersionId", "currentVersionId" ], "additionalProperties": false }, { "$ref": "#/components/schemas/Refusal" } ] } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/tests/{testId}/versions": { "get": { "operationId": "listTestVersions", "summary": "List test versions", "tags": [ "Tests" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "testId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "A page of frozen test versions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "testId": { "type": "string", "minLength": 1 }, "suiteId": { "type": "string", "minLength": 1 }, "testName": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "current": { "type": "boolean" }, "scenario": { "type": "string" }, "expectedBehaviors": { "type": "array", "items": { "type": "string" } }, "personas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "archivedAt" ], "additionalProperties": false } }, "mockTools": { "type": "array", "items": { "description": "One named tool's fixed response for this test. Supply exactly one of answer or error. Tools without a mock run normally.", "oneOf": [ { "type": "object", "properties": { "tool": { "type": "string" }, "answer": {}, "error": { "not": {} } }, "required": [ "tool", "answer" ], "additionalProperties": false }, { "type": "object", "properties": { "tool": { "type": "string" }, "answer": { "not": {} }, "error": { "type": "string" } }, "required": [ "tool", "error" ], "additionalProperties": false } ] } }, "env": { "anyOf": [ { "type": "object", "properties": { "retell_dynamic_variables": { "type": "object", "description": "String values supplied to the Retell agent before the conversation. Variable names beginning with egma_ are reserved.", "additionalProperties": { "type": "string" } }, "job_dispatch_metadata": { "type": "object", "description": "Context delivered to the LiveKit worker in ctx.job.metadata.", "additionalProperties": true } }, "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "testId", "suiteId", "testName", "version", "current", "scenario", "expectedBehaviors", "personas", "mockTools", "env", "createdAt" ], "additionalProperties": false } }, "nextPageToken": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "versions", "nextPageToken" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "422": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/traces": { "get": { "operationId": "listTraces", "summary": "List traces", "tags": [ "Traces" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "simulation", "production" ] } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of traces inside the requested window.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traces": { "type": "array", "items": { "type": "object", "properties": { "traceId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": "string", "format": "date-time" }, "durationNs": { "type": "string" }, "spanCount": { "type": "integer" }, "turnCounts": { "type": "object", "properties": { "human": { "type": "integer" }, "agent": { "type": "integer" } }, "required": [ "human", "agent" ], "additionalProperties": false }, "toolSpanCount": { "type": "integer" }, "erroredSpanCount": { "type": "integer" }, "source": { "type": "string", "enum": [ "simulation", "production" ] }, "pov": { "type": "string", "enum": [ "persona", "agent" ], "description": "The trace's primary source: agent for the agent's own evidence, or persona for Egma's simulated caller. A simulation can contain spans from both sources; each span has its own pov." }, "environment": { "type": "string" }, "connectionType": { "type": "string" }, "providerCallId": { "type": "string" }, "agentPlatform": { "type": "string" }, "platformAgentId": { "type": "string" }, "platformAgentName": { "type": "string" }, "platformAgentVersion": { "type": "string" }, "runId": { "type": "string" }, "agentId": { "type": "string" }, "preview": { "type": "string" }, "turnResponseLatencyP90Milliseconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "turnResponseLatencyP90Partial": { "type": "boolean" } }, "required": [ "traceId", "startedAt", "endedAt", "durationNs", "spanCount", "turnCounts", "toolSpanCount", "erroredSpanCount", "source", "pov", "environment", "connectionType", "providerCallId", "agentPlatform", "platformAgentId", "platformAgentName", "platformAgentVersion", "runId", "agentId", "preview", "turnResponseLatencyP90Milliseconds", "turnResponseLatencyP90Partial" ], "additionalProperties": false } }, "nextPageToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "from", "to" ], "additionalProperties": false } }, "required": [ "traces", "nextPageToken", "window" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/v1/traces/{traceId}": { "get": { "operationId": "getTrace", "summary": "Get a trace", "tags": [ "Traces" ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The trace and its grades.", "content": { "application/json": { "schema": { "type": "object", "properties": { "trace": { "type": "object", "properties": { "traceId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": "string", "format": "date-time" }, "durationNs": { "type": "string" }, "spanCount": { "type": "integer" }, "turnCounts": { "type": "object", "properties": { "human": { "type": "integer" }, "agent": { "type": "integer" } }, "required": [ "human", "agent" ], "additionalProperties": false }, "toolSpanCount": { "type": "integer" }, "erroredSpanCount": { "type": "integer" }, "source": { "type": "string", "enum": [ "simulation", "production" ] }, "pov": { "type": "string", "enum": [ "persona", "agent" ], "description": "The trace's primary source: agent for the agent's own evidence, or persona for Egma's simulated caller. A simulation can contain spans from both sources; each span has its own pov." }, "environment": { "type": "string" }, "connectionType": { "type": "string" }, "providerCallId": { "type": "string" }, "agentPlatform": { "type": "string" }, "platformAgentId": { "type": "string" }, "platformAgentName": { "type": "string" }, "platformAgentVersion": { "type": "string" }, "runId": { "type": "string" }, "agentId": { "type": "string" } }, "required": [ "traceId", "startedAt", "endedAt", "durationNs", "spanCount", "turnCounts", "toolSpanCount", "erroredSpanCount", "source", "pov", "environment", "connectionType", "providerCallId", "agentPlatform", "platformAgentId", "platformAgentName", "platformAgentVersion", "runId", "agentId" ], "additionalProperties": false }, "turns": { "type": "array", "items": { "$ref": "#/components/schemas/traceSpan" } }, "spans": { "type": "array", "items": { "$ref": "#/components/schemas/traceSpan" } }, "spansTruncated": { "type": "boolean" }, "metrics": { "type": "array", "items": { "type": "object", "description": "One metric from one side of the conversation. Simulation metrics prefer the persona's series when available. Production traces use the agent's evidence. A second series stays separate in otherPov.", "properties": { "measure": { "type": "string", "description": "Metric identifier. turn_response_latency measures the wait from the end of the caller's turn to the agent's reply. For voice simulations, it runs from the end of the caller's played audio, including trailing padding, to the arrival of the agent's audio. first_response_latency measures the wait from conversation start to the first reply. Both use milliseconds." }, "unit": { "type": "string" }, "derived": { "type": "boolean" }, "pov": { "type": "string", "enum": [ "persona", "agent" ], "description": "The source of these measurements: agent for the agent's own evidence, or persona for Egma's simulated caller. The samples and summary values describe only this source." }, "reportedBy": { "type": "string" }, "samples": { "type": "array", "items": { "type": "number" } }, "spanIds": { "type": "array", "items": { "type": "string" } }, "mean": { "type": "number" }, "p50": { "type": "number" }, "p90": { "type": "number" }, "partial": { "type": "boolean" }, "otherPov": { "type": "object", "properties": { "pov": { "type": "string", "enum": [ "persona", "agent" ] }, "derived": { "type": "boolean" }, "reportedBy": { "type": "string" }, "samples": { "type": "array", "items": { "type": "number" } }, "spanIds": { "type": "array", "items": { "type": "string" } }, "partial": { "type": "boolean" } }, "required": [ "pov", "derived", "samples", "spanIds", "partial" ], "additionalProperties": false, "description": "The same metric measured from the other side of a simulation. Keep its samples separate from the primary series. Absent when only one side measured the conversation, including production traces." } }, "required": [ "measure", "unit", "derived", "pov", "samples", "spanIds", "mean", "p50", "p90", "partial" ], "additionalProperties": false } }, "simulationId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "gradingState": { "type": "string", "enum": [ "not_requested", "pending", "running", "complete", "error" ] }, "workBlock": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "enum": [ "allowance_spent", "providers_unfunded" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "grades": { "type": "array", "items": { "type": "object", "properties": { "projectGraderId": { "type": "string", "minLength": 1 }, "graderDefinitionId": { "type": "string", "minLength": 1 }, "graderDefinitionVersion": { "type": "integer", "minimum": 1 }, "parameterValues": { "type": "object", "additionalProperties": true, "description": "The model or numeric settings used for this grading attempt. Retained for successful and errored grades, including after temporary jobs are removed. Contains no credentials." }, "graderName": { "type": "string" }, "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "details": { "type": "object", "properties": { "rationale": { "type": "string" }, "assertions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "decision": { "type": "string", "enum": [ "met", "not_met", "cannot_determine" ] }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, "rationale": { "type": "string" }, "citedSpanIds": { "type": "array", "items": { "type": "string" } }, "citedTurns": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "error": { "type": "string" } }, "required": [ "key" ], "additionalProperties": false } }, "error": { "type": "string" } }, "additionalProperties": true }, "passThreshold": { "type": "number", "minimum": 0, "maximum": 1 }, "result": { "type": "string", "enum": [ "passed", "failed", "errored" ] }, "gradedAt": { "type": "string", "format": "date-time" } }, "required": [ "projectGraderId", "graderDefinitionId", "graderDefinitionVersion", "parameterValues", "graderName", "score", "details", "passThreshold", "result", "gradedAt" ], "additionalProperties": false }, "description": "The current result for each selected grader. Each grade has its own score, frozen threshold, result, and supporting details." }, "gradeHistory": { "type": "array", "items": { "type": "object", "properties": { "projectGraderId": { "type": "string", "minLength": 1 }, "graderDefinitionId": { "type": "string", "minLength": 1 }, "graderDefinitionVersion": { "type": "integer", "minimum": 1 }, "parameterValues": { "type": "object", "additionalProperties": true, "description": "The model or numeric settings used for this grading attempt. Retained for successful and errored grades, including after temporary jobs are removed. Contains no credentials." }, "graderName": { "type": "string" }, "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "details": { "type": "object", "properties": { "rationale": { "type": "string" }, "assertions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "decision": { "type": "string", "enum": [ "met", "not_met", "cannot_determine" ] }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, "rationale": { "type": "string" }, "citedSpanIds": { "type": "array", "items": { "type": "string" } }, "citedTurns": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "error": { "type": "string" } }, "required": [ "key" ], "additionalProperties": false } }, "error": { "type": "string" } }, "additionalProperties": true }, "passThreshold": { "type": "number", "minimum": 0, "maximum": 1 }, "result": { "type": "string", "enum": [ "passed", "failed", "errored" ] }, "gradedAt": { "type": "string", "format": "date-time" } }, "required": [ "projectGraderId", "graderDefinitionId", "graderDefinitionVersion", "parameterValues", "graderName", "score", "details", "passThreshold", "result", "gradedAt" ], "additionalProperties": false }, "description": "Recorded grade results, including previous grading attempts. Regrading preserves this history." }, "combinedScore": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ], "description": "Display-only arithmetic mean when every selected grader has a current score. Null while a required score is missing or errored. This is not an overall pass/fail result." } }, "required": [ "trace", "turns", "spans", "spansTruncated", "metrics", "simulationId", "gradingState", "workBlock", "grades", "gradeHistory", "combinedScore" ], "additionalProperties": false } } } }, "400": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "401": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "The request was refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "429": { "description": "The request rate limit was reached.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An Egma API key." }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "egma.session_token", "description": "The browser session cookie issued by Egma. HTTPS deployments add the standard __Secure- prefix." } }, "schemas": { "Refusal": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false }, "traceSpan": { "type": "object", "properties": { "spanId": { "type": "string" }, "parentSpanId": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "status": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "durationNs": { "type": "string" }, "text": { "type": "string" }, "audioUrl": { "type": "string" }, "toolName": { "type": "string" }, "toolArguments": { "type": "string" }, "toolResult": { "type": "string" }, "pov": { "type": "string", "enum": [ "persona", "agent" ], "description": "Whose account this span records: agent for the agent’s own turns and tools, or persona for Egma’s caller. Read the agent spans for one transcript; combining both repeats the conversation." }, "toolProvenance": { "type": "string", "enum": [ "mocked" ], "description": "Present when a mock with this toolName answered the call. Read from the simulation’s pinned test version. Absent on ordinary tool calls and production traces." }, "spans": { "type": "array", "items": { "$ref": "#/components/schemas/traceSpan" } } }, "required": [ "spanId", "parentSpanId", "name", "kind", "status", "startedAt", "durationNs", "text", "audioUrl", "toolName", "toolArguments", "toolResult", "pov", "spans" ], "additionalProperties": false } } } }