{ "openapi": "3.1.0", "info": { "title": "Roark Analytics API", "description": "The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform.", "version": "1.0.0" }, "components": { "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "degraded", "unhealthy" ] }, "version": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "status", "version", "timestamp" ], "description": "Health check response payload", "example": { "status": "healthy", "version": "1.0.0", "timestamp": "2026-05-18T09:44:40.971Z" } }, "ErrorResponse": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "validation", "authentication", "forbidden", "not_found", "conflict", "payment_required", "rate_limit", "internal" ], "description": "The error type category", "examples": [ "validation", "authentication" ] }, "code": { "type": "string", "description": "Machine-readable error code identifier", "examples": [ "invalid_parameter", "missing_required_field", "unauthorized" ] }, "message": { "type": "string", "description": "Human-readable error message", "examples": [ "The request was invalid", "Authentication required" ] }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "examples": [ "email", "user_id" ] }, "details": { "description": "Additional error context information" } }, "required": [ "type", "code", "message" ] }, "MeResponse": { "type": "object", "properties": { "tokenScope": { "type": "string", "enum": [ "PROJECT", "USER" ] }, "user": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "name" ] }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "defaultProject": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] }, "grantedPermissions": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "tokenScope", "user", "organization", "defaultProject", "grantedPermissions", "scopes" ], "description": "The credential making this request, and what it is bound to", "example": { "tokenScope": "USER", "user": { "id": "0b2b1c34-5d6e-4f70-8192-a3b4c5d6e7f8", "email": "ada@example.com", "name": "Ada Lovelace" }, "organization": { "id": "9f8e7d6c-5b4a-4312-9081-7f6e5d4c3b2a", "name": "Example Inc" }, "defaultProject": { "id": "1a2b3c4d-5e6f-4701-8293-a4b5c6d7e8f9", "name": "Support Line", "slug": "support-line" }, "grantedPermissions": [ "call:read", "metric:read" ], "scopes": [ "READ" ] } }, "MeApiKeyListResponse": { "type": "object", "properties": { "apiKeys": { "type": "array", "items": { "$ref": "#/components/schemas/MeApiKey" } } }, "required": [ "apiKeys" ], "description": "The credentials that act as the caller" }, "MeApiKey": { "type": "object", "properties": { "id": { "type": "string", "description": "Roark ID of the credential. Pass it to DELETE to revoke." }, "name": { "type": "string", "description": "The label chosen when it was created" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp" }, "lastUsedAt": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp, null if never used" }, "expiresAt": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp, null if it never expires" }, "status": { "type": [ "string", "null" ], "enum": [ "ACTIVE", "REVOKED" ] }, "organizationId": { "type": [ "string", "null" ], "description": "The organization this credential is pinned to" }, "defaultProjectId": { "type": [ "string", "null" ], "description": "The project a request acts on when it sends no X-Roark-Project-Id header. Null once that project is deleted." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Coarse tier: READ, or WRITE for read and write" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Granted 'resource:action' permissions" } }, "required": [ "id", "name", "createdAt", "lastUsedAt", "expiresAt", "status", "organizationId", "defaultProjectId", "scopes", "permissions" ], "description": "A credential that acts as the caller", "example": { "id": "7c6d5e4f-3a2b-4109-8765-4f3e2d1c0b9a", "name": "CLI on laptop", "createdAt": "2026-09-28T11:04:00.000Z", "lastUsedAt": "2026-10-02T08:12:31.000Z", "expiresAt": null, "status": "ACTIVE", "organizationId": "9f8e7d6c-5b4a-4312-9081-7f6e5d4c3b2a", "defaultProjectId": "1a2b3c4d-5e6f-4701-8293-a4b5c6d7e8f9", "scopes": [ "READ" ], "permissions": [ "call:read", "metric:read" ] } }, "CreateMyApiKeyResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Roark ID of the credential. Pass it to DELETE to revoke." }, "name": { "type": "string", "description": "The label chosen when it was created" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp" }, "lastUsedAt": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp, null if never used" }, "expiresAt": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp, null if it never expires" }, "status": { "type": [ "string", "null" ], "enum": [ "ACTIVE", "REVOKED" ] }, "organizationId": { "type": [ "string", "null" ], "description": "The organization this credential is pinned to" }, "defaultProjectId": { "type": [ "string", "null" ], "description": "The project a request acts on when it sends no X-Roark-Project-Id header. Null once that project is deleted." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Coarse tier: READ, or WRITE for read and write" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Granted 'resource:action' permissions" }, "key": { "type": "string", "description": "The credential value. Returned only here, only once." } }, "required": [ "id", "name", "createdAt", "lastUsedAt", "expiresAt", "status", "organizationId", "defaultProjectId", "scopes", "permissions", "key" ], "description": "The created credential, with its key", "example": { "id": "7c6d5e4f-3a2b-4109-8765-4f3e2d1c0b9a", "name": "CI deploy gate", "createdAt": "2026-10-05T09:30:00.000Z", "lastUsedAt": null, "expiresAt": null, "status": "ACTIVE", "organizationId": "9f8e7d6c-5b4a-4312-9081-7f6e5d4c3b2a", "defaultProjectId": "1a2b3c4d-5e6f-4701-8293-a4b5c6d7e8f9", "scopes": [ "READ" ], "permissions": [ "call:read", "metric:read" ], "key": "roark0f1e2d3c4b5a69788796a5b4c3d2e1f09182" } }, "CreateMyApiKeyInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "A label you will recognise later. It is the only thing that tells two credentials apart in the list you revoke from.", "example": "CI deploy gate" }, "projectId": { "type": "string", "description": "Project the credential assumes when a request sends no X-Roark-Project-Id header. Defaults to the calling credential's own default project. You must be an admin of whichever project is used." }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "READ", "WRITE" ] }, "minItems": 1, "description": "Coarse tier. Defaults to the calling credential's own tier, and can never exceed it: a READ credential cannot mint a WRITE one.", "example": [ "READ" ] }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Granular 'resource:action' permissions. Defaults to the calling credential's own set, and can never exceed it. A ceiling, not an entitlement: the holder still only reaches what their project membership allows.", "example": [ "call:read", "metric:read" ] }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO 8601 expiry. Defaults to the calling credential's own expiry (no expiry, for a `roark auth login` credential) and may not outlive it, so a short-lived connector credential cannot mint a permanent one.", "example": "2026-12-31T23:59:59.000Z" } }, "required": [ "name" ], "description": "A personal credential to mint for the caller" }, "MeApiKeyRevokeResponse": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true, "description": "Always true when the credential was revoked" } }, "required": [ "id", "deleted" ], "description": "Result of revoking one of your credentials" }, "ProjectListResponse": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "grantedPermissions": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "slug", "organization", "grantedPermissions" ] } } }, "required": [ "projects" ], "description": "Projects this credential may act on", "example": { "projects": [ { "id": "1a2b3c4d-5e6f-4701-8293-a4b5c6d7e8f9", "name": "Support Line", "slug": "support-line", "organization": { "id": "9f8e7d6c-5b4a-4312-9081-7f6e5d4c3b2a", "name": "Example Inc" }, "grantedPermissions": [ "call:read", "metric:read" ] } ] } }, "AgentEndpointDetailResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Agent endpoint ID" }, "agentId": { "type": "string", "format": "uuid", "description": "Agent ID this endpoint belongs to" }, "type": { "type": "string", "enum": [ "PHONE", "WEBSOCKET", "LIVEKIT", "SMALL_WEBRTC", "ELEVENLABS_WS", "KORE", "GOOGLE_CES", "DAILY" ], "description": "Agent endpoint type (PHONE, WEBSOCKET, LIVEKIT, SMALL_WEBRTC, or ELEVENLABS_WS)" }, "value": { "type": "string", "description": "Agent endpoint value (phone number, URL, etc.)" }, "environment": { "type": "string", "description": "Agent endpoint environment" }, "direction": { "type": "string", "enum": [ "INCOMING", "OUTGOING", "INCOMING_AND_OUTGOING" ], "description": "Agent endpoint direction (INCOMING, OUTGOING, INCOMING_AND_OUTGOING)" }, "outboundDialType": { "type": "string", "enum": [ "NONE", "HTTP_REQUEST" ], "description": "Outbound dial type (NONE or HTTP_REQUEST)" }, "outboundDialHttpRequestDefinitionId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the linked HTTP request definition for outbound dialing" }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "description": "Last update timestamp" } }, "required": [ "id", "agentId", "type", "value", "environment", "direction", "outboundDialType", "outboundDialHttpRequestDefinitionId", "createdAt", "updatedAt" ], "description": "Detailed agent endpoint response" }, "CreateAgentEndpointInput": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid", "description": "Agent ID to associate this endpoint with" }, "value": { "type": "string", "description": "Phone number in E.164 format (e.g., +12345678900)" }, "environment": { "type": "string", "default": "production", "description": "Environment name (default: production)" }, "direction": { "type": "string", "enum": [ "INCOMING", "OUTGOING", "INCOMING_AND_OUTGOING" ], "description": "Call direction: INCOMING, OUTGOING, or INCOMING_AND_OUTGOING" }, "outboundDialType": { "type": "string", "enum": [ "NONE", "HTTP_REQUEST" ], "default": "NONE", "description": "Outbound dial type: NONE or HTTP_REQUEST (default: NONE)" }, "outboundDialHttpRequestDefinitionId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the HTTP request definition for outbound dialing (required when outboundDialType is HTTP_REQUEST)" } }, "required": [ "agentId", "value", "direction" ], "description": "Input for creating an agent endpoint" }, "UpdateAgentEndpointInput": { "type": "object", "properties": { "environment": { "type": "string", "description": "Environment name" }, "outboundDialType": { "type": "string", "enum": [ "NONE", "HTTP_REQUEST" ], "description": "Outbound dial type: NONE or HTTP_REQUEST" }, "outboundDialHttpRequestDefinitionId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the HTTP request definition for outbound dialing" } }, "description": "Input for updating an agent endpoint" }, "GetAgentPromptsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentPromptResponse" } } }, "required": [ "data" ] }, "AgentPromptResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Prompt lineage ID (its own version history)." }, "source": { "type": "string", "enum": [ "USER", "RETELL_INTEGRATION", "VAPI_INTEGRATION", "ELEVEN_LABS_INTEGRATION", "BLAND_INTEGRATION", "PIPECAT_CLOUD_INTEGRATION", "PIPECAT_SELF_HOSTED_INTEGRATION", "LIVEKIT_SELF_HOSTED_INTEGRATION", "API", "CONFIG", "API_MANAGED" ], "description": "Where this prompt came from: USER (edited in the app), API (provided via the API or on calls), CONFIG (managed by config-as-code), or a provider integration." }, "prompt": { "type": "string", "description": "Current prompt content (the latest version)." }, "updatedAt": { "type": "string", "description": "When the current version was recorded (ISO 8601)." }, "createdAt": { "type": "string", "description": "When this prompt lineage was first created (ISO 8601)." } }, "required": [ "id", "source", "prompt", "updatedAt", "createdAt" ], "description": "A prompt lineage on an agent." }, "GetAgentPromptVersionsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentPromptVersionResponse" } } }, "required": [ "data" ] }, "AgentPromptVersionResponse": { "type": "object", "properties": { "versionNumber": { "type": "integer", "description": "Version number: 1-based and increasing." }, "prompt": { "type": "string", "description": "Prompt content at this version." }, "createdAt": { "type": "string", "description": "When this version was recorded (ISO 8601)." } }, "required": [ "versionNumber", "prompt", "createdAt" ] }, "SetAgentPromptResponse": { "type": "object", "properties": { "promptId": { "type": "string", "format": "uuid", "description": "The ID of the API-managed prompt lineage." }, "versionNumber": { "type": "integer", "description": "The current version number after the set." }, "changed": { "type": "boolean", "description": "True if a new version was appended; false if the content matched the current version (no-op)." } }, "required": [ "promptId", "versionNumber", "changed" ] }, "SetAgentPromptInput": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The prompt content to set." } }, "required": [ "prompt" ] }, "ListAgentVersionsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentVersionResponse" } }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of items" }, "hasMore": { "type": "boolean", "description": "Whether there are more items to fetch" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page of items" } }, "required": [ "total", "hasMore", "nextCursor" ] } }, "required": [ "data", "pagination" ] }, "AgentVersionResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "DRAFT", "PUBLISHED", "DISCARDED" ], "description": "DRAFT while being edited, PUBLISHED once it has been live." }, "versionNumber": { "type": [ "integer", "null" ], "description": "v1, v2, ... assigned on publish; null on a draft." }, "revision": { "type": "integer", "description": "Increases with every edit to a draft. Send it back as expectedRevision when you publish." }, "baseVersionId": { "type": [ "string", "null" ], "format": "uuid", "description": "The published version a draft started from." }, "rolledBackFromVersionId": { "type": [ "string", "null" ], "format": "uuid", "description": "Set when this version rolls the agent back to an older one." }, "summary": { "type": [ "string", "null" ], "description": "What changed, written on publish." }, "createdByType": { "type": "string", "enum": [ "USER", "API", "CONFIG", "AUTOIMPROVE", "INTEGRATION", "SYSTEM" ] }, "createdById": { "type": [ "string", "null" ], "format": "uuid" }, "publishedAt": { "type": [ "string", "null" ], "description": "ISO 8601." }, "publishedByType": { "type": [ "string", "null" ], "enum": [ "USER", "API", "CONFIG", "AUTOIMPROVE", "INTEGRATION", "SYSTEM" ] }, "publishedById": { "type": [ "string", "null" ], "format": "uuid" }, "createdAt": { "type": "string", "description": "ISO 8601." }, "updatedAt": { "type": "string", "description": "ISO 8601." }, "modalities": { "type": "array", "items": { "type": "string", "enum": [ "call", "chat" ] }, "description": "Whether the agent takes calls, chats, or both." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1, e.g. en." }, "firstMessageMode": { "type": [ "string", "null" ], "enum": [ "SPEAK_TEXT", "PLAY_AUDIO", "WAIT_FOR_CALLER" ] }, "firstMessage": { "type": [ "string", "null" ], "description": "What the agent says first, with firstMessageMode SPEAK_TEXT." }, "firstMessageAudioUrl": { "type": [ "string", "null" ], "description": "The audio a call opens with, with firstMessageMode PLAY_AUDIO." }, "interruptionMode": { "type": [ "string", "null" ], "enum": [ "ALLOW", "BLOCK" ] }, "vadStartSecs": { "type": [ "number", "null" ] }, "vadStopSecs": { "type": [ "number", "null" ] }, "callMaxDurationSeconds": { "type": [ "integer", "null" ] }, "callSilenceTimeoutSeconds": { "type": [ "integer", "null" ] }, "idleTimeoutSeconds": { "type": [ "integer", "null" ] }, "idleMaxCount": { "type": [ "integer", "null" ] }, "idleMessages": { "type": "array", "items": { "type": "string" } }, "endDetectionPhrases": { "type": "array", "items": { "type": "string" }, "description": "Phrases that end the call when the caller says them, matched anywhere in what they say." }, "endDetectionReasons": { "type": "array", "items": { "type": "string" }, "description": "When the agent may decide to end the call itself." }, "endCallGoodbyeMessage": { "type": [ "string", "null" ] }, "backgroundNoise": { "type": [ "string", "null" ], "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "description": "A background preset." }, "backgroundNoiseUrl": { "type": [ "string", "null" ], "description": "A custom background recording, instead of a preset." }, "backgroundNoiseVolume": { "type": [ "number", "null" ], "description": "0 to 1." }, "chatMaxDurationSeconds": { "type": [ "integer", "null" ] }, "chatInactivityTimeoutSeconds": { "type": [ "integer", "null" ] }, "subAgents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentVersionSubAgent" }, "description": "The main agent (key `main`) first, then the sub-agents it can hand the call to." }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/AgentVersionIssue" }, "description": "Why this version cannot run; empty when it can be published. Returned when reading one version." } }, "required": [ "id", "agentId", "status", "versionNumber", "revision", "baseVersionId", "rolledBackFromVersionId", "summary", "createdByType", "createdById", "publishedAt", "publishedByType", "publishedById", "createdAt", "updatedAt", "modalities", "language", "firstMessageMode", "firstMessage", "firstMessageAudioUrl", "interruptionMode", "vadStartSecs", "vadStopSecs", "callMaxDurationSeconds", "callSilenceTimeoutSeconds", "idleTimeoutSeconds", "idleMaxCount", "idleMessages", "endDetectionPhrases", "endDetectionReasons", "endCallGoodbyeMessage", "backgroundNoise", "backgroundNoiseUrl", "backgroundNoiseVolume", "chatMaxDurationSeconds", "chatInactivityTimeoutSeconds", "subAgents" ], "description": "One version of a Roark-hosted agent's configuration. Null settings use the runtime default." }, "AgentVersionSubAgent": { "type": "object", "properties": { "key": { "type": "string", "description": "`main` for the main agent; otherwise letters, digits, `_` or `-`." }, "name": { "type": [ "string", "null" ], "description": "How the agent refers to this speaker." }, "systemPrompt": { "type": [ "string", "null" ], "description": "The speaker's prompt." }, "isInitial": { "type": "boolean", "description": "The call opens as this sub-agent instead of the main agent." }, "modelConfigs": { "type": "array", "items": { "$ref": "#/components/schemas/AgentModelConfig" }, "description": "Up to three, in the order a call tries them. Empty on a sub-agent: it runs on the main agent's. The main agent needs one." }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/AgentVersionTool" } }, "handoffs": { "type": "array", "items": { "$ref": "#/components/schemas/AgentVersionHandoff" } } }, "required": [ "key", "name", "systemPrompt", "isInitial", "modelConfigs", "tools", "handoffs" ], "description": "A speaker in the conversation. A sub-agent without model configs runs on the main agent's." }, "AgentModelConfig": { "oneOf": [ { "$ref": "#/components/schemas/AgentCascadeModelConfig" }, { "$ref": "#/components/schemas/AgentSpeechToSpeechModelConfig" } ], "discriminator": { "propertyName": "type", "mapping": { "CASCADE": "#/components/schemas/AgentCascadeModelConfig", "SPEECH_TO_SPEECH": "#/components/schemas/AgentSpeechToSpeechModelConfig" } }, "description": "A model setup a speaker runs on. The call moves to the next config once this one has nothing left to try. A field of the other type is refused." }, "AgentCascadeModelConfig": { "type": "object", "properties": { "type": { "type": "string", "const": "CASCADE" }, "stt": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSttConfig" }, "description": "One to three transcribers, in the order a call tries them." }, "llm": { "type": "array", "items": { "$ref": "#/components/schemas/AgentLlmConfig" }, "description": "One to three text models, in the order a call tries them." }, "tts": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTtsConfig" }, "description": "One to three voices, in the order a call tries them." } }, "required": [ "type", "stt", "llm", "tts" ], "description": "A transcriber, a text model and a voice. A component that fails during a call moves to its next entry; the others stay." }, "AgentSttConfig": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "DEEPGRAM", "OPENAI_WHISPER", "SPEECHMATICS", "ASSEMBLYAI", "ELEVENLABS" ] }, "model": { "type": "string", "description": "Any transcriber model id the provider accepts." }, "keyterms": { "type": "array", "items": { "type": "string" }, "description": "Words and phrases the transcriber should listen for." }, "smartFormat": { "type": [ "boolean", "null" ] }, "endpointingMs": { "type": [ "integer", "null" ], "description": "How long the transcriber waits before it ends a turn." }, "turnDetection": { "type": [ "string", "null" ], "enum": [ "pipeline", "provider" ] } }, "required": [ "provider", "model", "keyterms", "smartFormat", "endpointingMs", "turnDetection" ], "description": "A transcriber. Null settings use the default." }, "AgentLlmConfig": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "OPENAI", "ANTHROPIC", "GOOGLE", "XAI", "ULTRAVOX", "AWS", "ELEVENLABS" ] }, "model": { "type": "string", "description": "Any text model id the provider accepts." }, "temperature": { "type": [ "number", "null" ], "description": "0 to 2." }, "maxTokens": { "type": [ "integer", "null" ] } }, "required": [ "provider", "model", "temperature", "maxTokens" ], "description": "A text model. Null settings use the default." }, "AgentTtsConfig": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "CARTESIA", "ELEVENLABS", "OPENAI", "RIME" ] }, "model": { "type": "string", "description": "Any voice model id the provider accepts." }, "voiceId": { "type": "string", "description": "Any voice id the provider accepts, including your own voices." }, "speed": { "type": [ "number", "null" ], "description": "0.5 to 2." }, "stability": { "type": [ "number", "null" ], "description": "0 to 1, ElevenLabs." }, "similarityBoost": { "type": [ "number", "null" ], "description": "0 to 1, ElevenLabs." } }, "required": [ "provider", "model", "voiceId", "speed", "stability", "similarityBoost" ], "description": "A voice. Null settings use the default." }, "AgentSpeechToSpeechModelConfig": { "type": "object", "properties": { "type": { "type": "string", "const": "SPEECH_TO_SPEECH" }, "speechToSpeech": { "$ref": "#/components/schemas/AgentSpeechToSpeechConfig" } }, "required": [ "type", "speechToSpeech" ], "description": "One model that hears the caller and speaks with its own voice." }, "AgentSpeechToSpeechConfig": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "OPENAI", "ANTHROPIC", "GOOGLE", "XAI", "ULTRAVOX", "AWS", "ELEVENLABS" ] }, "model": { "type": "string", "description": "Any speech-to-speech model id the provider accepts." }, "voice": { "type": [ "string", "null" ], "description": "The model's own voice." }, "temperature": { "type": [ "number", "null" ], "description": "0 to 2." }, "maxOutputTokens": { "type": [ "integer", "null" ] }, "backendModel": { "type": [ "string", "null" ], "description": "OpenAI Live models only: the text model they delegate to." } }, "required": [ "provider", "model", "voice", "temperature", "maxOutputTokens", "backendModel" ], "description": "A model that hears the caller and speaks with its own voice. Null settings use the default." }, "AgentVersionTool": { "type": "object", "properties": { "toolDefinitionId": { "type": "string", "format": "uuid" }, "pinnedVersion": { "type": [ "integer", "null" ], "description": "The tool version the agent runs; null runs the tool's latest declared version." } }, "required": [ "toolDefinitionId", "pinnedVersion" ] }, "AgentVersionHandoff": { "type": "object", "properties": { "to": { "type": "string", "description": "The key of the sub-agent that takes over; `main` for the main agent." }, "description": { "type": "string", "description": "When to hand off, in the words the model is given." }, "once": { "type": "boolean", "description": "At most once per call." }, "history": { "type": "string", "enum": [ "SHARED", "NONE" ], "description": "SHARED: the new speaker hears the conversation so far. NONE: it starts fresh." }, "note": { "type": [ "string", "null" ], "description": "Added to the new speaker's prompt at the handoff, such as a warm-transfer brief." } }, "required": [ "to", "description", "once", "history", "note" ] }, "AgentVersionIssue": { "type": "object", "properties": { "field": { "type": "string", "description": "The setting the issue is about." }, "message": { "type": "string" } }, "required": [ "field", "message" ], "description": "Something that stops a version from running." }, "RollbackAgentVersionInput": { "type": "object", "properties": { "summary": { "type": "string", "minLength": 1, "maxLength": 500 }, "expectedLiveVersionId": { "type": "string", "format": "uuid", "description": "The live version when you decided to roll back. When sent, the rollback is refused with 409 if another version went live since." } } }, "CreateAgentDraftInput": { "type": "object", "properties": { "fromVersionId": { "type": "string", "format": "uuid", "description": "Start from this published version instead of the live one." } } }, "UpdateAgentDraftInput": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "description": "The draft's revision when you read it. When sent, the edit is refused if the draft changed since; when omitted, it applies on top of the latest edit." }, "settings": { "type": "object", "properties": { "modalities": { "type": "array", "items": { "type": "string", "enum": [ "call", "chat" ] }, "maxItems": 2 }, "language": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 10 }, "firstMessageMode": { "type": [ "string", "null" ], "enum": [ "SPEAK_TEXT", "PLAY_AUDIO", "WAIT_FOR_CALLER" ] }, "firstMessage": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 }, "firstMessageAudioUrl": { "type": [ "string", "null" ], "format": "uri" }, "interruptionMode": { "type": [ "string", "null" ], "enum": [ "ALLOW", "BLOCK" ] }, "vadStartSecs": { "type": [ "number", "null" ], "minimum": 0, "maximum": 5 }, "vadStopSecs": { "type": [ "number", "null" ], "minimum": 0, "maximum": 5 }, "callMaxDurationSeconds": { "type": [ "integer", "null" ], "minimum": 30, "maximum": 3600 }, "callSilenceTimeoutSeconds": { "type": [ "integer", "null" ], "minimum": 5, "maximum": 120 }, "idleTimeoutSeconds": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 60 }, "idleMaxCount": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 }, "idleMessages": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxItems": 10 }, "endDetectionPhrases": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 20 }, "endDetectionReasons": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxItems": 20 }, "endCallGoodbyeMessage": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 500 }, "backgroundNoise": { "type": [ "string", "null" ], "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ] }, "backgroundNoiseUrl": { "type": [ "string", "null" ], "format": "uri" }, "backgroundNoiseVolume": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "chatMaxDurationSeconds": { "type": [ "integer", "null" ], "minimum": 30, "maximum": 86400 }, "chatInactivityTimeoutSeconds": { "type": [ "integer", "null" ], "minimum": 60, "maximum": 86400 }, "subAgents": { "type": "array", "items": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string", "const": "main" }, { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$", "minLength": 1, "maxLength": 53 } ] }, "name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100 }, "systemPrompt": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100000 }, "isInitial": { "type": "boolean" }, "modelConfigs": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "CASCADE" }, "stt": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "DEEPGRAM", "OPENAI_WHISPER", "SPEECHMATICS", "ASSEMBLYAI", "ELEVENLABS" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "keyterms": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 50, "default": [] }, "smartFormat": { "type": [ "boolean", "null" ], "default": null }, "endpointingMs": { "type": [ "integer", "null" ], "minimum": 10, "maximum": 5000, "default": null }, "turnDetection": { "type": [ "string", "null" ], "enum": [ "pipeline", "provider" ], "default": null } }, "required": [ "provider", "model" ], "additionalProperties": false }, "minItems": 1, "maxItems": 3 }, "llm": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "OPENAI", "ANTHROPIC", "GOOGLE", "XAI", "ULTRAVOX", "AWS", "ELEVENLABS" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "temperature": { "type": [ "number", "null" ], "minimum": 0, "maximum": 2, "default": null }, "maxTokens": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 128000, "default": null } }, "required": [ "provider", "model" ], "additionalProperties": false }, "minItems": 1, "maxItems": 3 }, "tts": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "CARTESIA", "ELEVENLABS", "OPENAI", "RIME" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "voiceId": { "type": "string", "minLength": 1, "maxLength": 200 }, "speed": { "type": [ "number", "null" ], "minimum": 0.5, "maximum": 2, "default": null }, "stability": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "default": null }, "similarityBoost": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "default": null } }, "required": [ "provider", "model", "voiceId" ], "additionalProperties": false }, "minItems": 1, "maxItems": 3 } }, "required": [ "type", "stt", "llm", "tts" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "SPEECH_TO_SPEECH" }, "speechToSpeech": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "OPENAI", "ANTHROPIC", "GOOGLE", "XAI", "ULTRAVOX", "AWS", "ELEVENLABS" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "voice": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "default": null }, "temperature": { "type": [ "number", "null" ], "minimum": 0, "maximum": 2, "default": null }, "maxOutputTokens": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 128000, "default": null }, "backendModel": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "default": null } }, "required": [ "provider", "model" ], "additionalProperties": false } }, "required": [ "type", "speechToSpeech" ], "additionalProperties": false } ] }, "maxItems": 3 }, "tools": { "type": "array", "items": { "type": "object", "properties": { "toolDefinitionId": { "type": "string", "format": "uuid" }, "pinnedVersion": { "type": [ "integer", "null" ], "minimum": 1 } }, "required": [ "toolDefinitionId", "pinnedVersion" ] }, "maxItems": 32 }, "handoffs": { "type": "array", "items": { "type": "object", "properties": { "to": { "anyOf": [ { "type": "string", "const": "main" }, { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$", "minLength": 1, "maxLength": 53 } ] }, "description": { "type": "string", "minLength": 1, "maxLength": 1024 }, "once": { "type": "boolean" }, "history": { "type": "string", "enum": [ "SHARED", "NONE" ] }, "note": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2000 } }, "required": [ "to", "description", "once", "history", "note" ] }, "maxItems": 16 } }, "required": [ "key", "name", "systemPrompt", "isInitial", "modelConfigs", "tools", "handoffs" ] }, "minItems": 1, "maxItems": 17 } }, "description": "The settings to change. Omitted settings stay as they are; null clears one to the runtime default. subAgents replaces every speaker, model configs included, and must include `main`; in a model config, omitted fields use the runtime default." } }, "required": [ "settings" ] }, "PublishAgentDraftInput": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "description": "The draft revision you reviewed." }, "summary": { "type": "string", "minLength": 1, "maxLength": 500, "description": "What changed." } }, "required": [ "expectedRevision" ] }, "PhoneNumberResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Phone number ID" }, "e164": { "type": "string", "description": "The number in E.164 format", "example": "+14155550123" }, "name": { "type": [ "string", "null" ], "description": "Label the project gave the number" }, "localityCode": { "type": [ "string", "null" ], "description": "ISO 3166-2 code of the region the number is from, when the carrier gave one" }, "purchasedAt": { "type": "string", "description": "When the number was bought (ISO 8601)" }, "rentNextChargeAt": { "type": "string", "description": "When the next month of rent is due (ISO 8601)" }, "isFree": { "type": "boolean", "description": "Whether the number sits inside the plan free allowance right now" }, "monthlyRentMicros": { "type": "integer", "description": "What a month of this number costs in micro-dollars; 0 while it is free" }, "agentId": { "type": [ "string", "null" ], "format": "uuid", "description": "The agent the number is assigned to, if any" } }, "required": [ "id", "e164", "name", "localityCode", "purchasedAt", "rentNextChargeAt", "isFree", "monthlyRentMicros", "agentId" ], "description": "A phone number the project owns" }, "AvailablePhoneNumberResponse": { "type": "object", "properties": { "e164": { "type": "string", "description": "The number in E.164 format", "example": "+14155550123" }, "region": { "type": [ "string", "null" ], "description": "Region the carrier lists, e.g. a state code" }, "locality": { "type": [ "string", "null" ], "description": "Locality the carrier lists, e.g. a city" }, "bestEffort": { "type": "boolean", "description": "True when the area code asked for had no numbers and the carrier offered this nearby one instead" } }, "required": [ "e164", "region", "locality", "bestEffort" ], "description": "A number the carrier has for sale" }, "PhoneNumberAllowanceResponse": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "PAYG", "TEAM", "ENTERPRISE" ], "description": "The billing plan the allowance comes from" }, "freeLimit": { "type": "integer", "description": "Numbers included at no charge" }, "used": { "type": "integer", "description": "Numbers the organization holds right now" }, "paidCount": { "type": "integer", "description": "How many of those sit outside the free allowance" }, "monthlyRentMicros": { "type": "integer", "description": "What one paid number costs a month, in micro-dollars" }, "nextIsFree": { "type": "boolean", "description": "Whether the next number would be free" }, "canPurchase": { "type": "boolean", "description": "Whether a purchase would be admitted right now" }, "blockedReason": { "type": [ "string", "null" ], "enum": [ "PAYMENT_METHOD_REQUIRED", "INSUFFICIENT_CREDITS", "SPEND_CAP_REACHED", "PLAN_LIMIT_REACHED" ], "description": "Why a purchase would be refused; null when canPurchase is true" }, "isOverridden": { "type": "boolean", "description": "True when the free allowance comes from a per-organization override" } }, "required": [ "plan", "freeLimit", "used", "paidCount", "monthlyRentMicros", "nextIsFree", "canPurchase", "blockedReason", "isOverridden" ], "description": "How many numbers the organization gets for free and whether it may buy the next one" }, "CreatePhoneNumberInput": { "type": "object", "properties": { "e164": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$", "description": "The number to buy, in E.164 format, from a search result. Give this or autoPick.", "example": "+14155550123" }, "autoPick": { "$ref": "#/components/schemas/PhoneNumberAutoPickInput", "description": "Let Roark pick a matching number instead of naming one. Give this or e164." }, "country": { "type": "string", "enum": [ "US", "CA" ], "description": "The country of the number given by e164 (default: US). An auto-picked number uses autoPick.country.", "example": "US" }, "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "A label for the number" }, "agentId": { "type": "string", "format": "uuid", "description": "The agent to assign the number to" }, "expectFree": { "type": "boolean", "description": "Whether you expect this number to be free (from the allowance). The purchase is refused with 409 if that has changed since you checked." }, "expectMonthlyRentMicros": { "type": "integer", "minimum": 0, "description": "The monthly rent you expect for a paid number, in micros (from the allowance). The purchase is refused with 409 if that has changed since you checked.", "example": 2000000 } }, "description": "Input for buying a phone number" }, "PhoneNumberAutoPickInput": { "type": "object", "properties": { "country": { "type": "string", "enum": [ "US", "CA" ], "description": "ISO 3166-1 alpha-2 country of the number: US or CA", "example": "US", "default": "US" }, "numberType": { "type": "string", "enum": [ "LOCAL", "TOLL_FREE" ], "description": "LOCAL for a number in an area code, TOLL_FREE for one from the shared US and Canada toll-free pool", "example": "LOCAL", "default": "LOCAL" }, "areaCode": { "type": "string", "pattern": "^\\d{3}$", "description": "Three-digit area code, or a toll-free prefix such as 800. When it has no numbers, nearby ones are returned instead, flagged bestEffort.", "example": "415" }, "contains": { "type": "string", "pattern": "^[0-9A-Za-z*]{1,7}$", "description": "Digits or letters the number must contain (1 to 7, * matches any digit)", "example": "555" } }, "description": "What the number Roark picks should look like. Roark buys the first matching number the carrier will sell, preferring the area code and falling back to a nearby one." }, "UpdatePhoneNumberInput": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 80, "description": "New label; null clears it, omit to leave it alone" }, "agentId": { "type": [ "string", "null" ], "format": "uuid", "description": "Agent to assign the number to; null unassigns, omit to leave it alone" } }, "description": "Input for relabelling or reassigning a phone number" }, "ReleasePhoneNumberResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Phone number ID" }, "released": { "type": "boolean", "const": true, "description": "Always true; the number is gone and rent has stopped" } }, "required": [ "id", "released" ], "description": "Confirmation that a phone number was released" }, "CallCreate": { "type": "object", "properties": { "recordingUrl": { "type": "string", "format": "uri", "description": "URL of source recording (must be an accessible WAV, MP3, MP4, or OGG file). Can be a signed URL." }, "stereoRecordingUrl": { "type": "string", "format": "uri", "description": "URL of source stereo recording. Must be accessible. Can be a signed URL. Supported formats: WAV, MP3, MP4, OGG." }, "startedAt": { "type": "string", "description": "When the call started (ISO 8601 format)" }, "interfaceType": { "type": "string", "enum": [ "PHONE", "WEB" ], "description": "Interface type of the call (PHONE or WEB)" }, "callDirection": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direction of the call (INBOUND or OUTBOUND)" }, "endedStatus": { "type": "string", "enum": [ "PARTICIPANTS_DID_NOT_SPEAK", "AGENT_DID_NOT_ANSWER", "AGENT_DID_NOT_SPEAK", "AGENT_STOPPED_SPEAKING", "AGENT_ENDED_CALL", "AGENT_SAID_END_CALL_PHRASE", "AGENT_TRANSFERRED_CALL", "AGENT_BUSY", "AGENT_ERROR", "CUSTOMER_ENDED_CALL", "VOICE_MAIL_REACHED", "SILENCE_TIME_OUT", "PHONE_CALL_PROVIDER_CONNECTION_ERROR", "CUSTOMER_DID_NOT_ANSWER", "CUSTOMER_DID_NOT_SPEAK", "CUSTOMER_STOPPED_SPEAKING", "CUSTOMER_BUSY", "DIAL_ERROR", "MAX_DURATION_REACHED", "UNKNOWN" ], "description": "High-level call end status, indicating how the call terminated" }, "transcript": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/TranscriptEntryAgent" }, { "$ref": "#/components/schemas/TranscriptEntryCustomer" } ] }, "description": "List of transcript entries made during the call" }, "toolInvocations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the tool that was invoked" }, "description": { "type": "string", "description": "Description of when the tool should be invoked" }, "parameters": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "description": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean" ] }, "value": {} } }, {} ] }, "description": "Parameters provided to the tool during invocation" }, "result": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": {} } ], "description": "Result returned by the tool after execution. Can be a string or a JSON object" }, "startOffsetMs": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Offset in milliseconds from the start of the call when the tool was invoked" }, "endOffsetMs": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Offset in milliseconds from the start of the call when the tool execution completed. Used to calculate duration of the tool execution" }, "agent": { "type": "object", "properties": { "roarkId": { "type": "string", "format": "uuid", "description": "The Roark ID of the agent" }, "customId": { "type": "string", "description": "The custom ID set on the agent" } }, "description": "Metadata about the agent that invoked this tool - used to match which agent from the agents array this tool invocation belongs to" } }, "required": [ "name", "parameters", "result", "startOffsetMs" ] }, "description": "List of tool invocations made during the call" }, "properties": { "type": "object", "additionalProperties": {}, "description": "Custom properties to include with the call. These can be used for filtering and will show in the call details page" }, "vapiCallId": { "type": "string", "format": "uuid", "description": "The Vapi call ID (UUID) to link this call with OpenTelemetry trace data from Vapi. Used for matching calls with OTEL traces." }, "livekitRoomId": { "type": "string", "maxLength": 255, "description": "The LiveKit Cloud room ID to link this call with OpenTelemetry trace data from LiveKit. Used for matching calls with OTEL traces." }, "externalId": { "type": "string", "maxLength": 255, "description": "A stable identifier from your own system (e.g. session ID, conversation ID) used to correlate this call with OpenTelemetry traces. Set the same value as a `roark.external_id` span or resource attribute on your traces and the matching trace will be linked automatically. Must be unique within a project." }, "agent": { "allOf": [ { "anyOf": [ { "$ref": "#/components/schemas/AgentIdentificationByRoarkId" }, { "$ref": "#/components/schemas/AgentIdentificationByName" }, { "$ref": "#/components/schemas/AgentIdentificationByCustomId" } ] }, { "type": "object", "properties": { "endpoint": { "anyOf": [ { "$ref": "#/components/schemas/AgentEndpointById" }, { "$ref": "#/components/schemas/AgentEndpointByValue" } ], "description": "Endpoint configuration for this agent (optional)" }, "prompt": { "type": "object", "properties": { "resolvedPrompt": { "type": "string", "description": "The agent's system prompt used during this call" } }, "required": [ "resolvedPrompt" ], "description": "Agent's prompt configuration (optional)" } } } ], "description": "Single agent participating in the call. Use this for simpler API when you have only one agent." }, "agents": { "type": "array", "items": { "allOf": [ { "anyOf": [ { "$ref": "#/components/schemas/AgentIdentificationByRoarkId" }, { "$ref": "#/components/schemas/AgentIdentificationByName" }, { "$ref": "#/components/schemas/AgentIdentificationByCustomId" } ] }, { "type": "object", "properties": { "endpoint": { "anyOf": [ { "$ref": "#/components/schemas/AgentEndpointById" }, { "$ref": "#/components/schemas/AgentEndpointByValue" } ], "description": "Endpoint configuration for this agent (optional)" }, "prompt": { "type": "object", "properties": { "resolvedPrompt": { "type": "string", "description": "The agent's system prompt used during this call" } }, "required": [ "resolvedPrompt" ], "description": "Agent's prompt configuration (optional)" } } } ], "description": "Agent participating in the call with their endpoint and prompt" }, "description": "Agents participating in the call. Each agent requires identification and prompt information." }, "customer": { "type": "object", "properties": { "label": { "type": [ "string", "null" ], "description": "Label to identify this customer in the transcript (e.g., \"speaker-01\", \"speaker-02\")" }, "phoneNumberE164": { "type": [ "string", "null" ], "description": "Customer phone number in E.164 format (e.g., +14155551234)" } }, "required": [ "phoneNumberE164" ], "description": "Single customer participating in the call. Use this for simpler API when you have only one customer." }, "customers": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": [ "string", "null" ], "description": "Label to identify this customer in the transcript (e.g., \"speaker-01\", \"speaker-02\")" }, "phoneNumberE164": { "type": [ "string", "null" ], "description": "Customer phone number in E.164 format (e.g., +14155551234)" } }, "required": [ "phoneNumberE164" ], "description": "Customer participating in the call" }, "description": "Customers participating in the call." } }, "required": [ "recordingUrl", "startedAt", "interfaceType", "callDirection" ], "description": "Call creation payload. Supports singular (agent/customer) or plural (agents/customers) formats." }, "TranscriptEntryAgent": { "type": "object", "properties": { "startOffsetMs": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "endOffsetMs": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "text": { "type": "string" }, "languageCode": { "type": "string" }, "payload": { "type": [ "object", "null" ], "additionalProperties": {} }, "role": { "type": "string", "const": "AGENT" }, "agent": { "type": "object", "properties": { "roarkId": { "type": "string", "format": "uuid", "description": "The Roark ID of the agent" }, "customId": { "type": "string", "description": "The custom ID set on the agent" } }, "description": "Metadata about the agent that spoke this turn - used to match which agent from the `agents` array this transcript entry belongs to" } }, "required": [ "startOffsetMs", "endOffsetMs", "text", "role" ] }, "TranscriptEntryCustomer": { "type": "object", "properties": { "startOffsetMs": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "endOffsetMs": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "text": { "type": "string" }, "languageCode": { "type": "string" }, "payload": { "type": [ "object", "null" ], "additionalProperties": {} }, "role": { "type": "string", "const": "CUSTOMER" }, "customer": { "type": "object", "properties": { "phoneNumberE164": { "type": "string", "description": "The phone number of the customer in E.164 format, matching the `phoneNumberE164` field on the `customers` array when creating the call" }, "label": { "type": "string", "description": "Label matching the `label` field on the `customers` array when creating the call" } }, "description": "Metadata about the customer that spoke this turn - used to match which customer from the `customers` array this transcript entry belongs to" } }, "required": [ "startOffsetMs", "endOffsetMs", "text", "role" ] }, "AgentIdentificationByRoarkId": { "type": "object", "properties": { "roarkId": { "type": "string", "format": "uuid", "description": "Existing Roark agent ID" } }, "required": [ "roarkId" ] }, "AgentIdentificationByName": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent name" }, "description": { "type": "string", "description": "Agent description" }, "customId": { "type": "string", "description": "Agent custom ID" } }, "required": [ "name" ], "description": "Find existing by customId if provided, otherwise reuse exact project name match before creating" }, "AgentIdentificationByCustomId": { "type": "object", "properties": { "customId": { "type": "string", "description": "Existing custom ID for a Roark agent" } }, "required": [ "customId" ] }, "AgentEndpointById": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Existing Roark endpoint ID" } }, "required": [ "id" ] }, "AgentEndpointByValue": { "type": "object", "properties": { "value": { "type": "string", "description": "Endpoint value (phone number in E.164 format or websocket URL)" }, "type": { "type": "string", "description": "Type of endpoint (phone or websocket)" }, "direction": { "type": "string", "description": "Call direction for this endpoint" } }, "required": [ "value", "type" ], "description": "Lookup or create endpoint if one with these values does not exist" }, "AppendToolInvocationsResponse": { "type": "object", "properties": { "callId": { "type": "string", "format": "uuid", "description": "The call the tool invocations were attached to" }, "added": { "type": "integer", "description": "Number of tool invocations newly written" }, "skipped": { "type": "integer", "description": "Number of tool invocations skipped because an identical one (same tool and timing) already existed on the call" }, "metricCollectionJob": { "oneOf": [ { "$ref": "#/components/schemas/MetricCollectionJobResponse" }, { "type": "null" } ], "description": "The metric collection job triggered to (re)score the requested metrics, or null when no metrics were requested (or when scoring failed, see metricCollectionError). Track its id to fetch results from GET /v1/metric/collection-jobs/:jobId." }, "metricCollectionError": { "type": [ "string", "null" ], "description": "Present (non-null) only when `metrics` were requested but the collection job could not be started (e.g. insufficient credits, or an unknown metric id). The tool invocations were still attached — retry scoring via POST /v1/metric/collection-jobs, or re-send this request (attaching is idempotent). Null on success or when no metrics were requested." } }, "required": [ "callId", "added", "skipped", "metricCollectionJob", "metricCollectionError" ], "description": "Result of appending tool invocations to a call." }, "MetricCollectionJobResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the metric collection job" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELED" ], "description": "Current status of the job" }, "triggeredBy": { "type": "string", "enum": [ "USER_MANUAL", "USER_API", "METRIC_POLICY", "SIMULATION" ], "description": "What triggered this job" }, "totalItems": { "type": "integer", "description": "Total number of call-metric pairs to process" }, "completedItems": { "type": "integer", "description": "Number of items that finished without failing: a value was written, or the metric did not apply to the conversation" }, "failedItems": { "type": "integer", "description": "Number of items that could not be computed, for example because an artifact the metric reads (such as diarization) failed to generate" }, "startedAt": { "type": [ "string", "null" ], "description": "When the job started processing" }, "completedAt": { "type": [ "string", "null" ], "description": "When the job completed" }, "errorMessage": { "type": [ "string", "null" ], "description": "Why the job failed or, on a COMPLETED job with failedItems above 0, why those items failed" }, "policyIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs of the metric policies that triggered this job" }, "createdAt": { "type": "string", "description": "When the job was created" }, "updatedAt": { "type": "string", "description": "When the job was last updated" } }, "required": [ "id", "status", "triggeredBy", "totalItems", "completedItems", "failedItems", "startedAt", "completedAt", "errorMessage", "policyIds", "createdAt", "updatedAt" ], "description": "A metric collection job that processes metrics for calls or chats" }, "AppendToolInvocationsRequest": { "type": "object", "properties": { "toolInvocations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the tool that was invoked" }, "description": { "type": "string", "description": "Description of when the tool should be invoked" }, "parameters": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "description": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean" ] }, "value": {} } }, {} ] }, "description": "Parameters provided to the tool during invocation" }, "result": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": {} } ], "description": "Result returned by the tool after execution. Can be a string or a JSON object" }, "startOffsetMs": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Offset in milliseconds from the start of the call when the tool was invoked" }, "endOffsetMs": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Offset in milliseconds from the start of the call when the tool execution completed. Used to calculate duration of the tool execution" }, "agent": { "type": "object", "properties": { "roarkId": { "type": "string", "format": "uuid", "description": "The Roark ID of the agent" }, "customId": { "type": "string", "description": "The custom ID set on the agent" } }, "description": "Metadata about the agent that invoked this tool - used to match which agent from the agents array this tool invocation belongs to" } }, "required": [ "name", "parameters", "result", "startOffsetMs" ] }, "minItems": 1, "maxItems": 500, "description": "Tool invocations that fired during the call, to attach to it. Max 500 per request. Re-sending an invocation already present on the call (same tool name and timing) is skipped, so retries are safe." }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "minItems": 1, "maxItems": 20, "description": "Optional. Metric definitions to (re)score on this call after the tool invocations are attached, e.g. the Tool Invocation Analysis metrics. Triggers a metric collection job (billed, credit-gated) and requires the 'metric:create' permission. Omit to attach tools without scoring. Max 20." } }, "required": [ "toolInvocations" ], "description": "Attach tool invocations to an existing call, optionally (re)scoring metrics over them." }, "UpdateCallPropertiesResponse": { "type": "object", "properties": { "callId": { "type": "string", "format": "uuid", "description": "The call whose properties were updated" }, "updated": { "type": "array", "items": { "type": "string" }, "description": "Stored (snake_case) names of the properties written by this request, including ones sent with the value they already had" }, "removed": { "type": "array", "items": { "type": "string" }, "description": "Stored names of the properties removed by this request. A property sent as null that was not on the call is not listed." }, "properties": { "type": "object", "additionalProperties": { "type": "string" }, "description": "All of the call's properties after the update, including the ones Roark sets, when the key also has the 'call:read' permission. A key without it gets back only the properties this request wrote. Values are returned as strings, as on GET /v1/call/:callId." }, "metricCollectionJob": { "oneOf": [ { "$ref": "#/components/schemas/MetricCollectionJobResponse" }, { "type": "null" } ], "description": "The metric collection job triggered to (re)score the requested metrics, or null when no metrics were requested (or when scoring failed, see metricCollectionError). Track its id to fetch results from GET /v1/metric/collection-jobs/:jobId." }, "metricCollectionError": { "type": [ "string", "null" ], "description": "Present (non-null) only when `metrics` were requested but the collection job could not be started (e.g. insufficient credits, or an unknown metric id). The properties were still written. Retry scoring via POST /v1/metric/collection-jobs, or re-send this request (writing the same values again is harmless). Null on success or when no metrics were requested." } }, "required": [ "callId", "updated", "removed", "properties", "metricCollectionJob", "metricCollectionError" ], "description": "Result of updating the properties of a call." }, "UpdateCallPropertiesRequest": { "type": "object", "properties": { "properties": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Properties to change on the call. A string, number or boolean value adds the property or overwrites it; null removes it. Properties left out are untouched. Keys are stored in snake_case, as on POST /v1/call. A property keeps the value type it was first stored with in the project, so a value of another type is rejected. Properties Roark sets itself (direction, duration_seconds, agent_id, ...) can't be changed. Max 100 per request.", "example": { "partner_outcome": "apr_returned", "delivered_apr": "21.99" } }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "minItems": 1, "maxItems": 20, "description": "Optional. Metric definitions to (re)score on this call once the properties are written, e.g. metrics that read the call's properties. Triggers a metric collection job (billed, credit-gated) and requires the 'metric:create' permission. Omit to update properties without scoring. Max 20." } }, "required": [ "properties" ], "description": "Add, overwrite or remove custom properties on an existing call, optionally (re)scoring metrics." }, "CallCost": { "type": "object", "properties": { "callId": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "const": "usd" }, "totalUsdMicros": { "type": "integer", "description": "Total billable spend for this call, in micro-dollars." }, "totalUsd": { "type": "number" }, "breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/CostBreakdownItem" }, "description": "Spend by cost type. Sums to totalUsdMicros." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CallCostLine" }, "description": "Every billable cost line attributed to the call." } }, "required": [ "callId", "currency", "totalUsdMicros", "totalUsd", "breakdown", "items" ] }, "CostBreakdownItem": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "SIM_PLATFORM_FEE", "SIM_TTS", "SIM_STT", "SIM_LLM", "SIM_TELEPHONY", "METRIC", "TRANSCRIPTION", "INTERNAL_LLM", "INTERNAL_STT", "PHONE_NUMBER" ], "description": "The cost source, e.g. SIM_PLATFORM_FEE, SIM_LLM, METRIC." }, "surface": { "type": "string", "enum": [ "SIMULATION", "POST_CALL" ], "description": "SIMULATION or POST_CALL." }, "amountUsdMicros": { "type": "integer", "description": "Billable spend for this type, in micro-dollars." }, "amountUsd": { "type": "number", "description": "The same figure in US dollars." }, "quantity": { "type": "number", "minimum": 0, "description": "Units billed (see the line items for the unit)." } }, "required": [ "source", "surface", "amountUsdMicros", "amountUsd", "quantity" ] }, "CallCostLine": { "type": "object", "properties": { "eventId": { "type": "string", "description": "Stable id of the cost event. Use it to deduplicate." }, "source": { "type": "string", "enum": [ "SIM_PLATFORM_FEE", "SIM_TTS", "SIM_STT", "SIM_LLM", "SIM_TELEPHONY", "METRIC", "TRANSCRIPTION", "INTERNAL_LLM", "INTERNAL_STT", "PHONE_NUMBER" ] }, "surface": { "type": "string", "enum": [ "SIMULATION", "POST_CALL" ] }, "amountUsdMicros": { "type": "integer" }, "amountUsd": { "type": "number" }, "quantity": { "type": "number", "minimum": 0 }, "quantityUnit": { "type": "string", "enum": [ "MINUTES", "INPUT_TOKENS", "OUTPUT_TOKENS", "CHARACTERS", "AUDIO_SECONDS", "UNITS" ] }, "provider": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "simulationJobId": { "type": [ "string", "null" ], "format": "uuid" }, "metricDefinitionId": { "type": [ "string", "null" ], "format": "uuid", "description": "The metric a METRIC line was charged for." }, "metricCollectionJobId": { "type": [ "string", "null" ], "format": "uuid", "description": "The grading pass a METRIC line paid for. A call graded twice carries one line per pass." }, "occurredAt": { "type": "string", "description": "When the cost was incurred, ISO 8601." } }, "required": [ "eventId", "source", "surface", "amountUsdMicros", "amountUsd", "quantity", "quantityUnit", "provider", "model", "simulationJobId", "metricDefinitionId", "metricCollectionJobId", "occurredAt" ] }, "ChatCreate": { "type": "object", "properties": { "startTimestamp": { "type": "string", "description": "When the chat started (ISO 8601 format)" }, "endTimestamp": { "type": "string", "description": "When the chat ended (ISO 8601 format)" }, "messages": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/ChatMessageAgent" }, { "$ref": "#/components/schemas/ChatMessageCustomer" } ] }, "description": "Ordered list of messages exchanged during the chat" }, "toolInvocations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the tool that was invoked" }, "description": { "type": "string", "description": "Description of when the tool should be invoked" }, "parameters": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "description": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean" ] }, "value": {} } }, {} ] }, "description": "Parameters provided to the tool during invocation" }, "result": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": {} } ], "description": "Result returned by the tool after execution. Can be a string or a JSON object" }, "startTimestamp": { "type": "string", "description": "When the tool was invoked (ISO 8601). Must fall within the chat time range." }, "endTimestamp": { "type": "string", "description": "When the tool execution completed (ISO 8601). Used to calculate duration of the tool execution." }, "agent": { "type": "object", "properties": { "roarkId": { "type": "string", "format": "uuid", "description": "The Roark ID of the agent" }, "customId": { "type": "string", "description": "The custom ID set on the agent" } }, "description": "Metadata about the agent that invoked this tool - used to match which agent from the agents array this tool invocation belongs to" } }, "required": [ "name", "parameters", "result", "startTimestamp" ] }, "description": "List of tool invocations made during the chat" }, "properties": { "type": "object", "additionalProperties": {}, "description": "Custom properties to include with the chat. These can be used for filtering and will show in the chat details page", "example": { "source": "web", "region": "US", "sessionId": "abc123" } }, "traceId": { "type": [ "string", "null" ], "description": "Optional OpenTelemetry trace ID for the chat. Surfaces the chat in the tracing tab.", "example": "4bf92f3577b34da6a3ce929d0e0e4736" }, "externalId": { "type": "string", "maxLength": 255, "description": "A stable identifier from your own system (e.g. session ID, conversation ID) used to correlate this chat with OpenTelemetry traces. Set the same value as a `roark.external_id` span or resource attribute on your traces and the matching trace will be linked automatically. Must be unique within a project." }, "agent": { "allOf": [ { "anyOf": [ { "$ref": "#/components/schemas/ChatAgentIdentificationByRoarkId" }, { "$ref": "#/components/schemas/ChatAgentIdentificationByName" }, { "$ref": "#/components/schemas/ChatAgentIdentificationByCustomId" } ] }, { "type": "object", "properties": { "prompt": { "type": "object", "properties": { "resolvedPrompt": { "type": "string", "description": "The agent's system prompt used during this chat" } }, "required": [ "resolvedPrompt" ], "description": "Agent's prompt configuration (optional)" } } } ], "description": "Single agent participating in the chat. Use this for the simpler API when you have only one agent." }, "agents": { "type": "array", "items": { "allOf": [ { "anyOf": [ { "$ref": "#/components/schemas/ChatAgentIdentificationByRoarkId" }, { "$ref": "#/components/schemas/ChatAgentIdentificationByName" }, { "$ref": "#/components/schemas/ChatAgentIdentificationByCustomId" } ] }, { "type": "object", "properties": { "prompt": { "type": "object", "properties": { "resolvedPrompt": { "type": "string", "description": "The agent's system prompt used during this chat" } }, "required": [ "resolvedPrompt" ], "description": "Agent's prompt configuration (optional)" } } } ], "description": "Agent participating in the chat with their identification and prompt" }, "description": "Agents participating in the chat. Each agent requires identification and prompt information." }, "customer": { "type": "object", "properties": { "label": { "type": [ "string", "null" ], "description": "Label to identify this customer in the chat (e.g., \"user-01\", \"anonymous-visitor\")" }, "phoneNumberE164": { "type": [ "string", "null" ], "description": "Customer phone number in E.164 format (e.g., +14155551234), optional for chat customers" } }, "required": [ "phoneNumberE164" ], "description": "Single customer participating in the chat. Use this for the simpler API when you have only one customer." }, "customers": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": [ "string", "null" ], "description": "Label to identify this customer in the chat (e.g., \"user-01\", \"anonymous-visitor\")" }, "phoneNumberE164": { "type": [ "string", "null" ], "description": "Customer phone number in E.164 format (e.g., +14155551234), optional for chat customers" } }, "required": [ "phoneNumberE164" ], "description": "Customer participating in the chat" }, "description": "Customers participating in the chat." } }, "required": [ "startTimestamp", "endTimestamp", "messages" ], "description": "Chat creation payload. Supports singular (agent/customer) or plural (agents/customers) formats." }, "ChatMessageAgent": { "type": "object", "properties": { "role": { "type": "string", "const": "AGENT", "description": "The agent sent this message" }, "text": { "type": "string", "minLength": 1, "description": "Message content" }, "languageCode": { "type": "string", "description": "ISO language code (e.g., \"en\")" }, "startTimestamp": { "type": "string", "description": "When the message was sent (ISO 8601). Must fall within the chat time range." }, "endTimestamp": { "type": "string", "description": "When the message finished sending (ISO 8601). For instant messages, can equal startTimestamp." }, "agent": { "type": "object", "properties": { "roarkId": { "type": "string", "format": "uuid", "description": "The Roark ID of the agent" }, "customId": { "type": "string", "description": "The custom ID set on the agent" } }, "description": "Metadata about the agent that sent this message - used to match which agent from the agents array this message belongs to" } }, "required": [ "role", "text", "startTimestamp" ] }, "ChatMessageCustomer": { "type": "object", "properties": { "role": { "type": "string", "const": "CUSTOMER", "description": "The customer sent this message" }, "text": { "type": "string", "minLength": 1, "description": "Message content" }, "languageCode": { "type": "string", "description": "ISO language code (e.g., \"en\")" }, "startTimestamp": { "type": "string", "description": "When the message was sent (ISO 8601). Must fall within the chat time range." }, "endTimestamp": { "type": "string", "description": "When the message finished sending (ISO 8601). For instant messages, can equal startTimestamp." }, "customer": { "type": "object", "properties": { "phoneNumberE164": { "type": "string", "description": "Customer phone number in E.164 format" }, "label": { "type": "string", "description": "Customer label" } }, "description": "Metadata about the customer that sent this message - used to match which customer from the customers array this message belongs to" } }, "required": [ "role", "text", "startTimestamp" ] }, "ChatAgentIdentificationByRoarkId": { "type": "object", "properties": { "roarkId": { "type": "string", "format": "uuid", "description": "Existing Roark agent ID" } }, "required": [ "roarkId" ] }, "ChatAgentIdentificationByName": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent name" }, "description": { "type": "string", "description": "Agent description" }, "customId": { "type": "string", "description": "Agent custom ID" } }, "required": [ "name" ], "description": "Find existing by customId if provided, otherwise reuse exact project name match before creating" }, "ChatAgentIdentificationByCustomId": { "type": "object", "properties": { "customId": { "type": "string", "description": "Existing custom ID for a Roark agent" } }, "required": [ "customId" ] }, "ListMetricDefinitionsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MetricDefinitionResponse" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "limit", "hasMore", "nextCursor" ] } }, "required": [ "data", "pagination" ], "description": "Cursor-paginated metric definitions available in the project" }, "MetricDefinitionResponse": { "oneOf": [ { "$ref": "#/components/schemas/LlmJudgeMetricResponse" }, { "$ref": "#/components/schemas/ProviderMetricResponse" }, { "$ref": "#/components/schemas/ThresholdMetricResponse" }, { "$ref": "#/components/schemas/FormulaMetricResponse" }, { "$ref": "#/components/schemas/PatternMetricResponse" }, { "$ref": "#/components/schemas/HttpRequestMetricResponse" } ], "discriminator": { "propertyName": "calculationType", "mapping": { "LLM_JUDGE": "#/components/schemas/LlmJudgeMetricResponse", "PROVIDER": "#/components/schemas/ProviderMetricResponse", "THRESHOLD": "#/components/schemas/ThresholdMetricResponse", "FORMULA": "#/components/schemas/FormulaMetricResponse", "PATTERN": "#/components/schemas/PatternMetricResponse", "HTTP_REQUEST": "#/components/schemas/HttpRequestMetricResponse" } }, "description": "Metric definition data. The variant is selected by `calculationType`." }, "LlmJudgeMetricResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the metric definition" }, "slug": { "type": "string", "description": "Stable metric slug (e.g. \"call_reason\", \"customer_satisfaction\")" }, "metricId": { "type": "string", "description": "Alias of `slug` retained for backwards compatibility. Same value as `slug`." }, "variantId": { "type": "string", "format": "uuid", "description": "The resolved variant this response reflects (org-scoped Default if the org has customized it, otherwise the system Default). Pass this as sourceVariantId when building a derived metric off this one to pin the exact config." }, "versionId": { "type": "string", "format": "uuid", "description": "The variant's current version. Immutable snapshot of the config — editing the metric produces a new versionId. Use it to detect config changes." }, "name": { "type": "string", "description": "Name of the metric" }, "description": { "type": "string", "description": "Description of what the metric measures" }, "type": { "type": "string", "enum": [ "COUNT", "NUMERIC", "BOOLEAN", "SCALE", "TEXT", "CLASSIFICATION", "OFFSET" ], "description": "Type of value this metric produces" }, "scope": { "type": "string", "enum": [ "GLOBAL", "PER_PARTICIPANT" ], "description": "Whether metric is global or per-participant" }, "supportedContexts": { "type": "array", "items": { "type": "string", "enum": [ "CALL", "SEGMENT", "TURN" ] }, "description": "Which levels this metric can produce values at" }, "supportedConversationSources": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "SIMULATED", "LIVE" ] }, "description": "Which kinds of conversation this metric can be scored on. `null` means both. `[\"LIVE\"]` marks a metric that can only be scored from your own recording of a real call, and `[\"SIMULATED\"]` one that only applies to simulations." }, "requiresLiveConversation": { "type": "boolean", "description": "True when this metric can only be scored from a live recording (`supportedConversationSources` is `[\"LIVE\"]`). Selecting one of these on a simulation run forces live enrichment: the run waits for your recording and, if none arrives, the metric produces no value. Check this before a run rather than discovering the wait afterwards." }, "supportsVariants": { "type": "boolean", "description": "Whether you can create a variant of this metric with POST /v1/metric/definitions/{idOrSlug}/variants. False for threshold metrics (their configuration comes from the metric they derive from), for HTTP request metrics (their configuration is the request, edited on the metric), for provider-computed metrics whose calculation lives in the collector rather than an editable prompt, and for metrics in a package that manages its own variants. Most of Roark’s own metrics are false, so read this rather than discovering it from a 403." }, "unit": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the unit" }, "symbol": { "type": [ "string", "null" ], "description": "Symbol for the unit" } }, "required": [ "name", "symbol" ], "description": "Unit information if applicable" }, "evidenceSource": { "type": [ "object", "null" ], "properties": { "metricId": { "type": "string", "description": "Slug of the metric whose per-turn values are the evidence behind this count or rate" }, "countsWhen": { "type": "boolean", "description": "The per-turn value this metric tallies. `false` for an \"incorrect\" count over an appropriateness metric, `true` for a count of a boolean event." } }, "required": [ "metricId", "countsWhen" ], "description": "For a Roark count or rate summed from the per-turn verdicts of a sibling metric (for example `incorrect_barge_in_yield_count` over `barge_in_yield_appropriateness`): where the reasoning and transcript positions live. The count value itself carries neither. `null` for a metric that is its own evidence." }, "calculationType": { "type": "string", "const": "LLM_JUDGE", "description": "Metric evaluated by an LLM against a prompt." }, "llmPrompt": { "type": [ "string", "null" ], "description": "The rubric this judge applies, as stored. Read it back to confirm which criteria are live after a create or update." }, "booleanTrueLabel": { "type": [ "string", "null" ], "description": "For a BOOLEAN metric, what a `true` value means. Also given to the judge as its polarity rule." }, "booleanFalseLabel": { "type": [ "string", "null" ], "description": "For a BOOLEAN metric, what a `false` value means. Also given to the judge as its polarity rule." } }, "required": [ "id", "slug", "metricId", "variantId", "versionId", "name", "description", "type", "scope", "supportedContexts", "supportedConversationSources", "requiresLiveConversation", "supportsVariants", "evidenceSource", "calculationType", "llmPrompt", "booleanTrueLabel", "booleanFalseLabel" ], "title": "LLM judge metric" }, "ProviderMetricResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the metric definition" }, "slug": { "type": "string", "description": "Stable metric slug (e.g. \"call_reason\", \"customer_satisfaction\")" }, "metricId": { "type": "string", "description": "Alias of `slug` retained for backwards compatibility. Same value as `slug`." }, "variantId": { "type": "string", "format": "uuid", "description": "The resolved variant this response reflects (org-scoped Default if the org has customized it, otherwise the system Default). Pass this as sourceVariantId when building a derived metric off this one to pin the exact config." }, "versionId": { "type": "string", "format": "uuid", "description": "The variant's current version. Immutable snapshot of the config — editing the metric produces a new versionId. Use it to detect config changes." }, "name": { "type": "string", "description": "Name of the metric" }, "description": { "type": "string", "description": "Description of what the metric measures" }, "type": { "type": "string", "enum": [ "COUNT", "NUMERIC", "BOOLEAN", "SCALE", "TEXT", "CLASSIFICATION", "OFFSET" ], "description": "Type of value this metric produces" }, "scope": { "type": "string", "enum": [ "GLOBAL", "PER_PARTICIPANT" ], "description": "Whether metric is global or per-participant" }, "supportedContexts": { "type": "array", "items": { "type": "string", "enum": [ "CALL", "SEGMENT", "TURN" ] }, "description": "Which levels this metric can produce values at" }, "supportedConversationSources": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "SIMULATED", "LIVE" ] }, "description": "Which kinds of conversation this metric can be scored on. `null` means both. `[\"LIVE\"]` marks a metric that can only be scored from your own recording of a real call, and `[\"SIMULATED\"]` one that only applies to simulations." }, "requiresLiveConversation": { "type": "boolean", "description": "True when this metric can only be scored from a live recording (`supportedConversationSources` is `[\"LIVE\"]`). Selecting one of these on a simulation run forces live enrichment: the run waits for your recording and, if none arrives, the metric produces no value. Check this before a run rather than discovering the wait afterwards." }, "supportsVariants": { "type": "boolean", "description": "Whether you can create a variant of this metric with POST /v1/metric/definitions/{idOrSlug}/variants. False for threshold metrics (their configuration comes from the metric they derive from), for HTTP request metrics (their configuration is the request, edited on the metric), for provider-computed metrics whose calculation lives in the collector rather than an editable prompt, and for metrics in a package that manages its own variants. Most of Roark’s own metrics are false, so read this rather than discovering it from a 403." }, "unit": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the unit" }, "symbol": { "type": [ "string", "null" ], "description": "Symbol for the unit" } }, "required": [ "name", "symbol" ], "description": "Unit information if applicable" }, "evidenceSource": { "type": [ "object", "null" ], "properties": { "metricId": { "type": "string", "description": "Slug of the metric whose per-turn values are the evidence behind this count or rate" }, "countsWhen": { "type": "boolean", "description": "The per-turn value this metric tallies. `false` for an \"incorrect\" count over an appropriateness metric, `true` for a count of a boolean event." } }, "required": [ "metricId", "countsWhen" ], "description": "For a Roark count or rate summed from the per-turn verdicts of a sibling metric (for example `incorrect_barge_in_yield_count` over `barge_in_yield_appropriateness`): where the reasoning and transcript positions live. The count value itself carries neither. `null` for a metric that is its own evidence." }, "calculationType": { "type": "string", "const": "PROVIDER", "description": "System-managed metric produced by an analysis provider." } }, "required": [ "id", "slug", "metricId", "variantId", "versionId", "name", "description", "type", "scope", "supportedContexts", "supportedConversationSources", "requiresLiveConversation", "supportsVariants", "evidenceSource", "calculationType" ], "title": "Provider metric" }, "ThresholdMetricResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the metric definition" }, "slug": { "type": "string", "description": "Stable metric slug (e.g. \"call_reason\", \"customer_satisfaction\")" }, "metricId": { "type": "string", "description": "Alias of `slug` retained for backwards compatibility. Same value as `slug`." }, "variantId": { "type": "string", "format": "uuid", "description": "The resolved variant this response reflects (org-scoped Default if the org has customized it, otherwise the system Default). Pass this as sourceVariantId when building a derived metric off this one to pin the exact config." }, "versionId": { "type": "string", "format": "uuid", "description": "The variant's current version. Immutable snapshot of the config — editing the metric produces a new versionId. Use it to detect config changes." }, "name": { "type": "string", "description": "Name of the metric" }, "description": { "type": "string", "description": "Description of what the metric measures" }, "type": { "type": "string", "enum": [ "COUNT", "NUMERIC", "BOOLEAN", "SCALE", "TEXT", "CLASSIFICATION", "OFFSET" ], "description": "Type of value this metric produces" }, "scope": { "type": "string", "enum": [ "GLOBAL", "PER_PARTICIPANT" ], "description": "Whether metric is global or per-participant" }, "supportedContexts": { "type": "array", "items": { "type": "string", "enum": [ "CALL", "SEGMENT", "TURN" ] }, "description": "Which levels this metric can produce values at" }, "supportedConversationSources": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "SIMULATED", "LIVE" ] }, "description": "Which kinds of conversation this metric can be scored on. `null` means both. `[\"LIVE\"]` marks a metric that can only be scored from your own recording of a real call, and `[\"SIMULATED\"]` one that only applies to simulations." }, "requiresLiveConversation": { "type": "boolean", "description": "True when this metric can only be scored from a live recording (`supportedConversationSources` is `[\"LIVE\"]`). Selecting one of these on a simulation run forces live enrichment: the run waits for your recording and, if none arrives, the metric produces no value. Check this before a run rather than discovering the wait afterwards." }, "supportsVariants": { "type": "boolean", "description": "Whether you can create a variant of this metric with POST /v1/metric/definitions/{idOrSlug}/variants. False for threshold metrics (their configuration comes from the metric they derive from), for HTTP request metrics (their configuration is the request, edited on the metric), for provider-computed metrics whose calculation lives in the collector rather than an editable prompt, and for metrics in a package that manages its own variants. Most of Roark’s own metrics are false, so read this rather than discovering it from a 403." }, "unit": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the unit" }, "symbol": { "type": [ "string", "null" ], "description": "Symbol for the unit" } }, "required": [ "name", "symbol" ], "description": "Unit information if applicable" }, "evidenceSource": { "type": [ "object", "null" ], "properties": { "metricId": { "type": "string", "description": "Slug of the metric whose per-turn values are the evidence behind this count or rate" }, "countsWhen": { "type": "boolean", "description": "The per-turn value this metric tallies. `false` for an \"incorrect\" count over an appropriateness metric, `true` for a count of a boolean event." } }, "required": [ "metricId", "countsWhen" ], "description": "For a Roark count or rate summed from the per-turn verdicts of a sibling metric (for example `incorrect_barge_in_yield_count` over `barge_in_yield_appropriateness`): where the reasoning and transcript positions live. The count value itself carries neither. `null` for a metric that is its own evidence." }, "calculationType": { "type": "string", "const": "THRESHOLD", "description": "Boolean metric derived by comparing a source metric against a threshold." }, "threshold": { "$ref": "#/components/schemas/ThresholdMetricDetails", "description": "Threshold configuration." } }, "required": [ "id", "slug", "metricId", "variantId", "versionId", "name", "description", "type", "scope", "supportedContexts", "supportedConversationSources", "requiresLiveConversation", "supportsVariants", "evidenceSource", "calculationType" ], "title": "Threshold metric" }, "ThresholdMetricDetails": { "type": "object", "properties": { "sourceMetricDefinitionId": { "type": "string", "format": "uuid" }, "operator": { "type": "string", "enum": [ "GREATER_THAN", "GREATER_THAN_OR_EQUALS", "LESS_THAN", "LESS_THAN_OR_EQUALS", "EQUALS", "NOT_EQUALS" ] }, "thresholdValue": { "type": "string" }, "aggregationMode": { "type": "string", "enum": [ "EACH", "COUNT", "AVERAGE", "MIN", "MAX", "MEDIAN", "P95", "P99", "SUM" ] }, "countThreshold": { "type": [ "integer", "null" ] }, "sourceParticipantRole": { "type": [ "string", "null" ], "enum": [ "AGENT", "CUSTOMER", "SIMULATED_CUSTOMER", "BACKGROUND_SPEAKER" ] }, "sourceVariantId": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "sourceMetricDefinitionId", "operator", "thresholdValue", "aggregationMode", "countThreshold", "sourceParticipantRole", "sourceVariantId" ] }, "FormulaMetricResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the metric definition" }, "slug": { "type": "string", "description": "Stable metric slug (e.g. \"call_reason\", \"customer_satisfaction\")" }, "metricId": { "type": "string", "description": "Alias of `slug` retained for backwards compatibility. Same value as `slug`." }, "variantId": { "type": "string", "format": "uuid", "description": "The resolved variant this response reflects (org-scoped Default if the org has customized it, otherwise the system Default). Pass this as sourceVariantId when building a derived metric off this one to pin the exact config." }, "versionId": { "type": "string", "format": "uuid", "description": "The variant's current version. Immutable snapshot of the config — editing the metric produces a new versionId. Use it to detect config changes." }, "name": { "type": "string", "description": "Name of the metric" }, "description": { "type": "string", "description": "Description of what the metric measures" }, "type": { "type": "string", "enum": [ "COUNT", "NUMERIC", "BOOLEAN", "SCALE", "TEXT", "CLASSIFICATION", "OFFSET" ], "description": "Type of value this metric produces" }, "scope": { "type": "string", "enum": [ "GLOBAL", "PER_PARTICIPANT" ], "description": "Whether metric is global or per-participant" }, "supportedContexts": { "type": "array", "items": { "type": "string", "enum": [ "CALL", "SEGMENT", "TURN" ] }, "description": "Which levels this metric can produce values at" }, "supportedConversationSources": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "SIMULATED", "LIVE" ] }, "description": "Which kinds of conversation this metric can be scored on. `null` means both. `[\"LIVE\"]` marks a metric that can only be scored from your own recording of a real call, and `[\"SIMULATED\"]` one that only applies to simulations." }, "requiresLiveConversation": { "type": "boolean", "description": "True when this metric can only be scored from a live recording (`supportedConversationSources` is `[\"LIVE\"]`). Selecting one of these on a simulation run forces live enrichment: the run waits for your recording and, if none arrives, the metric produces no value. Check this before a run rather than discovering the wait afterwards." }, "supportsVariants": { "type": "boolean", "description": "Whether you can create a variant of this metric with POST /v1/metric/definitions/{idOrSlug}/variants. False for threshold metrics (their configuration comes from the metric they derive from), for HTTP request metrics (their configuration is the request, edited on the metric), for provider-computed metrics whose calculation lives in the collector rather than an editable prompt, and for metrics in a package that manages its own variants. Most of Roark’s own metrics are false, so read this rather than discovering it from a 403." }, "unit": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the unit" }, "symbol": { "type": [ "string", "null" ], "description": "Symbol for the unit" } }, "required": [ "name", "symbol" ], "description": "Unit information if applicable" }, "evidenceSource": { "type": [ "object", "null" ], "properties": { "metricId": { "type": "string", "description": "Slug of the metric whose per-turn values are the evidence behind this count or rate" }, "countsWhen": { "type": "boolean", "description": "The per-turn value this metric tallies. `false` for an \"incorrect\" count over an appropriateness metric, `true` for a count of a boolean event." } }, "required": [ "metricId", "countsWhen" ], "description": "For a Roark count or rate summed from the per-turn verdicts of a sibling metric (for example `incorrect_barge_in_yield_count` over `barge_in_yield_appropriateness`): where the reasoning and transcript positions live. The count value itself carries neither. `null` for a metric that is its own evidence." }, "calculationType": { "type": "string", "const": "FORMULA", "description": "Metric computed by evaluating an expression over other metrics." }, "formula": { "$ref": "#/components/schemas/FormulaMetricDetails", "description": "Formula configuration." } }, "required": [ "id", "slug", "metricId", "variantId", "versionId", "name", "description", "type", "scope", "supportedContexts", "supportedConversationSources", "requiresLiveConversation", "supportsVariants", "evidenceSource", "calculationType", "formula" ], "title": "Formula metric" }, "FormulaMetricDetails": { "type": "object", "properties": { "expression": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "sourceMetricDefinitionId": { "type": "string", "format": "uuid" }, "sourceVariantId": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "sourceMetricDefinitionId", "sourceVariantId" ] } } }, "required": [ "expression", "sources" ] }, "PatternMetricResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the metric definition" }, "slug": { "type": "string", "description": "Stable metric slug (e.g. \"call_reason\", \"customer_satisfaction\")" }, "metricId": { "type": "string", "description": "Alias of `slug` retained for backwards compatibility. Same value as `slug`." }, "variantId": { "type": "string", "format": "uuid", "description": "The resolved variant this response reflects (org-scoped Default if the org has customized it, otherwise the system Default). Pass this as sourceVariantId when building a derived metric off this one to pin the exact config." }, "versionId": { "type": "string", "format": "uuid", "description": "The variant's current version. Immutable snapshot of the config — editing the metric produces a new versionId. Use it to detect config changes." }, "name": { "type": "string", "description": "Name of the metric" }, "description": { "type": "string", "description": "Description of what the metric measures" }, "type": { "type": "string", "enum": [ "COUNT", "NUMERIC", "BOOLEAN", "SCALE", "TEXT", "CLASSIFICATION", "OFFSET" ], "description": "Type of value this metric produces" }, "scope": { "type": "string", "enum": [ "GLOBAL", "PER_PARTICIPANT" ], "description": "Whether metric is global or per-participant" }, "supportedContexts": { "type": "array", "items": { "type": "string", "enum": [ "CALL", "SEGMENT", "TURN" ] }, "description": "Which levels this metric can produce values at" }, "supportedConversationSources": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "SIMULATED", "LIVE" ] }, "description": "Which kinds of conversation this metric can be scored on. `null` means both. `[\"LIVE\"]` marks a metric that can only be scored from your own recording of a real call, and `[\"SIMULATED\"]` one that only applies to simulations." }, "requiresLiveConversation": { "type": "boolean", "description": "True when this metric can only be scored from a live recording (`supportedConversationSources` is `[\"LIVE\"]`). Selecting one of these on a simulation run forces live enrichment: the run waits for your recording and, if none arrives, the metric produces no value. Check this before a run rather than discovering the wait afterwards." }, "supportsVariants": { "type": "boolean", "description": "Whether you can create a variant of this metric with POST /v1/metric/definitions/{idOrSlug}/variants. False for threshold metrics (their configuration comes from the metric they derive from), for HTTP request metrics (their configuration is the request, edited on the metric), for provider-computed metrics whose calculation lives in the collector rather than an editable prompt, and for metrics in a package that manages its own variants. Most of Roark’s own metrics are false, so read this rather than discovering it from a 403." }, "unit": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the unit" }, "symbol": { "type": [ "string", "null" ], "description": "Symbol for the unit" } }, "required": [ "name", "symbol" ], "description": "Unit information if applicable" }, "evidenceSource": { "type": [ "object", "null" ], "properties": { "metricId": { "type": "string", "description": "Slug of the metric whose per-turn values are the evidence behind this count or rate" }, "countsWhen": { "type": "boolean", "description": "The per-turn value this metric tallies. `false` for an \"incorrect\" count over an appropriateness metric, `true` for a count of a boolean event." } }, "required": [ "metricId", "countsWhen" ], "description": "For a Roark count or rate summed from the per-turn verdicts of a sibling metric (for example `incorrect_barge_in_yield_count` over `barge_in_yield_appropriateness`): where the reasoning and transcript positions live. The count value itself carries neither. `null` for a metric that is its own evidence." }, "calculationType": { "type": "string", "const": "PATTERN", "description": "Metric detecting a trigger condition followed by an outcome within a window." }, "pattern": { "$ref": "#/components/schemas/PatternMetricDetails", "description": "Pattern configuration." } }, "required": [ "id", "slug", "metricId", "variantId", "versionId", "name", "description", "type", "scope", "supportedContexts", "supportedConversationSources", "requiresLiveConversation", "supportsVariants", "evidenceSource", "calculationType", "pattern" ], "title": "Pattern metric" }, "PatternMetricDetails": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "PATTERN_EXISTS", "PATTERN_COUNT", "OUTCOME_AGGREGATE" ] }, "windowMode": { "type": [ "string", "null" ] }, "triggerCombinator": { "type": [ "string", "null" ], "enum": [ "AND", "OR" ] }, "triggers": { "type": "array", "items": { "type": "object", "properties": { "sourceMetricDefinitionId": { "type": "string", "format": "uuid" }, "operator": { "type": "string", "enum": [ "GREATER_THAN", "GREATER_THAN_OR_EQUALS", "LESS_THAN", "LESS_THAN_OR_EQUALS", "EQUALS", "NOT_EQUALS" ] }, "thresholdValue": { "type": "string" }, "sourceParticipantRole": { "type": [ "string", "null" ], "enum": [ "AGENT", "CUSTOMER", "SIMULATED_CUSTOMER", "BACKGROUND_SPEAKER" ] }, "sourceVariantId": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "sourceMetricDefinitionId", "operator", "thresholdValue", "sourceParticipantRole", "sourceVariantId" ] } }, "outcome": { "type": [ "object", "null" ], "properties": { "sourceMetricDefinitionId": { "type": "string", "format": "uuid" }, "operator": { "type": "string", "enum": [ "GREATER_THAN", "GREATER_THAN_OR_EQUALS", "LESS_THAN", "LESS_THAN_OR_EQUALS", "EQUALS", "NOT_EQUALS" ] }, "thresholdValue": { "type": "string" }, "sourceParticipantRole": { "type": [ "string", "null" ], "enum": [ "AGENT", "CUSTOMER", "SIMULATED_CUSTOMER", "BACKGROUND_SPEAKER" ] }, "sourceVariantId": { "type": [ "string", "null" ], "format": "uuid" }, "windowBefore": { "type": [ "integer", "null" ] }, "windowAfter": { "type": [ "integer", "null" ] } }, "required": [ "sourceMetricDefinitionId", "operator", "thresholdValue", "sourceParticipantRole", "sourceVariantId", "windowBefore", "windowAfter" ] } }, "required": [ "operation", "windowMode", "triggerCombinator", "triggers", "outcome" ] }, "HttpRequestMetricResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the metric definition" }, "slug": { "type": "string", "description": "Stable metric slug (e.g. \"call_reason\", \"customer_satisfaction\")" }, "metricId": { "type": "string", "description": "Alias of `slug` retained for backwards compatibility. Same value as `slug`." }, "variantId": { "type": "string", "format": "uuid", "description": "The resolved variant this response reflects (org-scoped Default if the org has customized it, otherwise the system Default). Pass this as sourceVariantId when building a derived metric off this one to pin the exact config." }, "versionId": { "type": "string", "format": "uuid", "description": "The variant's current version. Immutable snapshot of the config — editing the metric produces a new versionId. Use it to detect config changes." }, "name": { "type": "string", "description": "Name of the metric" }, "description": { "type": "string", "description": "Description of what the metric measures" }, "type": { "type": "string", "enum": [ "COUNT", "NUMERIC", "BOOLEAN", "SCALE", "TEXT", "CLASSIFICATION", "OFFSET" ], "description": "Type of value this metric produces" }, "scope": { "type": "string", "enum": [ "GLOBAL", "PER_PARTICIPANT" ], "description": "Whether metric is global or per-participant" }, "supportedContexts": { "type": "array", "items": { "type": "string", "enum": [ "CALL", "SEGMENT", "TURN" ] }, "description": "Which levels this metric can produce values at" }, "supportedConversationSources": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "SIMULATED", "LIVE" ] }, "description": "Which kinds of conversation this metric can be scored on. `null` means both. `[\"LIVE\"]` marks a metric that can only be scored from your own recording of a real call, and `[\"SIMULATED\"]` one that only applies to simulations." }, "requiresLiveConversation": { "type": "boolean", "description": "True when this metric can only be scored from a live recording (`supportedConversationSources` is `[\"LIVE\"]`). Selecting one of these on a simulation run forces live enrichment: the run waits for your recording and, if none arrives, the metric produces no value. Check this before a run rather than discovering the wait afterwards." }, "supportsVariants": { "type": "boolean", "description": "Whether you can create a variant of this metric with POST /v1/metric/definitions/{idOrSlug}/variants. False for threshold metrics (their configuration comes from the metric they derive from), for HTTP request metrics (their configuration is the request, edited on the metric), for provider-computed metrics whose calculation lives in the collector rather than an editable prompt, and for metrics in a package that manages its own variants. Most of Roark’s own metrics are false, so read this rather than discovering it from a 403." }, "unit": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the unit" }, "symbol": { "type": [ "string", "null" ], "description": "Symbol for the unit" } }, "required": [ "name", "symbol" ], "description": "Unit information if applicable" }, "evidenceSource": { "type": [ "object", "null" ], "properties": { "metricId": { "type": "string", "description": "Slug of the metric whose per-turn values are the evidence behind this count or rate" }, "countsWhen": { "type": "boolean", "description": "The per-turn value this metric tallies. `false` for an \"incorrect\" count over an appropriateness metric, `true` for a count of a boolean event." } }, "required": [ "metricId", "countsWhen" ], "description": "For a Roark count or rate summed from the per-turn verdicts of a sibling metric (for example `incorrect_barge_in_yield_count` over `barge_in_yield_appropriateness`): where the reasoning and transcript positions live. The count value itself carries neither. `null` for a metric that is its own evidence." }, "calculationType": { "type": "string", "const": "HTTP_REQUEST", "description": "BOOLEAN metric answered by your own endpoint: Roark sends a request about each call and records the {\"passed\", \"reason\"} it answers with." }, "httpRequest": { "oneOf": [ { "$ref": "#/components/schemas/HttpRequestMetricDetails" }, { "type": "null" } ], "description": "The request this metric sends." }, "booleanTrueLabel": { "type": [ "string", "null" ], "description": "What a passed check is called" }, "booleanFalseLabel": { "type": [ "string", "null" ], "description": "What a failed check is called" } }, "required": [ "id", "slug", "metricId", "variantId", "versionId", "name", "description", "type", "scope", "supportedContexts", "supportedConversationSources", "requiresLiveConversation", "supportsVariants", "evidenceSource", "calculationType", "httpRequest", "booleanTrueLabel", "booleanFalseLabel" ], "title": "HTTP request metric" }, "HttpRequestMetricDetails": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL the request is sent to, placeholders included" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Request headers as key-value pairs" }, "body": { "type": [ "string", "null" ], "description": "The JSON body template, or null when the default payload is sent" } }, "required": [ "url", "method", "headers", "body" ] }, "CreateMetricDefinitionResponse": { "oneOf": [ { "$ref": "#/components/schemas/LlmJudgeMetricResponse" }, { "$ref": "#/components/schemas/FormulaMetricResponse" }, { "$ref": "#/components/schemas/PatternMetricResponse" }, { "$ref": "#/components/schemas/HttpRequestMetricResponse" } ], "discriminator": { "propertyName": "calculationType", "mapping": { "LLM_JUDGE": "#/components/schemas/LlmJudgeMetricResponse", "FORMULA": "#/components/schemas/FormulaMetricResponse", "PATTERN": "#/components/schemas/PatternMetricResponse", "HTTP_REQUEST": "#/components/schemas/HttpRequestMetricResponse" } }, "description": "The created metric definition. The variant is selected by `calculationType`." }, "CreateMetricDefinitionInput": { "oneOf": [ { "$ref": "#/components/schemas/PromptMetricInput" }, { "$ref": "#/components/schemas/FormulaMetricInput" }, { "$ref": "#/components/schemas/PatternMetricInput" }, { "$ref": "#/components/schemas/HttpRequestMetricInput" } ], "discriminator": { "propertyName": "calculationType", "mapping": { "LLM_JUDGE": "#/components/schemas/PromptMetricInput", "FORMULA": "#/components/schemas/FormulaMetricInput", "PATTERN": "#/components/schemas/PatternMetricInput", "HTTP_REQUEST": "#/components/schemas/HttpRequestMetricInput" } }, "description": "Input for creating a new metric definition. `calculationType` selects the variant and defaults to LLM_JUDGE when omitted (legacy prompt-metric payloads remain valid). To create a threshold, use the threshold sub-resource." }, "PromptMetricInput": { "type": "object", "properties": { "calculationType": { "type": "string", "const": "LLM_JUDGE", "description": "LLM-evaluated metric." }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Name of the metric", "example": "Customer Satisfaction" }, "slug": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Stable slug for the metric. Auto-generated from name if omitted.", "example": "customer_satisfaction" }, "metricId": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Alias of `slug` accepted for backwards compatibility. Use `slug` for new integrations.", "example": "customer_satisfaction" }, "outputType": { "type": "string", "enum": [ "COUNT", "NUMERIC", "BOOLEAN", "SCALE", "TEXT", "CLASSIFICATION", "OFFSET" ], "description": "Type of value this metric produces", "example": "BOOLEAN" }, "scope": { "type": "string", "enum": [ "GLOBAL", "PER_PARTICIPANT" ], "default": "GLOBAL", "description": "Whether metric is global or per-participant (default: GLOBAL)" }, "participantRole": { "type": "string", "enum": [ "AGENT", "CUSTOMER", "SIMULATED_CUSTOMER", "BACKGROUND_SPEAKER" ], "description": "Participant role to evaluate. Required when scope is PER_PARTICIPANT." }, "supportedContexts": { "type": "array", "items": { "type": "string", "enum": [ "CALL", "SEGMENT", "TURN" ] }, "minItems": 1, "default": [ "CALL" ], "description": "What the judge grades (default: [\"CALL\"], the whole conversation). [\"CALL\", \"SEGMENT\"] also grades each utterance of `participantRole`; [\"CALL\", \"TURN\"] also grades each agent reply to the caller (requires `participantRole: AGENT`). Per-utterance and per-reply grading needs `scope: PER_PARTICIPANT` and a BOOLEAN, SCALE, NUMERIC or COUNT output; the CALL value stays the graded result and the per-unit values are its evidence.", "example": [ "CALL", "TURN" ] }, "llmPrompt": { "type": "string", "maxLength": 20000, "description": "LLM prompt/criteria for evaluating this metric. Required for BOOLEAN, NUMERIC, TEXT, and SCALE types.", "example": "Evaluate whether the customer expressed satisfaction with the service provided." }, "analysisPackageId": { "type": "string", "format": "uuid", "description": "ID of the analysis package to add this metric to. Optional: when omitted, the metric is added to a default \"Custom Metrics\" package for your project (created automatically the first time)." }, "booleanTrueLabel": { "type": "string", "description": "Label for the true case (only for BOOLEAN type)" }, "booleanFalseLabel": { "type": "string", "description": "Label for the false case (only for BOOLEAN type)" }, "scaleMin": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Minimum value for scale. Required for SCALE type." }, "scaleMax": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Maximum value for scale. Required for SCALE type." }, "scaleLabels": { "type": "array", "items": { "type": "object", "properties": { "rangeMin": { "type": "number", "description": "Minimum value for this label range" }, "rangeMax": { "type": "number", "description": "Maximum value for this label range" }, "label": { "type": "string", "description": "Label for this range" }, "description": { "type": "string", "description": "Description of what this range means" }, "displayOrder": { "type": "integer", "description": "Display order of this label" }, "colorHex": { "type": "string", "description": "Hex color code for this label (e.g. \"#FF0000\")" } }, "required": [ "rangeMin", "rangeMax", "label", "displayOrder" ] }, "description": "Labels for scale ranges (only for SCALE type)" }, "classificationOptions": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "description": { "type": "string" }, "displayOrder": { "type": "integer" } }, "required": [ "label", "description", "displayOrder" ], "description": "Option for classification metrics." }, "minItems": 1, "description": "Options for classification. Required for CLASSIFICATION type." }, "maxClassifications": { "type": "integer", "minimum": 1, "description": "Maximum number of classifications that can be selected (only for CLASSIFICATION type)" } }, "required": [ "calculationType", "name", "outputType" ], "title": "LLM judge metric" }, "FormulaMetricInput": { "type": "object", "properties": { "calculationType": { "type": "string", "const": "FORMULA", "description": "Metric computed by evaluating a mathematical expression over other metrics." }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Name of the metric", "example": "Customer Satisfaction" }, "slug": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Stable slug for the metric. Auto-generated from name if omitted.", "example": "customer_satisfaction" }, "metricId": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Alias of `slug` accepted for backwards compatibility. Use `slug` for new integrations.", "example": "customer_satisfaction" }, "outputType": { "type": "string", "enum": [ "NUMERIC", "BOOLEAN" ], "description": "Output type of the formula. NUMERIC for arithmetic expressions, BOOLEAN for comparison expressions.", "example": "NUMERIC" }, "formula": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Formula expression using `{{id:}}` references to source metrics. Operators depend on output type: +, -, *, / for NUMERIC; ==, !=, >=, <=, >, < for BOOLEAN.", "example": "{{id:00000000-0000-0000-0000-000000000001}} / {{id:00000000-0000-0000-0000-000000000002}}" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "sourceMetricDefinitionId": { "type": "string", "format": "uuid", "description": "ID of a metric referenced in the formula" }, "sourceVariantId": { "type": "string", "format": "uuid", "description": "Variant of the source metric to use" } }, "required": [ "sourceMetricDefinitionId" ] }, "minItems": 2, "description": "Source metrics referenced by the formula. Minimum 2." }, "analysisPackageId": { "type": "string", "format": "uuid", "description": "ID of the analysis package to add this metric to. Optional: when omitted, the metric is added to a default \"Custom Metrics\" package for your project (created automatically the first time)." } }, "required": [ "calculationType", "name", "outputType", "formula", "sources" ], "title": "Formula metric" }, "PatternMetricInput": { "type": "object", "properties": { "calculationType": { "type": "string", "const": "PATTERN", "description": "Metric detecting temporal patterns: a trigger condition followed by an outcome within a window." }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Name of the metric", "example": "Customer Satisfaction" }, "slug": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Stable slug for the metric. Auto-generated from name if omitted.", "example": "customer_satisfaction" }, "metricId": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Alias of `slug` accepted for backwards compatibility. Use `slug` for new integrations.", "example": "customer_satisfaction" }, "operation": { "type": "string", "enum": [ "PATTERN_EXISTS", "PATTERN_COUNT", "OUTCOME_AGGREGATE" ], "description": "Pattern operation. PATTERN_EXISTS produces a BOOLEAN; PATTERN_COUNT produces a NUMERIC count; OUTCOME_AGGREGATE aggregates a numeric outcome.", "example": "PATTERN_EXISTS" }, "windowMode": { "type": "string", "enum": [ "seconds", "segments" ], "default": "seconds", "description": "Unit for trigger/outcome window values (default: seconds)" }, "trigger": { "type": "object", "properties": { "sourceMetricDefinitionId": { "type": "string", "format": "uuid" }, "operator": { "type": "string", "enum": [ "GREATER_THAN", "GREATER_THAN_OR_EQUALS", "LESS_THAN", "LESS_THAN_OR_EQUALS", "EQUALS", "NOT_EQUALS" ] }, "thresholdValue": { "type": "string", "minLength": 1 }, "sourceParticipantRole": { "type": "string", "enum": [ "AGENT", "CUSTOMER", "SIMULATED_CUSTOMER", "BACKGROUND_SPEAKER" ] }, "sourceVariantId": { "type": "string", "format": "uuid" } }, "required": [ "sourceMetricDefinitionId", "operator", "thresholdValue" ], "description": "Single trigger condition. Use either trigger or triggers + triggerCombinator." }, "triggers": { "type": "array", "items": { "type": "object", "properties": { "sourceMetricDefinitionId": { "type": "string", "format": "uuid" }, "operator": { "type": "string", "enum": [ "GREATER_THAN", "GREATER_THAN_OR_EQUALS", "LESS_THAN", "LESS_THAN_OR_EQUALS", "EQUALS", "NOT_EQUALS" ] }, "thresholdValue": { "type": "string", "minLength": 1 }, "sourceParticipantRole": { "type": "string", "enum": [ "AGENT", "CUSTOMER", "SIMULATED_CUSTOMER", "BACKGROUND_SPEAKER" ] }, "sourceVariantId": { "type": "string", "format": "uuid" } }, "required": [ "sourceMetricDefinitionId", "operator", "thresholdValue" ] }, "minItems": 1, "description": "Multiple trigger conditions. Use with triggerCombinator." }, "triggerCombinator": { "type": "string", "enum": [ "AND", "OR" ], "description": "How to combine multiple triggers. Required when triggers has more than 1 entry." }, "outcome": { "type": "object", "properties": { "sourceMetricDefinitionId": { "type": "string", "format": "uuid" }, "operator": { "type": "string", "enum": [ "GREATER_THAN", "GREATER_THAN_OR_EQUALS", "LESS_THAN", "LESS_THAN_OR_EQUALS", "EQUALS", "NOT_EQUALS" ] }, "thresholdValue": { "type": "string", "minLength": 1 }, "sourceParticipantRole": { "type": "string", "enum": [ "AGENT", "CUSTOMER", "SIMULATED_CUSTOMER", "BACKGROUND_SPEAKER" ] }, "sourceVariantId": { "type": "string", "format": "uuid" }, "windowAfter": { "type": "integer", "minimum": 0, "description": "How far after the trigger to look for the outcome (in seconds or segments, see windowMode)" }, "windowBefore": { "type": "integer", "minimum": 0, "description": "How far before the trigger to look for the outcome (default: 0)" } }, "required": [ "sourceMetricDefinitionId", "operator", "thresholdValue", "windowAfter" ], "description": "Outcome condition evaluated within the window relative to the trigger." }, "analysisPackageId": { "type": "string", "format": "uuid", "description": "ID of the analysis package to add this metric to. Optional: when omitted, the metric is added to a default \"Custom Metrics\" package for your project (created automatically the first time)." } }, "required": [ "calculationType", "name", "operation", "outcome" ], "title": "Pattern metric" }, "HttpRequestMetricInput": { "type": "object", "properties": { "calculationType": { "type": "string", "const": "HTTP_REQUEST", "description": "BOOLEAN metric answered by your own endpoint. Roark sends a request about each call, live or simulated, and your endpoint answers {\"passed\": true | false, \"reason\": \"...\"}." }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Name of the metric", "example": "Customer Satisfaction" }, "slug": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Stable slug for the metric. Auto-generated from name if omitted.", "example": "customer_satisfaction" }, "metricId": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Alias of `slug` accepted for backwards compatibility. Use `slug` for new integrations.", "example": "customer_satisfaction" }, "httpRequest": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "Public http(s) URL. May contain {{path}} placeholders into the request payload, which are URL-encoded.", "example": "https://api.example.com/roark/checks/pin-changed" }, "method": { "type": "string", "enum": [ "GET", "POST" ], "default": "POST", "description": "GET or POST (default POST). A GET request has no body." }, "headers": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 200 }, "additionalProperties": { "type": "string", "maxLength": 4000 }, "description": "Request headers, for example your own Authorization header. Values may contain placeholders.", "example": { "Authorization": "Bearer sk_live_..." } }, "body": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20000, "description": "A JSON template with {{path}} placeholders into the request payload, such as {\"cardId\": \"{{call.properties.cardId}}\"}. Omit or pass null to send the default payload." } }, "required": [ "url" ], "title": "HTTP request metric request", "description": "The request to send. With no body, Roark POSTs the default payload: { version, requestId, metric, call, simulation }." }, "analysisPackageId": { "type": "string", "format": "uuid", "description": "ID of the analysis package to add this metric to. Optional: when omitted, the metric is added to a default \"Custom Metrics\" package for your project (created automatically the first time)." }, "booleanTrueLabel": { "type": "string", "description": "What a passed check is called (default: Pass)" }, "booleanFalseLabel": { "type": "string", "description": "What a failed check is called (default: Fail)" } }, "required": [ "calculationType", "name", "httpRequest" ], "title": "HTTP request metric" }, "HttpRequestMetricConfig": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "Public http(s) URL. May contain {{path}} placeholders into the request payload, which are URL-encoded.", "example": "https://api.example.com/roark/checks/pin-changed" }, "method": { "type": "string", "enum": [ "GET", "POST" ], "default": "POST", "description": "GET or POST (default POST). A GET request has no body." }, "headers": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 200 }, "additionalProperties": { "type": "string", "maxLength": 4000 }, "description": "Request headers, for example your own Authorization header. Values may contain placeholders.", "example": { "Authorization": "Bearer sk_live_..." } }, "body": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20000, "description": "A JSON template with {{path}} placeholders into the request payload, such as {\"cardId\": \"{{call.properties.cardId}}\"}. Omit or pass null to send the default payload." } }, "required": [ "url" ], "title": "HTTP request metric request" }, "CreateThresholdInput": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Stable slug for the metric. Auto-generated from name if omitted.", "example": "customer_satisfaction" }, "metricId": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Alias of `slug` accepted for backwards compatibility. Use `slug` for new integrations.", "example": "customer_satisfaction" }, "operator": { "type": "string", "enum": [ "GREATER_THAN", "GREATER_THAN_OR_EQUALS", "LESS_THAN", "LESS_THAN_OR_EQUALS", "EQUALS", "NOT_EQUALS" ], "description": "Comparison operator", "example": "GREATER_THAN_OR_EQUALS" }, "value": { "type": "string", "minLength": 1, "description": "Value to compare the source metric against (as a string)", "example": "4" }, "aggregationMode": { "type": "string", "enum": [ "EACH", "COUNT", "AVERAGE", "MIN", "MAX", "MEDIAN", "P95", "P99", "SUM" ], "default": "EACH", "description": "How to aggregate the source metric before applying the comparison (default: EACH)" }, "countThreshold": { "type": "integer", "minimum": 0, "description": "Required when aggregationMode is COUNT. The threshold fires when the count is met." }, "sourceParticipantRole": { "type": "string", "enum": [ "AGENT", "CUSTOMER", "SIMULATED_CUSTOMER", "BACKGROUND_SPEAKER" ], "description": "When the source metric is per-participant, restrict evaluation to this role. Only valid for sources with TURN/SEGMENT contexts." }, "sourceVariantId": { "type": "string", "format": "uuid", "description": "Variant of the source metric to use" } }, "required": [ "operator", "value" ], "description": "Input for creating a new threshold derived from a source metric." }, "UpdateMetricDefinitionResponse": { "oneOf": [ { "$ref": "#/components/schemas/LlmJudgeMetricResponse" }, { "$ref": "#/components/schemas/FormulaMetricResponse" }, { "$ref": "#/components/schemas/PatternMetricResponse" }, { "$ref": "#/components/schemas/ThresholdMetricResponse" }, { "$ref": "#/components/schemas/HttpRequestMetricResponse" } ], "discriminator": { "propertyName": "calculationType", "mapping": { "LLM_JUDGE": "#/components/schemas/LlmJudgeMetricResponse", "FORMULA": "#/components/schemas/FormulaMetricResponse", "PATTERN": "#/components/schemas/PatternMetricResponse", "THRESHOLD": "#/components/schemas/ThresholdMetricResponse", "HTTP_REQUEST": "#/components/schemas/HttpRequestMetricResponse" } }, "description": "The updated metric definition. The variant is selected by `calculationType`." }, "UpdateMetricDefinitionInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "New name (only for metrics whose name is editable)" }, "llmPrompt": { "type": "string", "maxLength": 20000, "description": "New LLM prompt (only for LLM_JUDGE metrics whose prompt is editable)" }, "scaleMin": { "type": "integer", "minimum": 0, "maximum": 100, "description": "New scale minimum (SCALE output only)" }, "scaleMax": { "type": "integer", "minimum": 0, "maximum": 100, "description": "New scale maximum (SCALE output only)" }, "scaleLabels": { "type": "array", "items": { "type": "object", "properties": { "rangeMin": { "type": "number", "description": "Minimum value for this label range" }, "rangeMax": { "type": "number", "description": "Maximum value for this label range" }, "label": { "type": "string", "description": "Label for this range" }, "description": { "type": "string", "description": "Description of what this range means" }, "displayOrder": { "type": "integer", "description": "Display order of this label" }, "colorHex": { "type": "string", "description": "Hex color code for this label (e.g. \"#FF0000\")" } }, "required": [ "rangeMin", "rangeMax", "label", "displayOrder" ] }, "description": "Replacement set of scale-range labels (SCALE output only)" }, "booleanTrueLabel": { "type": "string", "description": "New label for the true case (BOOLEAN output only)" }, "booleanFalseLabel": { "type": "string", "description": "New label for the false case (BOOLEAN output only)" }, "classificationOptions": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "description": { "type": "string" }, "displayOrder": { "type": "integer" } }, "required": [ "label", "description", "displayOrder" ], "description": "Option for classification metrics." }, "minItems": 1, "description": "Replacement set of classification options (CLASSIFICATION output only)" }, "maxClassifications": { "type": "integer", "minimum": 1, "description": "New maximum number of classifications (CLASSIFICATION output only)" }, "toolDefinitionIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Replacement set of scoped tool-definition ids (only for metrics whose tool scoping is editable)" }, "supportedContexts": { "type": "array", "items": { "type": "string", "enum": [ "CALL", "SEGMENT", "TURN" ] }, "minItems": 1, "description": "Replacement set of supported contexts. Omit to leave unchanged. Scope and participantRole cannot change after create, so moving to SEGMENT or TURN grading only works on a PER_PARTICIPANT metric (see create)." }, "formula": { "type": "string", "minLength": 1, "maxLength": 500, "description": "New formula expression (FORMULA only). Pass `sources` alongside if the referenced metrics change." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "sourceMetricDefinitionId": { "type": "string", "format": "uuid", "description": "ID of a metric referenced in the formula" }, "sourceVariantId": { "type": "string", "format": "uuid", "description": "Variant of the source metric to use" } }, "required": [ "sourceMetricDefinitionId" ] }, "description": "Replacement formula sources, required when `formula` changes the referenced metrics (FORMULA only)." }, "httpRequest": { "$ref": "#/components/schemas/HttpRequestMetricConfig", "description": "Replacement request (HTTP_REQUEST only). Send the whole request; omitted headers are removed." }, "changeReason": { "type": "string", "description": "Optional free-text audit note recorded on the new version." }, "slug": {}, "metricId": {}, "source": {}, "organizationId": {}, "projectId": {}, "outputType": {}, "scope": {}, "participantRole": {}, "calcType": {}, "supportsMultipleVariants": {}, "analysisPackageId": {} }, "description": "Editable subset of a metric definition. Every update creates a new immutable version. Immutable fields (slug, scope, outputType, calcType, …) are rejected with a 400." }, "MetricVariantListResponse": { "type": "array", "items": { "$ref": "#/components/schemas/MetricVariantResponse" } }, "MetricVariantResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the variant." }, "metricDefinitionId": { "type": "string", "format": "uuid", "description": "The metric this variant configures." }, "name": { "type": "string", "description": "Name of the variant. \"Default\" is the one a metric is scored with unless something pins another." }, "versionId": { "type": [ "string", "null" ], "format": "uuid", "description": "The variant's current version: an immutable snapshot of its configuration. Editing the variant advances this. Null only for a variant left without one, which cannot be scored until it is configured." }, "isSystem": { "type": "boolean", "description": "True for Roark's own variant, shared by every organization. Editing one forks it for yours; the original is left alone." }, "isDefault": { "type": "boolean", "description": "Whether this is the variant a metric is scored with when nothing pins another." }, "createdAt": { "type": "string", "description": "When the variant was created." }, "updatedAt": { "type": "string", "description": "When the variant was last changed." } }, "required": [ "id", "metricDefinitionId", "name", "versionId", "isSystem", "isDefault", "createdAt", "updatedAt" ], "description": "One named configuration of a metric." }, "CreateMetricVariantInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Name for the new variant. Must be unique for this metric within your organization and cannot be `Default`.", "example": "Strict" } }, "required": [ "name" ], "additionalProperties": false, "description": "Create a variant, seeded from the metric's Default configuration. Edit it afterwards with PUT to change what it measures.", "example": { "name": "Strict" } }, "UpdateMetricVariantInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Rename the variant. Does not change its configuration, so `versionId` is unaffected. `Default` is reserved." }, "llmPrompt": { "type": "string", "maxLength": 20000, "description": "The rubric this variant applies. LLM judge metrics only." }, "scaleMin": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Scale minimum. SCALE output only." }, "scaleMax": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Scale maximum. SCALE output only." }, "booleanTrueLabel": { "type": "string", "maxLength": 200, "description": "What a `true` value means. Given to the judge as its polarity rule, so keep it accurate." }, "booleanFalseLabel": { "type": "string", "maxLength": 200, "description": "What a `false` value means. Given to the judge as its polarity rule, so keep it accurate." }, "maxClassifications": { "type": "integer", "minimum": 1, "description": "Maximum classifications returned. CLASSIFICATION output only." }, "changeReason": { "type": "string", "maxLength": 500, "description": "Free-text audit note recorded on the new version." } }, "additionalProperties": false, "description": "Change a variant's name, its configuration, or both. Every configuration change creates a new immutable\nversion and advances `versionId`.\n\nEditing Roark's own variant forks it for your organization first: the response carries the new variant's id,\nand other organizations keep the original. Delete that variant to go back to Roark's version.", "example": { "llmPrompt": "Did the agent verify identity before disclosing anything? {{transcript}}" } }, "DeleteMetricVariantResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ] }, "GetMetricPoliciesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MetricPolicyResponse" } }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of items" }, "hasMore": { "type": "boolean", "description": "Whether there are more items to fetch" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page of items" } }, "required": [ "total", "hasMore", "nextCursor" ] } }, "required": [ "data", "pagination" ], "description": "Paginated list of metric policies" }, "MetricPolicyResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the metric policy" }, "name": { "type": "string", "description": "Name of the metric policy" }, "type": { "type": "string", "enum": [ "SYSTEM", "USER" ], "description": "Type of the metric policy (SYSTEM or USER)" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "description": "Status of the metric policy (ACTIVE or INACTIVE)" }, "conditions": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "conditions": { "type": "array", "items": { "type": "object", "properties": { "conditionType": { "type": "string", "enum": [ "AGENT", "CALL_SOURCE", "CALL_PROPERTY", "INTEGRATION" ], "description": "Type of condition: AGENT (match by agent ID), CALL_SOURCE (match by source e.g. VAPI, RETELL), CALL_PROPERTY (match by call property key/value)" }, "conditionKey": { "type": "string", "description": "Key to match against. For AGENT: the agent ID. For CALL_SOURCE: the source name. For CALL_PROPERTY: the property key." }, "conditionOperator": { "type": [ "string", "null" ], "enum": [ "EQUALS", "NOT_EQUALS", "CONTAINS", "STARTS_WITH", "GREATER_THAN", "LESS_THAN", "GREATER_THAN_OR_EQUALS", "LESS_THAN_OR_EQUALS" ], "description": "Comparison operator. Required for CALL_PROPERTY conditions." }, "conditionValue": { "type": [ "string", "null" ], "description": "Value to compare against. Required for CALL_PROPERTY conditions." } }, "required": [ "conditionType", "conditionKey", "conditionOperator", "conditionValue" ] } } }, "required": [ "conditions" ] }, "description": "Condition groups for this policy. Null means the policy matches all calls." }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "settings": { "oneOf": [ { "$ref": "#/components/schemas/PolicyMetricSettings" }, { "type": "null" } ], "description": "The metric's per-collector setting, or null when it runs with its default" } }, "required": [ "id", "settings" ] }, "description": "Metric definitions associated with this policy" }, "createdAt": { "type": "string", "description": "When the policy was created" }, "updatedAt": { "type": "string", "description": "When the policy was last updated" } }, "required": [ "id", "name", "type", "status", "conditions", "metrics", "createdAt", "updatedAt" ], "description": "A metric policy defining when metrics should be collected" }, "PolicyMetricSettings": { "type": "object", "properties": { "verifiedProperties": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 50, "description": "Property Verification metrics: the conversation properties to check against the transcript. Empty or omitted checks every custom property." }, "excludedPhrases": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 50, "description": "Voice consistency metrics: phrases whose agent lines are not judged, such as a recorded prompt in a different voice." }, "voicemailScript": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "Voicemail metrics: the message the agent is expected to leave on voicemail." }, "screeningBrief": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "Call screening metrics: what the agent should say when a screener asks who is calling and why." }, "toolDefinitionIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Tool invocation metrics: the tool definitions to score. Empty or omitted scores every tool the agent has." }, "knowledgeBaseDocumentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Knowledge grounding metrics: the knowledge base documents to ground against, in priority order. Empty or omitted uses every knowledge base in the project." } }, "additionalProperties": false, "description": "The metric's per-collector setting. A metric takes at most one field, and which one depends on the metric: verifiedProperties for Property Verification, excludedPhrases for voice consistency, voicemailScript for voicemail, screeningBrief for call screening, toolDefinitionIds for tool invocation, knowledgeBaseDocumentIds for knowledge grounding. A field the metric doesn't take is rejected with a 400." }, "CreateMetricPolicyInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Name of the metric policy", "example": "Evaluate all inbound calls" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "default": "ACTIVE", "description": "Status of the policy (default: ACTIVE)", "example": "ACTIVE" }, "modality": { "type": "string", "enum": [ "call", "chat" ], "description": "Modality this policy targets. A policy fires for exactly one modality and can only reference metrics that support that modality.", "example": "call" }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "conditions": { "type": "array", "items": { "type": "object", "properties": { "conditionType": { "type": "string", "enum": [ "AGENT", "CALL_SOURCE", "CALL_PROPERTY", "INTEGRATION" ], "description": "Type of condition: AGENT (match by agent ID), CALL_SOURCE (match by source e.g. VAPI, RETELL), CALL_PROPERTY (match by call property key/value)" }, "conditionKey": { "type": "string", "description": "Key to match against. For AGENT: the agent ID. For CALL_SOURCE: the source name. For CALL_PROPERTY: the property key." }, "conditionOperator": { "type": [ "string", "null" ], "enum": [ "EQUALS", "NOT_EQUALS", "CONTAINS", "STARTS_WITH", "GREATER_THAN", "LESS_THAN", "GREATER_THAN_OR_EQUALS", "LESS_THAN_OR_EQUALS" ], "description": "Comparison operator. Required for CALL_PROPERTY conditions." }, "conditionValue": { "type": [ "string", "null" ], "description": "Value to compare against. Required for CALL_PROPERTY conditions." } }, "required": [ "conditionType", "conditionKey" ] } } }, "required": [ "conditions" ] }, "description": "Condition groups. Omit to match all calls." }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The metric definition to collect" }, "settings": { "oneOf": [ { "$ref": "#/components/schemas/PolicyMetricSettings" }, { "type": "null" } ], "description": "Optional. Omit, or send null, to collect the metric with its default (every property, every tool, no excluded phrases). Null is what a read returns for a metric on its default, so a fetched metrics list can be sent back as is." } }, "required": [ "id" ] }, "minItems": 1, "description": "Metric definitions to collect when this policy matches, each with an optional setting" } }, "required": [ "name", "modality", "metrics" ], "description": "Input for creating a new metric policy" }, "UpdateMetricPolicyInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Name of the metric policy" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "description": "Status of the policy" }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "conditions": { "type": "array", "items": { "type": "object", "properties": { "conditionType": { "type": "string", "enum": [ "AGENT", "CALL_SOURCE", "CALL_PROPERTY", "INTEGRATION" ], "description": "Type of condition: AGENT (match by agent ID), CALL_SOURCE (match by source e.g. VAPI, RETELL), CALL_PROPERTY (match by call property key/value)" }, "conditionKey": { "type": "string", "description": "Key to match against. For AGENT: the agent ID. For CALL_SOURCE: the source name. For CALL_PROPERTY: the property key." }, "conditionOperator": { "type": [ "string", "null" ], "enum": [ "EQUALS", "NOT_EQUALS", "CONTAINS", "STARTS_WITH", "GREATER_THAN", "LESS_THAN", "GREATER_THAN_OR_EQUALS", "LESS_THAN_OR_EQUALS" ], "description": "Comparison operator. Required for CALL_PROPERTY conditions." }, "conditionValue": { "type": [ "string", "null" ], "description": "Value to compare against. Required for CALL_PROPERTY conditions." } }, "required": [ "conditionType", "conditionKey" ] } } }, "required": [ "conditions" ] }, "description": "Condition groups. Omit to keep existing, provide empty array to remove all conditions." }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The metric definition to collect" }, "settings": { "oneOf": [ { "$ref": "#/components/schemas/PolicyMetricSettings" }, { "type": "null" } ], "description": "Optional. Omit, or send null, to collect the metric with its default (every property, every tool, no excluded phrases). Null is what a read returns for a metric on its default, so a fetched metrics list can be sent back as is." } }, "required": [ "id" ] }, "minItems": 1, "description": "Metric definitions to collect when this policy matches. Replaces the policy's whole metric list: a metric sent without settings goes back to its default, so resend a metric's settings to keep them. Omit to keep the current metrics." } }, "description": "Input for updating an existing metric policy" }, "GetMetricCollectionJobsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MetricCollectionJobResponse" } }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of items" }, "hasMore": { "type": "boolean", "description": "Whether there are more items to fetch" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page of items" } }, "required": [ "total", "hasMore", "nextCursor" ] } }, "required": [ "data", "pagination" ], "description": "Paginated list of metric collection jobs" }, "CreateMetricCollectionJobInput": { "type": "object", "properties": { "callIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 500, "description": "Call IDs to collect metrics for. Mutually exclusive with chatIds. Max 500 per request." }, "chatIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 500, "description": "Chat IDs to collect metrics for. Mutually exclusive with callIds. Max 500 per request." }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "minItems": 1, "maxItems": 20, "description": "Metric definitions to collect. Max 20 per request. Required unless policyId is given; with policyId, defaults to every metric that policy collects, and each one listed must be in it." }, "policyId": { "type": "string", "format": "uuid", "description": "Optional. A metric policy (collector) whose settings to score with: each metric runs at the version that policy runs it at, with its per-collector setting (such as the properties Property Verification checks), instead of the metric's default. A metric the policy runs at its default runs at its default here too. The policy's conditions are not applied: the listed conversations are scored as given. Use it to re-score past conversations after changing a policy's settings." } }, "description": "Input for creating and running a metric collection job. Limits: ≤500 conversations, ≤20 metrics, ≤5000 total items per request." }, "MetricCollectionJobMetricValuesResponse": { "type": "array", "items": { "type": "object", "properties": { "metricDefinitionId": { "type": "string", "format": "uuid", "description": "Unique identifier for the metric definition" }, "slug": { "type": "string", "description": "Stable metric slug" }, "metricId": { "type": "string", "description": "Alias of `slug` retained for backwards compatibility. Same value as `slug`." }, "name": { "type": "string", "description": "Name of the metric" }, "description": { "type": "string", "description": "Description of what the metric measures" }, "type": { "type": "string", "enum": [ "COUNT", "NUMERIC", "BOOLEAN", "SCALE", "TEXT", "CLASSIFICATION", "OFFSET" ], "description": "Type of value this metric produces" }, "scope": { "type": "string", "enum": [ "GLOBAL", "PER_PARTICIPANT" ], "description": "Whether metric is global or per-participant" }, "unit": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the unit" }, "symbol": { "type": [ "string", "null" ], "description": "Symbol for the unit" } }, "required": [ "name", "symbol" ], "description": "Unit information if applicable" }, "values": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "boolean" }, { "type": "string" } ], "description": "The metric value (type depends on outputType). Present only on SUCCESS rows; omitted for NOT_APPLICABLE / DATA_MISSING / ERROR." }, "callId": { "type": "string", "format": "uuid", "description": "ID of the call this value was computed on. Only set when the response spans multiple conversations (e.g. job-scoped metric values)." }, "chatId": { "type": "string", "format": "uuid", "description": "ID of the chat this value was computed on. Only set when the response spans multiple conversations (e.g. job-scoped metric values)." }, "captureStatus": { "type": "string", "enum": [ "SUCCESS", "NOT_APPLICABLE", "DATA_MISSING", "ERROR" ], "description": "Result state of this metric computation. SUCCESS carries a real `value`; NOT_APPLICABLE / DATA_MISSING / ERROR do not (the `value` field is omitted). Non-SUCCESS rows only appear when the request includes ?status=all." }, "errorMessage": { "type": "string", "description": "Error detail when captureStatus is ERROR — e.g. provider down, LLM timeout. Undefined for other statuses." }, "context": { "type": "string", "enum": [ "CALL", "SEGMENT", "SEGMENT_RANGE" ], "description": "Context level: CALL (entire conversation), SEGMENT (single segment), SEGMENT_RANGE (between/across segments)" }, "participantRole": { "type": "string", "enum": [ "agent", "customer" ], "description": "Role of participant (only for PER_PARTICIPANT metrics)" }, "valueReasoning": { "type": "string", "description": "Explanation for the metric value (especially useful for AI-computed metrics)" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Confidence score (0-1) for the computed value. Defaults to 1.0 for deterministic metrics. Omitted on non-SUCCESS rows." }, "computedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the metric was computed" }, "policyIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs of metric policies that triggered this metric computation" }, "segment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Segment information (for SEGMENT context metrics)" }, "fromSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Starting segment information (for SEGMENT_RANGE context metrics)" }, "toSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Ending segment information (for SEGMENT_RANGE context metrics)" }, "evidenceSpans": { "type": "array", "items": { "type": "object", "properties": { "fromSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "First segment of the span" }, "toSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Last segment of the span (the same as fromSegment for one line)" }, "reason": { "type": "string", "description": "The judge's one-line account of what happens here" } }, "required": [ "fromSegment", "toSegment" ] }, "description": "For CALL-context values of LLM judge metrics that cited where their evidence is: the transcript spans that decided the value, most decisive first. Omitted otherwise." } }, "required": [ "captureStatus", "context", "computedAt" ], "title": "Standard metric value", "description": "A metric value entry. Applies to every metric." }, { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "boolean" }, { "type": "string" } ], "description": "The metric value (type depends on outputType). Present only on SUCCESS rows; omitted for NOT_APPLICABLE / DATA_MISSING / ERROR." }, "callId": { "type": "string", "format": "uuid", "description": "ID of the call this value was computed on. Only set when the response spans multiple conversations (e.g. job-scoped metric values)." }, "chatId": { "type": "string", "format": "uuid", "description": "ID of the chat this value was computed on. Only set when the response spans multiple conversations (e.g. job-scoped metric values)." }, "captureStatus": { "type": "string", "enum": [ "SUCCESS", "NOT_APPLICABLE", "DATA_MISSING", "ERROR" ], "description": "Result state of this metric computation. SUCCESS carries a real `value`; NOT_APPLICABLE / DATA_MISSING / ERROR do not (the `value` field is omitted). Non-SUCCESS rows only appear when the request includes ?status=all." }, "errorMessage": { "type": "string", "description": "Error detail when captureStatus is ERROR — e.g. provider down, LLM timeout. Undefined for other statuses." }, "context": { "type": "string", "enum": [ "CALL", "SEGMENT", "SEGMENT_RANGE" ], "description": "Context level: CALL (entire conversation), SEGMENT (single segment), SEGMENT_RANGE (between/across segments)" }, "participantRole": { "type": "string", "enum": [ "agent", "customer" ], "description": "Role of participant (only for PER_PARTICIPANT metrics)" }, "valueReasoning": { "type": "string", "description": "Explanation for the metric value (especially useful for AI-computed metrics)" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Confidence score (0-1) for the computed value. Defaults to 1.0 for deterministic metrics. Omitted on non-SUCCESS rows." }, "computedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the metric was computed" }, "policyIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs of metric policies that triggered this metric computation" }, "segment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Segment information (for SEGMENT context metrics)" }, "fromSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Starting segment information (for SEGMENT_RANGE context metrics)" }, "toSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Ending segment information (for SEGMENT_RANGE context metrics)" }, "evidenceSpans": { "type": "array", "items": { "type": "object", "properties": { "fromSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "First segment of the span" }, "toSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Last segment of the span (the same as fromSegment for one line)" }, "reason": { "type": "string", "description": "The judge's one-line account of what happens here" } }, "required": [ "fromSegment", "toSegment" ] }, "description": "For CALL-context values of LLM judge metrics that cited where their evidence is: the transcript spans that decided the value, most decisive first. Omitted otherwise." }, "propertyVerdicts": { "type": "array", "items": { "type": "object", "properties": { "propertyName": { "type": "string", "description": "The call property checked, as sent at ingest" }, "expectedValue": { "type": "string", "description": "The value supplied at ingest, frozen at scoring time" }, "observedValue": { "type": "string", "description": "What the transcript said instead. Only present when verdict is MISMATCH." }, "verdict": { "type": "string", "enum": [ "MATCH", "MISMATCH", "TRANSCRIPTION_ERROR", "NOT_MENTIONED" ], "description": "How this property resolved against the transcript. NOT_MENTIONED means the subject never came up and is not a mismatch." }, "reasoning": { "type": "string", "description": "Judge reasoning for this verdict" }, "segment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "The transcript segment this property was referred to in: the conflicting value for MISMATCH, the confirming reference for MATCH. Omitted for NOT_MENTIONED and when the verdict could not be anchored." } }, "required": [ "propertyName", "expectedValue", "verdict" ] }, "description": "Per-property verdicts for the Property Mismatch metric, in the order the properties were checked. Omitted for every other metric." } }, "required": [ "captureStatus", "context", "computedAt" ], "title": "Property verification metric value", "description": "Returned for the Property Mismatch metric (`property_transcript_mismatch`): the standard entry plus the per-property verdict breakdown." } ] }, "description": "Array of metric values (multiple for PER_PARTICIPANT metrics, or multiple segments/turns)" } }, "required": [ "metricDefinitionId", "slug", "metricId", "name", "description", "type", "scope", "values" ], "description": "Metric data grouped by metric definition" }, "description": "Metric values produced by a specific metric collection job. Grouped by metric definition, same shape as the per-call metrics endpoint." }, "RunSimulationResponse": { "type": "object", "properties": { "simulationRunPlanJobId": { "type": "string", "format": "uuid", "description": "The run. Poll it with GET /v1/simulation/plan/job/{jobId}." }, "status": { "type": "string", "enum": [ "PENDING", "QUEUED", "CREATING_SNAPSHOTS", "CREATING_SIMULATIONS", "PREPARING_CAPACITY", "RUNNING_SIMULATIONS", "COMPLETED", "FAILED", "TIMED_OUT", "CANCELLED", "CANCELLING", "ENDING_SIMULATIONS" ], "description": "Initial status. PENDING normally, or QUEUED when the plan runs sequentially and another job of its is still active." }, "createdAt": { "type": "string", "description": "When the run was created, ISO 8601." }, "simulationRunPlanId": { "type": "string", "format": "uuid", "description": "The run plan behind this run, present whether or not it was saved. Pass it back as `planId` to run the same configuration again." }, "savedAsPlan": { "type": "boolean", "description": "Whether that plan is listed by GET /v1/simulation/plan. False for an unsaved run, whose plan is hidden." }, "simulationJobCount": { "type": "integer", "description": "How many simulated calls this run places." } }, "required": [ "simulationRunPlanJobId", "status", "createdAt", "simulationRunPlanId", "savedAsPlan", "simulationJobCount" ], "description": "A started simulation run." }, "RunSimulationInput": { "oneOf": [ { "$ref": "#/components/schemas/RunSimulationFromConfig" }, { "$ref": "#/components/schemas/RunSimulationFromPlanId" }, { "$ref": "#/components/schemas/RunSimulationFromConfigKey" }, { "$ref": "#/components/schemas/RunSimulationFromTemplate" } ], "description": "A built-in template to run, a simulation to configure and run, or the id of a plan to run." }, "RunSimulationFromConfig": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/InlineRunPlanConfig" }, "saveAsPlan": { "type": "boolean", "description": "Keeps this configuration as a run plan, listed by GET /v1/simulation/plan and re-runnable\nwith `planId`. Requires `plan.name`, since a plan you meant to keep should not be filed\nunder a generated one.\n\nOmitted or false gives a one-off. The run still needs a plan to execute, so one is created\neither way, but it is hidden: it carries this run and nothing else." }, "variables": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" }, "description": "Global format: key-value pairs that apply to ALL scenarios in the plan", "example": { "orderNumber": "12345", "environment": "staging" } }, { "type": "array", "items": { "type": "object", "properties": { "flowId": { "type": "string", "format": "uuid", "description": "A customer flow this plan runs." }, "happyPath": { "type": "boolean", "const": true, "description": "Narrow to the flow's happy path." }, "edgeCaseId": { "type": "string", "format": "uuid", "description": "Narrow to one edge case of that flow." }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The values to apply." } }, "required": [ "flowId", "variables" ] }, "description": "Values scoped to the flows this plan runs", "example": [ { "flowId": "550e8400-e29b-41d4-a716-446655440000", "variables": { "orderNumber": "12345" } }, { "flowId": "550e8400-e29b-41d4-a716-446655440000", "happyPath": true, "variables": { "orderNumber": "55555" } }, { "flowId": "550e8400-e29b-41d4-a716-446655440000", "edgeCaseId": "7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e", "variables": { "orderNumber": "67890" } } ] }, { "type": "array", "items": { "type": "object", "properties": { "scenarioId": { "type": "string", "format": "uuid", "description": "ID of the scenario to apply variables to" }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Key-value pairs for this scenario" } }, "required": [ "scenarioId", "variables" ] }, "deprecated": true, "description": "Deprecated, for plans built on scenarios. Plans built on customer flows target them with `flowId` instead.", "example": [ { "scenarioId": "550e8400-e29b-41d4-a716-446655440000", "variables": { "orderNumber": "12345" } }, { "scenarioId": "7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e", "variables": { "orderNumber": "67890" } } ] } ], "description": "Values for the {{variables}} the run resolves, overriding whatever the plan has pinned.\n\nAn object applies them to the whole run:\n\n { \"orderNumber\": \"12345\", \"tier\": \"gold\" }\n\nAn array applies them per flow, or to just its happy path or one of its edge cases, when a single\nset will not do. Each entry carries what it applies to:\n\n [\n { \"flowId\": \"550e8400-...\", \"variables\": { \"orderNumber\": \"12345\" } },\n { \"flowId\": \"550e8400-...\", \"happyPath\": true, \"variables\": { \"orderNumber\": \"55555\" } },\n { \"flowId\": \"550e8400-...\", \"edgeCaseId\": \"7a3d2e1f-...\", \"variables\": { \"orderNumber\": \"67890\" } }\n ]\n\nAn entry that narrows to neither covers everything that flow resolves. A flow this plan does not\nattach, or an edge case that does not belong to the flow, is rejected rather than ignored.\n\nA plan built on scenarios rather than customer flows targets them the same way, with `scenarioId` in\nplace of `flowId`. That form is deprecated alongside scenarios themselves, and still accepted so runs\nagainst those plans keep working." } }, "required": [ "plan" ], "additionalProperties": false, "title": "New simulation", "description": "Describe a simulation and run it, optionally keeping the configuration as a reusable plan.", "example": { "saveAsPlan": true, "plan": { "name": "Billing regression", "direction": "OUTBOUND", "maxSimulationDurationSeconds": 300, "agentEndpoints": [ { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } ], "metrics": [ { "slug": "customer_satisfaction" } ], "flows": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "happyPath": true, "edgeCases": "ALL" } ] }, "variables": { "orderNumber": "12345" } } }, "InlineRunPlanConfig": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "What to call this. Generated from the date when omitted, and required with `saveAsPlan`.", "example": "Billing regression" }, "description": { "type": "string", "description": "Description of the run plan", "example": "A run plan for testing inbound calls" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direction of the simulation (INBOUND or OUTBOUND)", "example": "INBOUND" }, "iterationCount": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1, "description": "Number of iterations to run for each test case (1-10000)", "example": 1 }, "maxConcurrentJobs": { "type": "integer", "minimum": 1, "default": 5, "description": "Maximum number of concurrent simulation jobs", "example": 5 }, "maxSimulationDurationSeconds": { "type": "integer", "minimum": 1, "description": "Maximum duration in seconds for each simulation", "example": 300 }, "silenceTimeoutSeconds": { "type": "integer", "minimum": 1, "default": 30, "description": "Timeout in seconds for silence detection", "example": 30 }, "maxNoResponseRetries": { "type": "integer", "minimum": 0, "maximum": 10, "default": 0, "description": "How many more times to run a test case when the agent under test never responds: it never speaks on a call or never replies in a chat (0-10). 0 turns retries off. Failed checks and failures on Roark’s side are never retried.\n\nEach retry is a separate attempt, billed like any other, so a plan retrying N times can place up to N + 1 calls per test case.\nEvery silent attempt stays on the run with its own call; the run settles once each test case has a final attempt, and the\nagent never spoke verdict is judged on each test case’s last attempt.", "example": 2 }, "noResponseRetryBackoffSeconds": { "type": "integer", "minimum": 30, "maximum": 600, "default": 90, "description": "Seconds a retry waits before it dials (30-600). Only used when `maxNoResponseRetries` is above 0.", "example": 90 }, "endCallPhrases": { "type": "array", "items": { "type": "string" }, "default": [ "goodbye" ], "description": "Phrases that trigger end of call. Empty array disables the feature.", "example": [ "goodbye" ] }, "endCallReasons": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Semantic conditions that trigger end of call. The LLM evaluates the conversation against these conditions. Empty array disables the feature.", "example": [ "Order has been confirmed by the agent" ] }, "executionMode": { "type": "string", "enum": [ "PARALLEL", "SEQUENTIAL_SAME_RUN_PLAN", "SEQUENTIAL_PROJECT" ], "default": "PARALLEL", "description": "Execution mode (PARALLEL or SEQUENTIAL)", "example": "PARALLEL" }, "scenarios": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Scenario ID" }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Template variables for this scenario instance. The same scenario can appear multiple times with different variables.", "example": { "customerName": "John Doe", "appointmentDate": "2024-02-15" } } }, "required": [ "id" ] }, "minItems": 1, "deprecated": true, "description": "Deprecated: use `flows` instead. Scenarios to include in this run plan. The same scenario ID can appear multiple times with different variables." }, "flows": { "type": "array", "items": { "$ref": "#/components/schemas/RunPlanFlowSelection" }, "minItems": 1, "description": "Customer flows to include in this run plan. The same flow can appear more than once with a different persona override, different variables, or different `overrides`: attaching it once per value of one property is how you compare that property without a template." }, "personas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "minItems": 1, "description": "Personas to include in this run plan. Required with `scenarios`; ignored with `flows`, where each variant carries its own persona." }, "agentEndpoints": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "minItems": 1, "description": "Agent endpoints to include in this run plan" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/RunPlanMetricRef" }, "minItems": 1, "description": "Metric definitions to include in this run plan. Reference each by `id` (UUID) or `slug`.\n\nOptional when the attached `flows` carry the grading: metrics a flow declares itself\n(with `includeFlowMetrics`), or the Agent Expectations and Keypad Entry metrics a run\nadds for flows with expectations or expected keypad entries (with\n`includeAutomaticMetrics`). A plan with nothing to grade is rejected with a 400." }, "includeFlowMetrics": { "type": "boolean", "default": true, "description": "Also collect each attached flow's own metrics, on top of the `metrics` named here.\n\nDefault true, which is what you want when you brought your own flows and their graders.\nSet false for a run whose metric list is meant to be exhaustive: a template like Load\nTesting or Voicemail deliberately grades a narrow set, and inheriting every flow metric\non top multiplies analysis cost across the volume without adding signal.\n\nGET /v1/simulation/template returns the value each template expects.", "example": true }, "includeAutomaticMetrics": { "type": "boolean", "default": true, "description": "Let the run add metrics by itself off the attached flows, on top of the `metrics` named here.\n\nTwo attach this way today: Agent Expectations wherever an attached flow has agent expectations\nwritten on it, and Keypad Entry wherever one has steps where the agent is expected to press keys.\nBoth grade something authored on the flow that nothing else measures, which is why it is on by\ndefault.\n\nSet false when the `metrics` list is meant to be exhaustive: a plan testing only whether the caller\ncan complete the flow may not want the agent graded on its expectations as well. False also pins\nthe plan against any automatic metric Roark adds later.", "example": true }, "comparisonProperty": { "type": [ "string", "null" ], "enum": [ "ACCENT", "AGE", "BACKGROUND_NOISE", "BACKGROUND_NOISE_VOLUME", "BASE_EMOTION", "CONFIRMATION_STYLE", "GENDER", "INTENT_CLARITY", "LANGUAGE", "INTERRUPTION", "MEMORY_RELIABILITY", "RESPONSE_TIMING", "SPEECH_CLARITY", "SPEECH_PACE" ], "description": "The property this run plan investigates: the one thing its arms differ by.\n\nSet it and the run report compares the arms on that property, so a run answers \"what did\nbackground noise cost\" rather than just \"what did each arm score\". Every value is a field\nalready recorded on each call, so the report can label an arm `CRYING_BABY` rather than\nrepeating a flow variant's title.\n\nOmit it and the report still compares when it can: it detects which property varies across\nthe arms. Setting it is what tells the written summary what you were trying to find out,\nwhich detection cannot infer.", "example": "BACKGROUND_NOISE" }, "comparisonBaseline": { "type": [ "string", "null" ], "description": "The reference value of `comparisonProperty`, for example `NONE` for `BACKGROUND_NOISE` or\n`NORMAL` for `SPEECH_PACE`: shown first in the results. Must be a value that property can take.\nWhether a value did significantly worse does not depend on it: that is decided against every\nother value combined (see `sweepAttribution`).\n\nStored rather than assumed, so the report can say \"compared against US accent\" instead of\nimplying Roark decided which value is normal. Omit it and the property's own norm is used,\nas the dashboard prefills it, or none when your `comparisonValues` leave the norm out.\n`GENDER` has no norm, so choose the one you are testing against.", "example": "NONE" }, "comparisonValues": { "type": "array", "items": { "anyOf": [ { "type": "string", "minLength": 1, "description": "A value of `comparisonProperty`, run as its plain arm." }, { "$ref": "#/components/schemas/ComparisonArm" } ] }, "minItems": 1, "description": "The arms to run, for a plan that sweeps `comparisonProperty`. This is what the plan costs: the\nflow is attached once per arm, so ten arms is ten times the calls of one.\n\nAttach each flow once, as you would without a comparison: the plan builds the arms, running\nthe happy path or edge cases you selected under every arm. Built arms need at least 5 calls\nper arm (`iterationCount` times the test cases per arm), or the plan is refused with `400`.\nFlows that all carry `overrides` on `comparisonProperty` already are the arms and are kept as\nyou wrote them; a mix of flows with and without one is refused.\n\nEach entry is one arm. A bare value runs it plain: `\"CITY\"`. An object runs the value with\nsomething pinned on that arm only, such as a noise level per bed: `{ \"value\": \"OFFICE\",\n\"backgroundNoiseVolume\": 0.6 }` plays OFFICE at 60% while the other beds keep the default.\nList a value more than once with different pins to run it as several arms: DRIVING at 0.7 and\nDRIVING at 1 are two arms, reported as `Driving (70% noise)` and `Driving (100% noise)`, and\n`\"DRIVING\"` beside them keeps the plain arm too. The sweep still varies one property; what an\narm pins is part of \"everything else\" for that arm only, so the report still compares the arms\non `comparisonProperty`.\n\nOmit it to run every value the property has, plain, which for `ACCENT` is more than twenty.\nA `comparisonBaseline` outside the values listed is rejected, because it would anchor every\ndifference to an arm the run never made. A value the property cannot take, a pin the sweep\ncannot account for, or the same arm listed twice is rejected with `400`.\n\nNot stored as a field: the arms are the values. Reading the plan back returns them as its\nflow attachments, each with its pins as `overrides`.", "example": [ "NONE", { "value": "OFFICE", "backgroundNoiseVolume": 0.6 }, { "value": "DRIVING", "backgroundNoiseVolume": 0.7 }, { "value": "DRIVING", "backgroundNoiseVolume": 1 } ] }, "enrichWithLiveConversation": { "type": "boolean", "default": false, "description": "Merge the customer's own recording of the real call into each simulation, so metrics can be\nscored against the live leg as well as the simulated one. This is the API equivalent of the\ndashboard's live-enrichment toggle.\n\nWith this on, the run provisions a phone number and holds each call open for up to 15 minutes\nwaiting for a matching call to be posted to POST /v1/call. A call matches on the provisioned\nnumber (`roarkPhoneNumber` on the job) with a start time inside the simulation window. If\nnothing arrives, the simulation still completes and any `LIVE`-sourced metric produces no value.\n\nRequired by any metric whose `requiresLiveConversation` is true: without it that metric is\nsilently skipped.", "example": false } }, "required": [ "direction", "maxSimulationDurationSeconds", "agentEndpoints" ], "additionalProperties": false, "description": "The simulation to run: what to call, who calls it, and what to measure." }, "RunPlanFlowSelection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The customer flow to run." }, "slug": { "type": "string", "minLength": 1, "description": "The Roark-curated flow to run, by its stable slug. Use instead of `id` for a run you keep in version control: a curated flow’s id differs between deployments, its slug does not. Your own flows have no slug and are named by `id`.", "example": "sf-prompt-injection" }, "happyPath": { "type": "boolean", "description": "Run the flow's happy path. Resolved when the run starts, so it follows the flow." }, "edgeCases": { "anyOf": [ { "type": "string", "const": "ALL" }, { "type": "array", "items": { "$ref": "#/components/schemas/RunPlanEdgeCaseSelection" } } ], "description": "`\"ALL\"` runs every edge case the flow has when the run starts, so one added later is covered.\nAn array runs only the ones you name, each able to carry its own persona override and values." }, "personaOverrideId": { "type": [ "string", "null" ], "format": "uuid", "description": "Runs everything this attachment resolves as that persona instead of its own." }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Values for everything it resolves.", "example": { "customerName": "John Doe", "appointmentDate": "2024-02-15" } }, "overrides": { "type": "array", "items": { "$ref": "#/components/schemas/RunPlanFlowOverride" }, "description": "Persona and environment properties to change for this attachment only, without editing the\npersona or the environment themselves. Each entry patches the per-run snapshot this\nattachment records, so the flow runs as a caller with that accent, or over that background\nnoise, and everything else stays as authored.\n\nThis is how you attach the same flow twice and vary one thing between them, which is what a\nsweep template builds for you. One value per property; a property named twice is rejected.", "example": [ { "property": "ACCENT", "value": "IN" }, { "property": "BACKGROUND_NOISE", "value": "TRAIN" } ] } }, "description": "One customer flow attached to a run plan, and which of its ways of running you cover.\n\nAttaching the same flow more than once with different overrides is how you fan it out across\npersonas or values.", "example": { "id": "550e8400-e29b-41d4-a716-446655440000", "happyPath": true, "edgeCases": [ { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "variables": { "tier": "premium" } } ] } }, "RunPlanEdgeCaseSelection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The edge case to run." }, "slug": { "type": "string", "minLength": 1, "description": "The edge case to run, by its stable slug, matched within this flow. Use instead of `id` for a run you keep in version control: a curated edge case’s id differs between deployments and changes outright if it is renamed. Your own edge cases have no slug and are named by `id`.", "example": "data-embedded-injection" }, "personaOverrideId": { "type": [ "string", "null" ], "format": "uuid", "description": "Run this one as that persona instead of its own." }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Values for this one only.", "example": { "customerName": "John Doe", "appointmentDate": "2024-02-15" } } } }, "RunPlanFlowOverride": { "type": "object", "properties": { "property": { "type": "string", "enum": [ "ACCENT", "AGE", "BACKGROUND_NOISE", "BACKGROUND_NOISE_VOLUME", "BASE_EMOTION", "CONFIRMATION_STYLE", "GENDER", "INTENT_CLARITY", "LANGUAGE", "INTERRUPTION", "MEMORY_RELIABILITY", "RESPONSE_TIMING", "SPEECH_CLARITY", "SPEECH_PACE" ] }, "value": { "type": "string", "minLength": 1 } }, "required": [ "property", "value" ], "description": "One persona or environment property, changed for this flow attachment only." }, "RunPlanMetricRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Metric definition UUID. Provide either this or `slug`, not both." }, "slug": { "type": "string", "minLength": 1, "description": "Stable metric slug (e.g. `customer_satisfaction`). Provide either this or `id`, not both." }, "metricId": { "type": "string", "minLength": 1, "description": "Alias of `slug` accepted for backwards compatibility. Use `slug` for new integrations." }, "conversationSource": { "type": [ "string", "null" ], "enum": [ "SIMULATED", "LIVE" ], "description": "Which side of an enriched run this metric is scored on. Only meaningful with\n`enrichWithLiveConversation: true`, where a run has both a simulated conversation and the\ncustomer's own live recording of it.\n\nDefaults to `SIMULATED`. Use `LIVE` for a metric that must be measured against the real\nrecording (audio quality, provider latency) rather than the simulated leg. `null` means the\nsame as omitting it, so a plan read back from GET can be sent straight to PUT." }, "minPassRate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "THE BAR, and the only thing that decides pass/fail. The share of the run's simulations\nthat must pass this check, 0-100.\n\nApplied to this check alone and never pooled: silence duration at 40 and word count at 80\nmeans the run fails unless 40% of sims clear silence AND 80% clear word count. Omit or\n`null` for the 80% default.", "example": 80 } }, "additionalProperties": false }, "ComparisonArm": { "type": "object", "properties": { "backgroundNoiseVolume": { "type": "number", "minimum": 0, "maximum": 1, "description": "The noise level this arm plays at, 0 to 1. The environment default is 0.1. Only a `BACKGROUND_NOISE` sweep may pin it.", "example": 0.6 }, "value": { "type": "string", "minLength": 1, "description": "The swept value this arm runs, a value of `comparisonProperty`.", "example": "OFFICE" } }, "required": [ "value" ], "additionalProperties": false, "description": "One arm of a sweep: the swept value it runs, and what it pins besides that value. The OFFICE\narm of a BACKGROUND_NOISE sweep playing at 60% while the other beds keep their level is\n`{ \"value\": \"OFFICE\", \"backgroundNoiseVolume\": 0.6 }`. The report compares the arms on the\nswept property only, so each sweep may pin just what its experiment calls for: a BACKGROUND_NOISE\nsweep may pin `backgroundNoiseVolume`, and no other sweep pins anything yet. A pin the sweep\ncannot account for is rejected with `400`." }, "RunSimulationFromPlanId": { "type": "object", "properties": { "planId": { "type": "string", "format": "uuid", "description": "The run plan to run, saved or hidden. Rename or unhide it with PUT /v1/simulation/plan/{planId}." }, "variables": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" }, "description": "Global format: key-value pairs that apply to ALL scenarios in the plan", "example": { "orderNumber": "12345", "environment": "staging" } }, { "type": "array", "items": { "type": "object", "properties": { "flowId": { "type": "string", "format": "uuid", "description": "A customer flow this plan runs." }, "happyPath": { "type": "boolean", "const": true, "description": "Narrow to the flow's happy path." }, "edgeCaseId": { "type": "string", "format": "uuid", "description": "Narrow to one edge case of that flow." }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The values to apply." } }, "required": [ "flowId", "variables" ] }, "description": "Values scoped to the flows this plan runs", "example": [ { "flowId": "550e8400-e29b-41d4-a716-446655440000", "variables": { "orderNumber": "12345" } }, { "flowId": "550e8400-e29b-41d4-a716-446655440000", "happyPath": true, "variables": { "orderNumber": "55555" } }, { "flowId": "550e8400-e29b-41d4-a716-446655440000", "edgeCaseId": "7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e", "variables": { "orderNumber": "67890" } } ] }, { "type": "array", "items": { "type": "object", "properties": { "scenarioId": { "type": "string", "format": "uuid", "description": "ID of the scenario to apply variables to" }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Key-value pairs for this scenario" } }, "required": [ "scenarioId", "variables" ] }, "deprecated": true, "description": "Deprecated, for plans built on scenarios. Plans built on customer flows target them with `flowId` instead.", "example": [ { "scenarioId": "550e8400-e29b-41d4-a716-446655440000", "variables": { "orderNumber": "12345" } }, { "scenarioId": "7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e", "variables": { "orderNumber": "67890" } } ] } ], "description": "Values for the {{variables}} the run resolves, overriding whatever the plan has pinned.\n\nAn object applies them to the whole run:\n\n { \"orderNumber\": \"12345\", \"tier\": \"gold\" }\n\nAn array applies them per flow, or to just its happy path or one of its edge cases, when a single\nset will not do. Each entry carries what it applies to:\n\n [\n { \"flowId\": \"550e8400-...\", \"variables\": { \"orderNumber\": \"12345\" } },\n { \"flowId\": \"550e8400-...\", \"happyPath\": true, \"variables\": { \"orderNumber\": \"55555\" } },\n { \"flowId\": \"550e8400-...\", \"edgeCaseId\": \"7a3d2e1f-...\", \"variables\": { \"orderNumber\": \"67890\" } }\n ]\n\nAn entry that narrows to neither covers everything that flow resolves. A flow this plan does not\nattach, or an edge case that does not belong to the flow, is rejected rather than ignored.\n\nA plan built on scenarios rather than customer flows targets them the same way, with `scenarioId` in\nplace of `flowId`. That form is deprecated alongside scenarios themselves, and still accepted so runs\nagainst those plans keep working." } }, "required": [ "planId" ], "additionalProperties": false, "title": "Existing plan", "description": "Run a plan that already exists.", "example": { "planId": "3a1d5e7c-9b2f-4a6d-8c31-5f7e9d0a2b4c", "variables": { "orderNumber": "99887" } } }, "RunSimulationFromConfigKey": { "type": "object", "properties": { "planConfigKey": { "type": "string", "pattern": "^simulationPlan\\/.+", "description": "The config key of a plan to run, as applied from config as code (`simulationPlan/`). Runs a config-managed plan by name, with no id lookup. Unique per project.", "example": "simulationPlan/nightly-screener-suite" }, "variables": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" }, "description": "Global format: key-value pairs that apply to ALL scenarios in the plan", "example": { "orderNumber": "12345", "environment": "staging" } }, { "type": "array", "items": { "type": "object", "properties": { "flowId": { "type": "string", "format": "uuid", "description": "A customer flow this plan runs." }, "happyPath": { "type": "boolean", "const": true, "description": "Narrow to the flow's happy path." }, "edgeCaseId": { "type": "string", "format": "uuid", "description": "Narrow to one edge case of that flow." }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The values to apply." } }, "required": [ "flowId", "variables" ] }, "description": "Values scoped to the flows this plan runs", "example": [ { "flowId": "550e8400-e29b-41d4-a716-446655440000", "variables": { "orderNumber": "12345" } }, { "flowId": "550e8400-e29b-41d4-a716-446655440000", "happyPath": true, "variables": { "orderNumber": "55555" } }, { "flowId": "550e8400-e29b-41d4-a716-446655440000", "edgeCaseId": "7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e", "variables": { "orderNumber": "67890" } } ] }, { "type": "array", "items": { "type": "object", "properties": { "scenarioId": { "type": "string", "format": "uuid", "description": "ID of the scenario to apply variables to" }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Key-value pairs for this scenario" } }, "required": [ "scenarioId", "variables" ] }, "deprecated": true, "description": "Deprecated, for plans built on scenarios. Plans built on customer flows target them with `flowId` instead.", "example": [ { "scenarioId": "550e8400-e29b-41d4-a716-446655440000", "variables": { "orderNumber": "12345" } }, { "scenarioId": "7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e", "variables": { "orderNumber": "67890" } } ] } ], "description": "Values for the {{variables}} the run resolves, overriding whatever the plan has pinned.\n\nAn object applies them to the whole run:\n\n { \"orderNumber\": \"12345\", \"tier\": \"gold\" }\n\nAn array applies them per flow, or to just its happy path or one of its edge cases, when a single\nset will not do. Each entry carries what it applies to:\n\n [\n { \"flowId\": \"550e8400-...\", \"variables\": { \"orderNumber\": \"12345\" } },\n { \"flowId\": \"550e8400-...\", \"happyPath\": true, \"variables\": { \"orderNumber\": \"55555\" } },\n { \"flowId\": \"550e8400-...\", \"edgeCaseId\": \"7a3d2e1f-...\", \"variables\": { \"orderNumber\": \"67890\" } }\n ]\n\nAn entry that narrows to neither covers everything that flow resolves. A flow this plan does not\nattach, or an edge case that does not belong to the flow, is rejected rather than ignored.\n\nA plan built on scenarios rather than customer flows targets them the same way, with `scenarioId` in\nplace of `flowId`. That form is deprecated alongside scenarios themselves, and still accepted so runs\nagainst those plans keep working." } }, "required": [ "planConfigKey" ], "additionalProperties": false, "title": "Existing plan by config key", "description": "Run a config-managed plan by its config name, with no id lookup.", "example": { "planConfigKey": "simulationPlan/nightly-screener-suite" } }, "RunSimulationFromTemplate": { "type": "object", "properties": { "template": { "type": "string", "minLength": 1, "description": "The template to run, as listed by GET /v1/simulation/template.", "example": "health-check" }, "agentEndpoints": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "minItems": 1, "description": "The agent endpoints to call. No template can know these." }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direction of the simulation (INBOUND or OUTBOUND)", "example": "INBOUND" }, "flows": { "type": "array", "items": { "$ref": "#/components/schemas/RunPlanFlowSelection" }, "minItems": 1, "description": "The flows to run, in the same shape a run plan takes them.\n\nRequired when the template lists no flows of its own: it presets what to measure, and this\nsays what to measure it on. Optional when it does, where these REPLACE the ones it would\nhave run, so you can narrow a suite to the cases you care about. Either way,\nGET /v1/simulation/template lists the flows and variant ids each template covers.\n\nOn a template that sweeps a property, every value runs exactly what you select here: the\nhappy path, the edge cases you name, or `edgeCases: \"ALL\"`. Each selected case is a call per\nvalue per iteration, so naming three edge cases triples the run.", "example": [ { "slug": "sf-prompt-injection", "edgeCases": [ { "slug": "data-embedded-injection" } ] }, { "id": "3a1d5e7c-9b2f-4a6d-8c31-5f7e9d0a2b4c", "happyPath": true } ] }, "iterationCount": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Runs per test case (1-10000). Defaults to 1, or to 6 for a template that sweeps a property. A sweep needs at least 5 calls per value (test cases per value times iterations) to compare its values, and a lower count is refused with 400.", "example": 6 }, "maxConcurrentJobs": { "type": "integer", "minimum": 1, "default": 5, "description": "Maximum number of concurrent simulation jobs", "example": 5 }, "maxSimulationDurationSeconds": { "type": "integer", "minimum": 1, "description": "Defaults to the template's `defaultMaxSimulationDurationSeconds`, as returned by GET /v1/simulation/template." }, "silenceTimeoutSeconds": { "type": "integer", "minimum": 1, "default": 30, "description": "Timeout in seconds for silence detection", "example": 30 }, "maxNoResponseRetries": { "type": "integer", "minimum": 0, "maximum": 10, "default": 0, "description": "How many more times to run a test case when the agent under test never responds: it never speaks on a call or never replies in a chat (0-10). 0 turns retries off. Failed checks and failures on Roark’s side are never retried.\n\nEach retry is a separate attempt, billed like any other, so a plan retrying N times can place up to N + 1 calls per test case.\nEvery silent attempt stays on the run with its own call; the run settles once each test case has a final attempt, and the\nagent never spoke verdict is judged on each test case’s last attempt.", "example": 2 }, "noResponseRetryBackoffSeconds": { "type": "integer", "minimum": 30, "maximum": 600, "default": 90, "description": "Seconds a retry waits before it dials (30-600). Only used when `maxNoResponseRetries` is above 0.", "example": 90 }, "endCallPhrases": { "type": "array", "items": { "type": "string" }, "default": [ "goodbye" ], "description": "Phrases that trigger end of call. Empty array disables the feature.", "example": [ "goodbye" ] }, "endCallReasons": { "type": "array", "items": { "type": "string" }, "description": "Semantic conditions that trigger end of call. The LLM evaluates the conversation against these conditions. Defaults to the template's `defaultEndCallReasons`, as returned by GET /v1/simulation/template. Pass an empty array to run with none.", "example": [ "Order has been confirmed by the agent" ] }, "executionMode": { "type": "string", "enum": [ "PARALLEL", "SEQUENTIAL_SAME_RUN_PLAN", "SEQUENTIAL_PROJECT" ], "default": "PARALLEL", "description": "Execution mode (PARALLEL or SEQUENTIAL)", "example": "PARALLEL" }, "enrichWithLiveConversation": { "type": "boolean", "default": false, "description": "Merge the customer's own recording of the real call into each simulation, so metrics can be\nscored against the live leg as well as the simulated one. This is the API equivalent of the\ndashboard's live-enrichment toggle.\n\nWith this on, the run provisions a phone number and holds each call open for up to 15 minutes\nwaiting for a matching call to be posted to POST /v1/call. A call matches on the provisioned\nnumber (`roarkPhoneNumber` on the job) with a start time inside the simulation window. If\nnothing arrives, the simulation still completes and any `LIVE`-sourced metric produces no value.\n\nRequired by any metric whose `requiresLiveConversation` is true: without it that metric is\nsilently skipped.", "example": false }, "additionalMetrics": { "type": "array", "items": { "$ref": "#/components/schemas/RunPlanMetricRef" }, "minItems": 1, "description": "Metrics to collect on top of the template's own, referenced by `id` or `slug` like a plan's `metrics`. The template's metrics and checks always run; naming one of them here again keeps it once, with the success criteria you set on it.", "example": [ { "slug": "call_ended_prematurely" } ] }, "comparisonValues": { "type": "array", "items": { "anyOf": [ { "type": "string", "minLength": 1, "description": "A value of `comparisonProperty`, run as its plain arm." }, { "$ref": "#/components/schemas/ComparisonArm" } ] }, "minItems": 1, "description": "The arms of the sweep to run, for a template that sweeps one (GET /v1/simulation/template\nreturns `sweep.property` for those that do). This is what the run costs: the flow is called\nonce per arm, so ten arms is ten times the calls of one.\n\nOmit it to run every value the property has, plain, which for `accent-handling` is more than\ntwenty. Send a subset to narrow it, for example the three accents you actually serve. An\nobject entry pins something on that arm only, such as a noise level per bed on\n`background-noise-robustness`: `{ \"value\": \"OFFICE\", \"backgroundNoiseVolume\": 0.6 }` plays\nOFFICE at 60% while the other beds keep the default. See `POST /v1/simulation/plan`.", "example": [ "US", "GB", "IN" ] }, "comparisonBaseline": { "type": [ "string", "null" ], "description": "The sweep's reference value, shown first in the results. Defaults to the template's own\nbaseline, as returned by GET /v1/simulation/template. Whether a value did significantly worse\ndoes not depend on it: that is decided against every other value combined.\n\nSend it with `comparisonValues` and it must be one of them, or the request is rejected:\nanchoring every difference to an arm the run never made would measure it against nothing.\nLeave it out and the template's own baseline is used, and quietly dropped if your\nnarrowing excluded it, since that one you did not choose.", "example": "US" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "ask": { "type": "string", "minLength": 1, "description": "The question the caller asks the agent.", "example": "What are your holiday hours?" }, "expect": { "type": "string", "minLength": 1, "description": "The answer the agent must give, judged against the transcript.", "example": "We're closed on public holidays." } }, "required": [ "ask", "expect" ] }, "minItems": 1, "description": "For the `question-answer-check` template: the questions to ask and the answer expected for each. Every question runs as its own graded call." }, "personaId": { "type": "string", "format": "uuid", "description": "For `question-answer-check`: the persona that asks the questions." }, "environmentId": { "type": "string", "format": "uuid", "description": "For `question-answer-check`: the environment the calls run in." }, "name": { "type": "string", "minLength": 1, "description": "What to call this. Defaults to the template's name and the date, and required with `saveAsPlan`." }, "saveAsPlan": { "type": "boolean", "description": "Keeps the resolved configuration as a run plan, listed by GET /v1/simulation/plan and re-runnable with `planId`. Requires `name`." }, "variables": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" }, "description": "Global format: key-value pairs that apply to ALL scenarios in the plan", "example": { "orderNumber": "12345", "environment": "staging" } }, { "type": "array", "items": { "type": "object", "properties": { "flowId": { "type": "string", "format": "uuid", "description": "A customer flow this plan runs." }, "happyPath": { "type": "boolean", "const": true, "description": "Narrow to the flow's happy path." }, "edgeCaseId": { "type": "string", "format": "uuid", "description": "Narrow to one edge case of that flow." }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The values to apply." } }, "required": [ "flowId", "variables" ] }, "description": "Values scoped to the flows this plan runs", "example": [ { "flowId": "550e8400-e29b-41d4-a716-446655440000", "variables": { "orderNumber": "12345" } }, { "flowId": "550e8400-e29b-41d4-a716-446655440000", "happyPath": true, "variables": { "orderNumber": "55555" } }, { "flowId": "550e8400-e29b-41d4-a716-446655440000", "edgeCaseId": "7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e", "variables": { "orderNumber": "67890" } } ] } ], "description": "Values for the {{variables}} the run resolves. An object applies them everywhere; an array\ntargets a flow, its happy path, or one of its edge cases with `flowId`.\n\nThe scenario-scoped form the other variants accept is not valid here: a template run is\nalways flow-based, so there would be no scenario for it to reach." } }, "required": [ "template", "agentEndpoints", "direction" ], "additionalProperties": false, "title": "From template", "description": "Run one of the built-in templates against your agent.", "example": { "template": "health-check", "direction": "OUTBOUND", "agentEndpoints": [ { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } ] } }, "SimulationRunGroup": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "createdAt": { "type": "string", "description": "ISO 8601" }, "runCount": { "type": "integer" }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationRunGroupRun" } }, "latestReport": { "oneOf": [ { "$ref": "#/components/schemas/SimulationRunGroupReport" }, { "type": "null" } ], "description": "The latest group report in any status. Null when none has been requested." } }, "required": [ "id", "name", "createdAt", "runCount", "runs", "latestReport" ], "description": "Several simulation runs read as one." }, "SimulationRunGroupRun": { "type": "object", "properties": { "simulationRunPlanJobId": { "type": "string", "format": "uuid", "description": "The run, readable at GET /v1/simulation/plan/job/{jobId}" }, "simulationRunPlanId": { "type": "string", "format": "uuid" }, "planName": { "type": [ "string", "null" ], "description": "The name of the plan the run ran. Null when the plan was deleted." }, "runNumber": { "type": [ "integer", "null" ], "description": "Per-project run number, shown as SR-42 in the app." }, "status": { "type": "string", "enum": [ "PENDING", "QUEUED", "CREATING_SNAPSHOTS", "CREATING_SIMULATIONS", "PREPARING_CAPACITY", "RUNNING_SIMULATIONS", "COMPLETED", "FAILED", "TIMED_OUT", "CANCELLED", "CANCELLING", "ENDING_SIMULATIONS" ] }, "createdAt": { "type": "string", "description": "ISO 8601" }, "startedAt": { "type": [ "string", "null" ] }, "endedAt": { "type": [ "string", "null" ] } }, "required": [ "simulationRunPlanJobId", "simulationRunPlanId", "planName", "runNumber", "status", "createdAt", "startedAt", "endedAt" ], "description": "One run in the group, in group order." }, "SimulationRunGroupReport": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "GENERATING", "READY", "FAILED" ], "description": "PENDING and GENERATING are in flight; READY carries the document; FAILED carries errorMessage." }, "errorMessage": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "ISO 8601" }, "completedAt": { "type": [ "string", "null" ], "description": "ISO 8601. Null until the report settles." }, "document": { "oneOf": [ { "$ref": "#/components/schemas/SimulationRunGroupReportDocument" }, { "type": "null" } ], "description": "Null until the report is READY." } }, "required": [ "id", "status", "errorMessage", "createdAt", "completedAt", "document" ], "description": "One generation of the group report." }, "SimulationRunGroupReportDocument": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "generatedAtIso": { "type": "string" }, "model": { "type": "string" }, "simulationRunGroupId": { "type": "string" }, "headline": { "type": "object", "properties": { "groupName": { "type": "string" }, "runCount": { "type": "integer" }, "reportedRunCount": { "type": "integer" }, "passedRunCount": { "type": "integer" }, "callCount": { "type": "integer" }, "verdict": { "type": "string", "enum": [ "PASSED", "THRESHOLD_FAILED" ] }, "completedAtIso": { "type": [ "string", "null" ] }, "verdictProse": { "type": "string" }, "statTiles": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" }, "sub": { "type": [ "string", "null" ] }, "deltaDirection": { "type": [ "string", "null" ], "enum": [ "POSITIVE", "NEGATIVE", "NEUTRAL" ] } }, "required": [ "label", "value", "sub", "deltaDirection" ] } } }, "required": [ "groupName", "runCount", "reportedRunCount", "passedRunCount", "callCount", "verdict", "completedAtIso", "verdictProse", "statTiles" ] }, "runs": { "type": "array", "items": { "type": "object", "properties": { "simulationRunPlanJobId": { "type": "string" }, "runLabel": { "type": "string" }, "runNumber": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "PENDING", "QUEUED", "CREATING_SNAPSHOTS", "CREATING_SIMULATIONS", "PREPARING_CAPACITY", "RUNNING_SIMULATIONS", "COMPLETED", "FAILED", "TIMED_OUT", "CANCELLED", "CANCELLING", "ENDING_SIMULATIONS" ] }, "verdict": { "type": [ "string", "null" ], "enum": [ "PASSED", "THRESHOLD_FAILED" ] }, "callCount": { "type": "integer" }, "checksPassed": { "type": "integer" }, "checksTotal": { "type": "integer" }, "themeCount": { "type": "integer" }, "completedAtIso": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] } }, "required": [ "simulationRunPlanJobId", "runLabel", "runNumber", "status", "verdict", "callCount", "checksPassed", "checksTotal", "themeCount", "completedAtIso", "summary" ] } }, "executiveSummary": { "type": "array", "items": { "type": "object", "properties": { "heading": { "type": "string" }, "body": { "type": "string" } }, "required": [ "heading", "body" ] } }, "scorecard": { "type": "array", "items": { "type": "object", "properties": { "checkName": { "type": "string" }, "runCount": { "type": "integer" }, "failedRunCount": { "type": "integer" }, "failedCount": { "type": "integer" }, "evaluatedCount": { "type": "integer" }, "passRatePct": { "type": [ "number", "null" ] } }, "required": [ "checkName", "runCount", "failedRunCount", "failedCount", "evaluatedCount", "passRatePct" ] } }, "wentWell": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "body": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "simulationRunPlanJobId": { "type": "string" }, "conversationId": { "type": "string" }, "callId": { "type": [ "string", "null" ] }, "personaName": { "type": [ "string", "null" ] }, "cueMs": { "type": [ "integer", "null" ] } }, "required": [ "text", "simulationRunPlanJobId", "conversationId", "callId", "personaName", "cueMs" ] } } }, "required": [ "title", "body", "evidence" ] } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "order": { "type": "integer" }, "title": { "type": "string" }, "body": { "type": "string" }, "severity": { "type": "string", "enum": [ "HIGH", "MEDIUM", "LOW" ] }, "rootCauseChannel": { "type": [ "string", "null" ], "enum": [ "PROMPT", "VOICE_CONFIG", "STT", "SPEECH_MODEL", "LLM_MODEL", "INFRA", "EXTERNAL" ] }, "affectedCallCount": { "type": "integer" }, "runLabels": { "type": "array", "items": { "type": "string" } }, "checkNames": { "type": "array", "items": { "type": "string" } }, "sourceThemes": { "type": "array", "items": { "type": "object", "properties": { "simulationRunPlanJobId": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "simulationRunPlanJobId", "slug" ] } }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "simulationRunPlanJobId": { "type": "string" }, "conversationId": { "type": "string" }, "callId": { "type": [ "string", "null" ] }, "personaName": { "type": [ "string", "null" ] }, "cueMs": { "type": [ "integer", "null" ] } }, "required": [ "text", "simulationRunPlanJobId", "conversationId", "callId", "personaName", "cueMs" ] } }, "calls": { "type": "array", "items": { "type": "object", "properties": { "simulationRunPlanJobId": { "type": "string" }, "conversationId": { "type": "string" }, "callId": { "type": [ "string", "null" ] }, "personaName": { "type": [ "string", "null" ] }, "cueMs": { "type": [ "integer", "null" ] } }, "required": [ "simulationRunPlanJobId", "conversationId", "callId", "personaName", "cueMs" ] } } }, "required": [ "order", "title", "body", "severity", "rootCauseChannel", "affectedCallCount", "runLabels", "checkNames", "sourceThemes", "evidence", "calls" ] } }, "smallerItems": { "type": "array", "items": { "type": "object", "properties": { "order": { "type": "integer" }, "title": { "type": "string" }, "body": { "type": "string" }, "severity": { "type": "string", "enum": [ "HIGH", "MEDIUM", "LOW" ] }, "rootCauseChannel": { "type": [ "string", "null" ], "enum": [ "PROMPT", "VOICE_CONFIG", "STT", "SPEECH_MODEL", "LLM_MODEL", "INFRA", "EXTERNAL" ] }, "affectedCallCount": { "type": "integer" }, "runLabels": { "type": "array", "items": { "type": "string" } }, "checkNames": { "type": "array", "items": { "type": "string" } }, "sourceThemes": { "type": "array", "items": { "type": "object", "properties": { "simulationRunPlanJobId": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "simulationRunPlanJobId", "slug" ] } }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "simulationRunPlanJobId": { "type": "string" }, "conversationId": { "type": "string" }, "callId": { "type": [ "string", "null" ] }, "personaName": { "type": [ "string", "null" ] }, "cueMs": { "type": [ "integer", "null" ] } }, "required": [ "text", "simulationRunPlanJobId", "conversationId", "callId", "personaName", "cueMs" ] } }, "calls": { "type": "array", "items": { "type": "object", "properties": { "simulationRunPlanJobId": { "type": "string" }, "conversationId": { "type": "string" }, "callId": { "type": [ "string", "null" ] }, "personaName": { "type": [ "string", "null" ] }, "cueMs": { "type": [ "integer", "null" ] } }, "required": [ "simulationRunPlanJobId", "conversationId", "callId", "personaName", "cueMs" ] } } }, "required": [ "order", "title", "body", "severity", "rootCauseChannel", "affectedCallCount", "runLabels", "checkNames", "sourceThemes", "evidence", "calls" ] } }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "order": { "type": "integer" }, "title": { "type": "string" }, "body": { "type": "string" }, "channel": { "type": [ "string", "null" ], "enum": [ "PROMPT", "VOICE_CONFIG", "STT", "SPEECH_MODEL", "LLM_MODEL", "INFRA", "EXTERNAL" ] }, "issueOrders": { "type": "array", "items": { "type": "integer" } } }, "required": [ "order", "title", "body", "channel", "issueOrders" ] } }, "aggregates": { "type": "array", "items": { "type": "object", "properties": { "metricName": { "type": "string" }, "averageLabel": { "type": [ "string", "null" ] }, "medianLabel": { "type": [ "string", "null" ] }, "p95Label": { "type": [ "string", "null" ] }, "evaluatedCount": { "type": "integer" } }, "required": [ "metricName", "averageLabel", "medianLabel", "p95Label", "evaluatedCount" ] } }, "methodology": { "type": "string" } }, "required": [ "version", "generatedAtIso", "model", "simulationRunGroupId", "headline", "runs", "executiveSummary", "scorecard", "wentWell", "issues", "smallerItems", "recommendations", "aggregates", "methodology" ], "description": "The group report: the runs it covers, a scorecard summed across them, what went well, and the issues found, each merged from the per-run debriefs with call-level evidence. Every figure is computed from the runs; the prose is AI-written around those facts." }, "CreateSimulationRunGroupInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "What to call the group. Defaults to the plans' names when starting plans, and to the runs' plan names when grouping existing runs.", "example": "Release 4.2 regression" }, "simulationRunPlanJobIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 2, "maxItems": 20, "description": "Runs that already exist, in display order (2 to 20). Runs still in progress are fine: the group report waits for them. Send this or `simulationRunPlanIds`, not both.", "example": [ "7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f", "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" ] }, "simulationRunPlanIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 2, "maxItems": 20, "description": "Plans to run once each, in display order (2 to 20). Each plan starts a run, exactly as POST /v1/simulation/plan/{planId}/job would. Send this or `simulationRunPlanJobIds`, not both.", "example": [ "7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f", "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" ] } }, "additionalProperties": false, "description": "Group existing runs, or start one run per plan and group those.", "example": { "name": "Release 4.2 regression", "simulationRunPlanIds": [ "3c1d2e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "6d7e8f9a-0b1c-4d2e-9f3a-4b5c6d7e8f9a" ] } }, "ListSimulationRunGroupsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationRunGroupListItem" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer", "description": "Total run groups in the project, ignoring this page." }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "offset", "total", "hasMore" ] } }, "required": [ "data", "pagination" ] }, "SimulationRunGroupListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "createdAt": { "type": "string", "description": "ISO 8601" }, "runCount": { "type": "integer" }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationRunGroupRun" } }, "latestReport": { "oneOf": [ { "$ref": "#/components/schemas/SimulationRunGroupReportSummary" }, { "type": "null" } ], "description": "Where the latest group report stands. Read the document from GET /v1/simulation/run-group/{groupId}." } }, "required": [ "id", "name", "createdAt", "runCount", "runs", "latestReport" ] }, "SimulationRunGroupReportSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "GENERATING", "READY", "FAILED" ], "description": "PENDING and GENERATING are in flight; READY carries the document; FAILED carries errorMessage." }, "errorMessage": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "ISO 8601" }, "completedAt": { "type": [ "string", "null" ], "description": "ISO 8601. Null until the report settles." } }, "required": [ "id", "status", "errorMessage", "createdAt", "completedAt" ], "description": "Where the group report stands, without its document." }, "ListSimulationGroupsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationGroup" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer", "description": "Total groups in the project, ignoring this page." }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "offset", "total", "hasMore" ] } }, "required": [ "data", "pagination" ] }, "SimulationGroup": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "configManaged": { "type": "boolean", "description": "Whether this group is managed by config as code. A managed group can be run here, but PUT and DELETE on it return 409: change it in the config file." }, "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The plan, readable at GET /v1/simulation/plan/{planId}" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "description": "The plans in run order. A plan deleted since it was added is left out." }, "notifications": { "type": "object", "properties": { "email": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "recipients": { "type": "array", "items": { "type": "string" } } }, "required": [ "enabled", "recipients" ] }, "slack": { "type": "array", "items": { "type": "object", "properties": { "channelId": { "type": "string" }, "channelName": { "type": "string" } }, "required": [ "channelId", "channelName" ] } } }, "required": [ "email", "slack" ], "description": "Where each run's group report announces itself once it is ready." }, "lastRunAt": { "type": [ "string", "null" ], "description": "ISO 8601. Null when it has never run." }, "latestRunGroupId": { "type": [ "string", "null" ], "format": "uuid", "description": "The most recent run group it started, readable at GET /v1/simulation/run-group/{groupId}. Null when it has never run." }, "createdAt": { "type": "string", "description": "ISO 8601" }, "updatedAt": { "type": "string", "description": "ISO 8601" } }, "required": [ "id", "name", "description", "configManaged", "plans", "notifications", "lastRunAt", "latestRunGroupId", "createdAt", "updatedAt" ], "description": "A saved, repeatable set of plans that run together. Each run starts one run of every plan and groups them into a run group with one combined report." }, "CreateSimulationGroupInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "What to call the group.", "example": "Release regression" }, "description": { "type": [ "string", "null" ], "maxLength": 2000, "description": "What the group is for." }, "simulationRunPlanIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 2, "maxItems": 20, "description": "The plans to run together, in run order (2 to 20). Duplicates are dropped.", "example": [ "3c1d2e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "6d7e8f9a-0b1c-4d2e-9f3a-4b5c6d7e8f9a" ] }, "notifications": { "$ref": "#/components/schemas/SimulationGroupNotificationsInput", "description": "Defaults to email on (to the default audience) and no Slack." } }, "required": [ "name", "simulationRunPlanIds" ], "additionalProperties": false, "description": "A saved set of plans to run together, again and again.", "example": { "name": "Release regression", "simulationRunPlanIds": [ "3c1d2e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "6d7e8f9a-0b1c-4d2e-9f3a-4b5c6d7e8f9a" ], "notifications": { "email": { "enabled": true, "recipients": [] }, "slack": [] } } }, "SimulationGroupNotificationsInput": { "type": "object", "properties": { "email": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether each run's group report is emailed when it is ready." }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50, "default": [], "description": "Addresses to email (at most 50), Roark users or not: the email attaches the report PDF. Empty emails every member of the project.", "example": [ "qa-lead@example.com" ] } }, "required": [ "enabled" ], "additionalProperties": false, "default": { "enabled": true, "recipients": [] } }, "slack": { "type": "array", "items": { "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1, "description": "The Slack channel id", "example": "C07ABCDEF12" }, "channelName": { "type": "string", "minLength": 1, "description": "The channel name, shown in Roark", "example": "qa-reports" } }, "required": [ "channelId", "channelName" ], "additionalProperties": false }, "maxItems": 10, "default": [], "description": "Channels in the project's connected Slack workspace to post the report to (at most 10). Slack must be connected to the project first." } }, "additionalProperties": false, "description": "Where each run's group report announces itself once it is ready.", "example": { "email": { "enabled": true, "recipients": [] }, "slack": [ { "channelId": "C07ABCDEF12", "channelName": "qa-reports" } ] } }, "UpdateSimulationGroupInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Send null to clear it." }, "simulationRunPlanIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 2, "maxItems": 20, "description": "Replaces the plans, in run order." }, "notifications": { "$ref": "#/components/schemas/SimulationGroupNotificationsInput", "description": "Replaces the notification settings as a whole." } }, "additionalProperties": false, "description": "Omitted fields keep their current value. Run groups the group already started keep theirs.", "example": { "simulationRunPlanIds": [ "3c1d2e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "6d7e8f9a-0b1c-4d2e-9f3a-4b5c6d7e8f9a" ] } }, "GetEnvironmentsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EnvironmentResponse" } }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of items" }, "hasMore": { "type": "boolean", "description": "Whether there are more items to fetch" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page of items" } }, "required": [ "total", "hasMore", "nextCursor" ] } }, "required": [ "data", "pagination" ], "description": "Paginated list of environments: the project's own plus the shared Roark-curated ones" }, "EnvironmentResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "backgroundNoise": { "type": "string", "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "default": "NONE" }, "backgroundNoiseVolume": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.1 }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format" }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format" } }, "required": [ "id", "name", "backgroundNoise", "backgroundNoiseVolume", "createdAt", "updatedAt" ], "description": "A simulation environment: the ambient conditions a customer flow variant runs under. The list includes both your own and the ones Roark curates for every project." }, "CreateEnvironmentInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Display name, shown wherever a flow variant references the environment", "example": "Busy call centre" }, "description": { "type": [ "string", "null" ], "description": "Optional note on when to use this environment", "example": "Open-plan office at peak hours" }, "backgroundNoise": { "type": "string", "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "description": "The noise bed played underneath the simulated caller. NONE plays nothing.", "example": "OFFICE" }, "backgroundNoiseVolume": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.1, "description": "How loud the bed plays, as a gain from 0 (silent) to 1 (as loud as the caller). Defaults to 0.1, which sits well under the caller. Ignored on Vapi endpoints, which have no level control.", "example": 0.3 } }, "required": [ "name", "backgroundNoise" ], "description": "Input for creating an environment" }, "UpdateEnvironmentInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Display name, shown wherever a flow variant references the environment", "example": "Busy call centre" }, "description": { "type": [ "string", "null" ], "description": "Optional note on when to use this environment", "example": "Open-plan office at peak hours" }, "backgroundNoise": { "type": "string", "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "description": "The noise bed played underneath the simulated caller. NONE plays nothing.", "example": "OFFICE" }, "backgroundNoiseVolume": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.1, "description": "How loud the bed plays, as a gain from 0 (silent) to 1 (as loud as the caller). Defaults to 0.1, which sits well under the caller. Ignored on Vapi endpoints, which have no level control.", "example": 0.3 } }, "description": "Input for updating an environment. Only the fields sent are changed. Roark-curated environments cannot be edited." }, "DeleteEnvironmentResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the deleted environment" }, "deleted": { "type": "boolean", "const": true, "description": "Always true when the environment was deleted" } }, "required": [ "id", "deleted" ] }, "GetRunPlansResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RunPlanResponse" } }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of items" }, "hasMore": { "type": "boolean", "description": "Whether there are more items to fetch" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page of items" } }, "required": [ "total", "hasMore", "nextCursor" ] } }, "required": [ "data", "pagination" ], "description": "Paginated list of simulation run plans" }, "RunPlanResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the run plan" }, "name": { "type": "string", "description": "Name of the run plan" }, "isConfigManaged": { "type": "boolean", "description": "Whether this plan is managed by config as code. A managed plan is reconciled from your config: PUT and DELETE on it return 409, and changes belong in the config file." }, "template": { "type": [ "string", "null" ], "description": "The built-in template this plan was created from, as listed by GET /v1/simulation/template. `null` for a plan described field by field. Recorded once at creation: the plan does not follow later changes to the template.", "example": "accent-handling" }, "description": { "type": [ "string", "null" ], "description": "Description of the run plan" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direction of the simulation (INBOUND or OUTBOUND)" }, "iterationCount": { "type": "integer", "description": "Number of iterations to run for each test case" }, "maxConcurrentJobs": { "type": "integer", "description": "Maximum number of concurrent simulation jobs" }, "maxSimulationDurationSeconds": { "type": "integer", "description": "Maximum duration in seconds for each simulation" }, "silenceTimeoutSeconds": { "type": "integer", "description": "Timeout in seconds for silence detection" }, "maxNoResponseRetries": { "type": "integer", "description": "How many more times to run a test case when the agent under test never responds: it never speaks on a call or never replies in a chat (0-10). 0 turns retries off. Failed checks and failures on Roark’s side are never retried.\n\nEach retry is a separate attempt, billed like any other, so a plan retrying N times can place up to N + 1 calls per test case.\nEvery silent attempt stays on the run with its own call; the run settles once each test case has a final attempt, and the\nagent never spoke verdict is judged on each test case’s last attempt." }, "noResponseRetryBackoffSeconds": { "type": "integer", "description": "Seconds a retry waits before it dials (30-600). Only used when `maxNoResponseRetries` is above 0." }, "endCallPhrases": { "type": "array", "items": { "type": "string" }, "description": "Phrases that trigger end of call. Empty array means disabled." }, "endCallReasons": { "type": "array", "items": { "type": "string" }, "description": "Semantic conditions that trigger end of call. The LLM evaluates the conversation against these conditions. Empty array means disabled." }, "executionMode": { "type": "string", "enum": [ "PARALLEL", "SEQUENTIAL_SAME_RUN_PLAN", "SEQUENTIAL_PROJECT" ], "description": "Execution mode (PARALLEL or SEQUENTIAL)" }, "scenarios": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Template variables for this scenario instance. Absent when no variables are set. The same scenario can appear multiple times with different variables.", "example": { "customerName": "John Doe", "appointmentDate": "2024-02-15" } } }, "required": [ "id" ] }, "deprecated": true, "description": "Deprecated: use `flows` instead. Scenarios included in this run plan." }, "flows": { "type": "array", "items": { "$ref": "#/components/schemas/RunPlanFlowSelection" }, "description": "Customer flows included in this run plan" }, "personas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "description": "Personas included in this run plan. Only meaningful alongside `scenarios`." }, "agentEndpoints": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "description": "Agent endpoints included in this run plan" }, "evaluators": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "description": "Deprecated: Use metrics instead. Evaluators included in this run plan." }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "conversationSource": { "type": [ "string", "null" ], "enum": [ "SIMULATED", "LIVE" ], "description": "Which side of an enriched run this metric is scored on. `null` means the default, SIMULATED." }, "minPassRate": { "type": [ "number", "null" ], "description": "THE BAR. The share of the run's simulations (0-100) that must pass this check. `null` means the 80% default." } }, "required": [ "id", "conversationSource", "minPassRate" ] }, "description": "Metric definitions included in this run plan" }, "enrichWithLiveConversation": { "type": "boolean", "description": "Whether this plan merges the customer's own live recording into each simulation." }, "includeFlowMetrics": { "type": "boolean", "description": "Whether this plan also collects each attached flow's own metrics, on top of its own list." }, "includeAutomaticMetrics": { "type": "boolean", "description": "Whether this plan lets a run add metrics by itself off the attached flows, on top of its own list. False means the `metrics` list is the whole answer." }, "comparisonProperty": { "type": [ "string", "null" ], "enum": [ "ACCENT", "AGE", "BACKGROUND_NOISE", "BACKGROUND_NOISE_VOLUME", "BASE_EMOTION", "CONFIRMATION_STYLE", "GENDER", "INTENT_CLARITY", "LANGUAGE", "INTERRUPTION", "MEMORY_RELIABILITY", "RESPONSE_TIMING", "SPEECH_CLARITY", "SPEECH_PACE" ], "description": "The property of the caller or their surroundings this plan investigates, such as `BACKGROUND_NOISE`. The run report compares the arms on it. `null` means the report works out for itself which property varies." }, "comparisonBaseline": { "type": [ "string", "null" ], "description": "The reference value of `comparisonProperty`, such as `NONE` for `BACKGROUND_NOISE`: shown first in the results. Whether a value did significantly worse does not depend on it: that is decided against every other value combined (see `sweepAttribution`). `null` when no comparison is declared, or when the property has no obvious norm and none was chosen." }, "notifications": { "type": "object", "properties": { "email": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "recipients": { "type": "array", "items": { "type": "string" } } }, "required": [ "enabled", "recipients" ] }, "slack": { "type": "array", "items": { "type": "object", "properties": { "channelId": { "type": "string" }, "channelName": { "type": "string" } }, "required": [ "channelId", "channelName" ] } } }, "required": [ "email", "slack" ], "description": "Where each run's report announces itself once it is ready. Email off and no Slack channels means the plan sends none." }, "testCaseCount": { "type": "integer", "description": "Total number of test cases generated from the plan configuration" }, "createdAt": { "type": "string", "description": "When the run plan was created" }, "updatedAt": { "type": "string", "description": "When the run plan was last updated" } }, "required": [ "id", "name", "isConfigManaged", "template", "direction", "iterationCount", "maxConcurrentJobs", "maxSimulationDurationSeconds", "silenceTimeoutSeconds", "maxNoResponseRetries", "noResponseRetryBackoffSeconds", "endCallPhrases", "endCallReasons", "executionMode", "scenarios", "flows", "personas", "agentEndpoints", "evaluators", "metrics", "enrichWithLiveConversation", "includeFlowMetrics", "includeAutomaticMetrics", "comparisonProperty", "comparisonBaseline", "notifications", "testCaseCount", "createdAt", "updatedAt" ], "description": "A simulation run plan defining the test matrix" }, "CreateRunPlanResponse": { "type": "object", "properties": { "runPlan": { "$ref": "#/components/schemas/RunPlanResponse" }, "runPlanJob": { "oneOf": [ { "$ref": "#/components/schemas/RunSimulationPlanResponse" }, { "type": "null" } ], "description": "The triggered job, only present if autoRun was true" } }, "required": [ "runPlan" ], "description": "Response when creating a run plan, optionally including a triggered job" }, "RunSimulationPlanResponse": { "type": "object", "properties": { "simulationRunPlanId": { "type": "string", "format": "uuid", "description": "ID of the simulation run plan that was executed" }, "simulationRunPlanJobId": { "type": "string", "format": "uuid", "description": "ID of the simulation run plan job that was created" }, "status": { "type": "string", "enum": [ "PENDING", "QUEUED", "CREATING_SNAPSHOTS", "CREATING_SIMULATIONS", "PREPARING_CAPACITY", "RUNNING_SIMULATIONS", "COMPLETED", "FAILED", "TIMED_OUT", "CANCELLED", "CANCELLING", "ENDING_SIMULATIONS" ], "description": "Initial status of the job" }, "createdAt": { "type": "string", "description": "When the job was created" } }, "required": [ "simulationRunPlanId", "simulationRunPlanJobId", "status", "createdAt" ], "description": "Response when triggering a simulation run plan", "example": { "simulationRunPlanId": "9a8b7c6d-5e4f-3210-abcd-ef9876543210", "simulationRunPlanJobId": "7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f", "status": "PENDING", "createdAt": "2024-01-15T10:30:00Z" } }, "CreateRunPlanInput": { "oneOf": [ { "$ref": "#/components/schemas/CreateRunPlanFromConfig" }, { "$ref": "#/components/schemas/CreateRunPlanFromTemplate" } ], "description": "A run plan to configure, or a built-in template to save as one." }, "CreateRunPlanFromConfig": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Name of the run plan", "example": "My Run Plan" }, "description": { "type": "string", "description": "Description of the run plan", "example": "A run plan for testing inbound calls" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direction of the simulation (INBOUND or OUTBOUND)", "example": "INBOUND" }, "iterationCount": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1, "description": "Number of iterations to run for each test case (1-10000)", "example": 1 }, "maxConcurrentJobs": { "type": "integer", "minimum": 1, "default": 5, "description": "Maximum number of concurrent simulation jobs", "example": 5 }, "maxSimulationDurationSeconds": { "type": "integer", "minimum": 1, "description": "Maximum duration in seconds for each simulation", "example": 300 }, "silenceTimeoutSeconds": { "type": "integer", "minimum": 1, "default": 30, "description": "Timeout in seconds for silence detection", "example": 30 }, "maxNoResponseRetries": { "type": "integer", "minimum": 0, "maximum": 10, "default": 0, "description": "How many more times to run a test case when the agent under test never responds: it never speaks on a call or never replies in a chat (0-10). 0 turns retries off. Failed checks and failures on Roark’s side are never retried.\n\nEach retry is a separate attempt, billed like any other, so a plan retrying N times can place up to N + 1 calls per test case.\nEvery silent attempt stays on the run with its own call; the run settles once each test case has a final attempt, and the\nagent never spoke verdict is judged on each test case’s last attempt.", "example": 2 }, "noResponseRetryBackoffSeconds": { "type": "integer", "minimum": 30, "maximum": 600, "default": 90, "description": "Seconds a retry waits before it dials (30-600). Only used when `maxNoResponseRetries` is above 0.", "example": 90 }, "endCallPhrases": { "type": "array", "items": { "type": "string" }, "default": [ "goodbye" ], "description": "Phrases that trigger end of call. Empty array disables the feature.", "example": [ "goodbye" ] }, "endCallReasons": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Semantic conditions that trigger end of call. The LLM evaluates the conversation against these conditions. Empty array disables the feature.", "example": [ "Order has been confirmed by the agent" ] }, "executionMode": { "type": "string", "enum": [ "PARALLEL", "SEQUENTIAL_SAME_RUN_PLAN", "SEQUENTIAL_PROJECT" ], "default": "PARALLEL", "description": "Execution mode (PARALLEL or SEQUENTIAL)", "example": "PARALLEL" }, "scenarios": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Scenario ID" }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Template variables for this scenario instance. The same scenario can appear multiple times with different variables.", "example": { "customerName": "John Doe", "appointmentDate": "2024-02-15" } } }, "required": [ "id" ] }, "minItems": 1, "deprecated": true, "description": "Deprecated: use `flows` instead. Scenarios to include in this run plan. The same scenario ID can appear multiple times with different variables." }, "flows": { "type": "array", "items": { "$ref": "#/components/schemas/RunPlanFlowSelection" }, "minItems": 1, "description": "Customer flows to include in this run plan. The same flow can appear more than once with a different persona override, different variables, or different `overrides`: attaching it once per value of one property is how you compare that property without a template." }, "personas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "minItems": 1, "description": "Personas to include in this run plan. Required with `scenarios`; ignored with `flows`, where each variant carries its own persona." }, "agentEndpoints": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "minItems": 1, "description": "Agent endpoints to include in this run plan" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/RunPlanMetricRef" }, "minItems": 1, "description": "Metric definitions to include in this run plan. Reference each by `id` (UUID) or `slug`.\n\nOptional when the attached `flows` carry the grading: metrics a flow declares itself\n(with `includeFlowMetrics`), or the Agent Expectations and Keypad Entry metrics a run\nadds for flows with expectations or expected keypad entries (with\n`includeAutomaticMetrics`). A plan with nothing to grade is rejected with a 400." }, "includeFlowMetrics": { "type": "boolean", "default": true, "description": "Also collect each attached flow's own metrics, on top of the `metrics` named here.\n\nDefault true, which is what you want when you brought your own flows and their graders.\nSet false for a run whose metric list is meant to be exhaustive: a template like Load\nTesting or Voicemail deliberately grades a narrow set, and inheriting every flow metric\non top multiplies analysis cost across the volume without adding signal.\n\nGET /v1/simulation/template returns the value each template expects.", "example": true }, "includeAutomaticMetrics": { "type": "boolean", "default": true, "description": "Let the run add metrics by itself off the attached flows, on top of the `metrics` named here.\n\nTwo attach this way today: Agent Expectations wherever an attached flow has agent expectations\nwritten on it, and Keypad Entry wherever one has steps where the agent is expected to press keys.\nBoth grade something authored on the flow that nothing else measures, which is why it is on by\ndefault.\n\nSet false when the `metrics` list is meant to be exhaustive: a plan testing only whether the caller\ncan complete the flow may not want the agent graded on its expectations as well. False also pins\nthe plan against any automatic metric Roark adds later.", "example": true }, "comparisonProperty": { "type": [ "string", "null" ], "enum": [ "ACCENT", "AGE", "BACKGROUND_NOISE", "BACKGROUND_NOISE_VOLUME", "BASE_EMOTION", "CONFIRMATION_STYLE", "GENDER", "INTENT_CLARITY", "LANGUAGE", "INTERRUPTION", "MEMORY_RELIABILITY", "RESPONSE_TIMING", "SPEECH_CLARITY", "SPEECH_PACE" ], "description": "The property this run plan investigates: the one thing its arms differ by.\n\nSet it and the run report compares the arms on that property, so a run answers \"what did\nbackground noise cost\" rather than just \"what did each arm score\". Every value is a field\nalready recorded on each call, so the report can label an arm `CRYING_BABY` rather than\nrepeating a flow variant's title.\n\nOmit it and the report still compares when it can: it detects which property varies across\nthe arms. Setting it is what tells the written summary what you were trying to find out,\nwhich detection cannot infer.", "example": "BACKGROUND_NOISE" }, "comparisonBaseline": { "type": [ "string", "null" ], "description": "The reference value of `comparisonProperty`, for example `NONE` for `BACKGROUND_NOISE` or\n`NORMAL` for `SPEECH_PACE`: shown first in the results. Must be a value that property can take.\nWhether a value did significantly worse does not depend on it: that is decided against every\nother value combined (see `sweepAttribution`).\n\nStored rather than assumed, so the report can say \"compared against US accent\" instead of\nimplying Roark decided which value is normal. Omit it and the property's own norm is used,\nas the dashboard prefills it, or none when your `comparisonValues` leave the norm out.\n`GENDER` has no norm, so choose the one you are testing against.", "example": "NONE" }, "comparisonValues": { "type": "array", "items": { "anyOf": [ { "type": "string", "minLength": 1, "description": "A value of `comparisonProperty`, run as its plain arm." }, { "$ref": "#/components/schemas/ComparisonArm" } ] }, "minItems": 1, "description": "The arms to run, for a plan that sweeps `comparisonProperty`. This is what the plan costs: the\nflow is attached once per arm, so ten arms is ten times the calls of one.\n\nAttach each flow once, as you would without a comparison: the plan builds the arms, running\nthe happy path or edge cases you selected under every arm. Built arms need at least 5 calls\nper arm (`iterationCount` times the test cases per arm), or the plan is refused with `400`.\nFlows that all carry `overrides` on `comparisonProperty` already are the arms and are kept as\nyou wrote them; a mix of flows with and without one is refused.\n\nEach entry is one arm. A bare value runs it plain: `\"CITY\"`. An object runs the value with\nsomething pinned on that arm only, such as a noise level per bed: `{ \"value\": \"OFFICE\",\n\"backgroundNoiseVolume\": 0.6 }` plays OFFICE at 60% while the other beds keep the default.\nList a value more than once with different pins to run it as several arms: DRIVING at 0.7 and\nDRIVING at 1 are two arms, reported as `Driving (70% noise)` and `Driving (100% noise)`, and\n`\"DRIVING\"` beside them keeps the plain arm too. The sweep still varies one property; what an\narm pins is part of \"everything else\" for that arm only, so the report still compares the arms\non `comparisonProperty`.\n\nOmit it to run every value the property has, plain, which for `ACCENT` is more than twenty.\nA `comparisonBaseline` outside the values listed is rejected, because it would anchor every\ndifference to an arm the run never made. A value the property cannot take, a pin the sweep\ncannot account for, or the same arm listed twice is rejected with `400`.\n\nNot stored as a field: the arms are the values. Reading the plan back returns them as its\nflow attachments, each with its pins as `overrides`.", "example": [ "NONE", { "value": "OFFICE", "backgroundNoiseVolume": 0.6 }, { "value": "DRIVING", "backgroundNoiseVolume": 0.7 }, { "value": "DRIVING", "backgroundNoiseVolume": 1 } ] }, "enrichWithLiveConversation": { "type": "boolean", "default": false, "description": "Merge the customer's own recording of the real call into each simulation, so metrics can be\nscored against the live leg as well as the simulated one. This is the API equivalent of the\ndashboard's live-enrichment toggle.\n\nWith this on, the run provisions a phone number and holds each call open for up to 15 minutes\nwaiting for a matching call to be posted to POST /v1/call. A call matches on the provisioned\nnumber (`roarkPhoneNumber` on the job) with a start time inside the simulation window. If\nnothing arrives, the simulation still completes and any `LIVE`-sourced metric produces no value.\n\nRequired by any metric whose `requiresLiveConversation` is true: without it that metric is\nsilently skipped.", "example": false }, "notifications": { "$ref": "#/components/schemas/SimulationPlanNotificationsInput", "description": "Email and/or Slack delivery of each run's report once it is ready, with the report PDF attached. Each run announces once, off its first report. Omitted: no notifications." }, "autoRun": { "type": "boolean", "default": false, "deprecated": true, "description": "Deprecated: use POST /v1/simulation/run, which starts a run and accepts runtime `variables` as well. This flag runs the plan with only the values pinned on it.", "example": false } }, "required": [ "name", "direction", "maxSimulationDurationSeconds", "agentEndpoints" ], "additionalProperties": false, "title": "New plan", "description": "Describe a run plan: what to call, who calls it, and what to measure.", "example": { "name": "Background noise sweep", "direction": "OUTBOUND", "iterationCount": 5, "maxSimulationDurationSeconds": 300, "agentEndpoints": [ { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } ], "metrics": [ { "slug": "call_outcome" } ], "flows": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "happyPath": true } ], "comparisonProperty": "BACKGROUND_NOISE", "comparisonValues": [ "NONE", "CITY", "TRAIN" ], "comparisonBaseline": "NONE" } }, "SimulationPlanNotificationsInput": { "type": "object", "properties": { "email": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether each run's report is emailed when it is ready." }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50, "default": [], "description": "Addresses to email (at most 50), Roark users or not: the email attaches the report PDF. Empty emails every member of the project.", "example": [ "qa-lead@example.com" ] } }, "required": [ "enabled" ], "additionalProperties": false, "default": { "enabled": true, "recipients": [] } }, "slack": { "type": "array", "items": { "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1, "description": "The Slack channel id", "example": "C07ABCDEF12" }, "channelName": { "type": "string", "minLength": 1, "description": "The channel name, shown in Roark", "example": "qa-reports" } }, "required": [ "channelId", "channelName" ], "additionalProperties": false }, "maxItems": 10, "default": [], "description": "Channels in the project's connected Slack workspace to post the report to (at most 10). Slack must be connected to the project first." } }, "additionalProperties": false, "description": "Where each run's report announces itself once it is ready.", "example": { "email": { "enabled": true, "recipients": [] }, "slack": [ { "channelId": "C07ABCDEF12", "channelName": "qa-reports" } ] } }, "CreateRunPlanFromTemplate": { "type": "object", "properties": { "template": { "type": "string", "minLength": 1, "description": "The template to run, as listed by GET /v1/simulation/template.", "example": "health-check" }, "agentEndpoints": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "minItems": 1, "description": "The agent endpoints to call. No template can know these." }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direction of the simulation (INBOUND or OUTBOUND)", "example": "INBOUND" }, "flows": { "type": "array", "items": { "$ref": "#/components/schemas/RunPlanFlowSelection" }, "minItems": 1, "description": "The flows to run, in the same shape a run plan takes them.\n\nRequired when the template lists no flows of its own: it presets what to measure, and this\nsays what to measure it on. Optional when it does, where these REPLACE the ones it would\nhave run, so you can narrow a suite to the cases you care about. Either way,\nGET /v1/simulation/template lists the flows and variant ids each template covers.\n\nOn a template that sweeps a property, every value runs exactly what you select here: the\nhappy path, the edge cases you name, or `edgeCases: \"ALL\"`. Each selected case is a call per\nvalue per iteration, so naming three edge cases triples the run.", "example": [ { "slug": "sf-prompt-injection", "edgeCases": [ { "slug": "data-embedded-injection" } ] }, { "id": "3a1d5e7c-9b2f-4a6d-8c31-5f7e9d0a2b4c", "happyPath": true } ] }, "iterationCount": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Runs per test case (1-10000). Defaults to 1, or to 6 for a template that sweeps a property. A sweep needs at least 5 calls per value (test cases per value times iterations) to compare its values, and a lower count is refused with 400.", "example": 6 }, "maxConcurrentJobs": { "type": "integer", "minimum": 1, "default": 5, "description": "Maximum number of concurrent simulation jobs", "example": 5 }, "maxSimulationDurationSeconds": { "type": "integer", "minimum": 1, "description": "Defaults to the template's `defaultMaxSimulationDurationSeconds`, as returned by GET /v1/simulation/template." }, "silenceTimeoutSeconds": { "type": "integer", "minimum": 1, "default": 30, "description": "Timeout in seconds for silence detection", "example": 30 }, "maxNoResponseRetries": { "type": "integer", "minimum": 0, "maximum": 10, "default": 0, "description": "How many more times to run a test case when the agent under test never responds: it never speaks on a call or never replies in a chat (0-10). 0 turns retries off. Failed checks and failures on Roark’s side are never retried.\n\nEach retry is a separate attempt, billed like any other, so a plan retrying N times can place up to N + 1 calls per test case.\nEvery silent attempt stays on the run with its own call; the run settles once each test case has a final attempt, and the\nagent never spoke verdict is judged on each test case’s last attempt.", "example": 2 }, "noResponseRetryBackoffSeconds": { "type": "integer", "minimum": 30, "maximum": 600, "default": 90, "description": "Seconds a retry waits before it dials (30-600). Only used when `maxNoResponseRetries` is above 0.", "example": 90 }, "endCallPhrases": { "type": "array", "items": { "type": "string" }, "default": [ "goodbye" ], "description": "Phrases that trigger end of call. Empty array disables the feature.", "example": [ "goodbye" ] }, "endCallReasons": { "type": "array", "items": { "type": "string" }, "description": "Semantic conditions that trigger end of call. The LLM evaluates the conversation against these conditions. Defaults to the template's `defaultEndCallReasons`, as returned by GET /v1/simulation/template. Pass an empty array to run with none.", "example": [ "Order has been confirmed by the agent" ] }, "executionMode": { "type": "string", "enum": [ "PARALLEL", "SEQUENTIAL_SAME_RUN_PLAN", "SEQUENTIAL_PROJECT" ], "default": "PARALLEL", "description": "Execution mode (PARALLEL or SEQUENTIAL)", "example": "PARALLEL" }, "enrichWithLiveConversation": { "type": "boolean", "default": false, "description": "Merge the customer's own recording of the real call into each simulation, so metrics can be\nscored against the live leg as well as the simulated one. This is the API equivalent of the\ndashboard's live-enrichment toggle.\n\nWith this on, the run provisions a phone number and holds each call open for up to 15 minutes\nwaiting for a matching call to be posted to POST /v1/call. A call matches on the provisioned\nnumber (`roarkPhoneNumber` on the job) with a start time inside the simulation window. If\nnothing arrives, the simulation still completes and any `LIVE`-sourced metric produces no value.\n\nRequired by any metric whose `requiresLiveConversation` is true: without it that metric is\nsilently skipped.", "example": false }, "additionalMetrics": { "type": "array", "items": { "$ref": "#/components/schemas/RunPlanMetricRef" }, "minItems": 1, "description": "Metrics to collect on top of the template's own, referenced by `id` or `slug` like a plan's `metrics`. The template's metrics and checks always run; naming one of them here again keeps it once, with the success criteria you set on it.", "example": [ { "slug": "call_ended_prematurely" } ] }, "comparisonValues": { "type": "array", "items": { "anyOf": [ { "type": "string", "minLength": 1, "description": "A value of `comparisonProperty`, run as its plain arm." }, { "$ref": "#/components/schemas/ComparisonArm" } ] }, "minItems": 1, "description": "The arms of the sweep to run, for a template that sweeps one (GET /v1/simulation/template\nreturns `sweep.property` for those that do). This is what the run costs: the flow is called\nonce per arm, so ten arms is ten times the calls of one.\n\nOmit it to run every value the property has, plain, which for `accent-handling` is more than\ntwenty. Send a subset to narrow it, for example the three accents you actually serve. An\nobject entry pins something on that arm only, such as a noise level per bed on\n`background-noise-robustness`: `{ \"value\": \"OFFICE\", \"backgroundNoiseVolume\": 0.6 }` plays\nOFFICE at 60% while the other beds keep the default. See `POST /v1/simulation/plan`.", "example": [ "US", "GB", "IN" ] }, "comparisonBaseline": { "type": [ "string", "null" ], "description": "The sweep's reference value, shown first in the results. Defaults to the template's own\nbaseline, as returned by GET /v1/simulation/template. Whether a value did significantly worse\ndoes not depend on it: that is decided against every other value combined.\n\nSend it with `comparisonValues` and it must be one of them, or the request is rejected:\nanchoring every difference to an arm the run never made would measure it against nothing.\nLeave it out and the template's own baseline is used, and quietly dropped if your\nnarrowing excluded it, since that one you did not choose.", "example": "US" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "ask": { "type": "string", "minLength": 1, "description": "The question the caller asks the agent.", "example": "What are your holiday hours?" }, "expect": { "type": "string", "minLength": 1, "description": "The answer the agent must give, judged against the transcript.", "example": "We're closed on public holidays." } }, "required": [ "ask", "expect" ] }, "minItems": 1, "description": "For the `question-answer-check` template: the questions to ask and the answer expected for each. Every question runs as its own graded call." }, "personaId": { "type": "string", "format": "uuid", "description": "For `question-answer-check`: the persona that asks the questions." }, "environmentId": { "type": "string", "format": "uuid", "description": "For `question-answer-check`: the environment the calls run in." }, "name": { "type": "string", "minLength": 1, "description": "Name of the run plan. Defaults to the template's name and the date." }, "notifications": { "$ref": "#/components/schemas/SimulationPlanNotificationsInput", "description": "Email and/or Slack delivery of each run's report once it is ready, with the report PDF attached. Each run announces once, off its first report. Omitted: no notifications." } }, "required": [ "template", "agentEndpoints", "direction" ], "additionalProperties": false, "title": "From template", "description": "Save one of the built-in templates as a run plan, configured for your agent, without running it.", "example": { "template": "accent-handling", "name": "Accents we serve", "direction": "OUTBOUND", "agentEndpoints": [ { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } ], "flows": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "happyPath": true } ], "comparisonValues": [ "US", "GB", "IN" ] } }, "UpdateRunPlanInput": { "type": "object", "properties": { "isHidden": { "type": "boolean", "description": "Whether this plan is hidden from GET /v1/simulation/plan.\n\nA run started without `saveAsPlan` creates a hidden plan to carry it. Send\n`{ \"name\": \"...\", \"isHidden\": false }` to keep that configuration as a reusable plan,\nwhich is what the app does when you save a one-off run." }, "name": { "type": "string", "minLength": 1, "description": "Name of the run plan" }, "description": { "type": "string", "description": "Description of the run plan" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direction of the simulation (INBOUND or OUTBOUND)" }, "iterationCount": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Number of iterations to run for each test case (1-10000)" }, "maxConcurrentJobs": { "type": "integer", "minimum": 1, "description": "Maximum number of concurrent simulation jobs" }, "maxSimulationDurationSeconds": { "type": "integer", "minimum": 1, "description": "Maximum duration in seconds for each simulation" }, "silenceTimeoutSeconds": { "type": "integer", "minimum": 1, "description": "Timeout in seconds for silence detection" }, "maxNoResponseRetries": { "type": "integer", "minimum": 0, "maximum": 10, "description": "How many more times to run a test case when the agent under test never responds: it never speaks on a call or never replies in a chat (0-10). 0 turns retries off. Failed checks and failures on Roark’s side are never retried.\n\nEach retry is a separate attempt, billed like any other, so a plan retrying N times can place up to N + 1 calls per test case.\nEvery silent attempt stays on the run with its own call; the run settles once each test case has a final attempt, and the\nagent never spoke verdict is judged on each test case’s last attempt." }, "noResponseRetryBackoffSeconds": { "type": "integer", "minimum": 30, "maximum": 600, "description": "Seconds a retry waits before it dials (30-600). Only used when `maxNoResponseRetries` is above 0." }, "endCallPhrases": { "type": "array", "items": { "type": "string" }, "description": "Phrases that trigger end of call. Empty array disables the feature." }, "endCallReasons": { "type": "array", "items": { "type": "string" }, "description": "Semantic conditions that trigger end of call. The LLM evaluates the conversation against these conditions. Empty array disables the feature." }, "executionMode": { "type": "string", "enum": [ "PARALLEL", "SEQUENTIAL_SAME_RUN_PLAN", "SEQUENTIAL_PROJECT" ], "description": "Execution mode (PARALLEL or SEQUENTIAL)" }, "scenarios": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Scenario ID" }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Template variables for this scenario instance. The same scenario can appear multiple times with different variables.", "example": { "customerName": "John Doe", "appointmentDate": "2024-02-15" } } }, "required": [ "id" ] }, "deprecated": true, "description": "Deprecated: use `flows` instead. Replaces the scenarios on this run plan. Omit to leave them unchanged; send an empty array to detach them all, which is how a scenario-based plan is moved over to flows." }, "flows": { "type": "array", "items": { "$ref": "#/components/schemas/RunPlanFlowSelection" }, "description": "Replaces the customer flows attached to this run plan. Omit to leave them unchanged; send an empty array to detach them all." }, "personas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "minItems": 1, "description": "Personas to include in this run plan" }, "agentEndpoints": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "minItems": 1, "description": "Agent endpoints to include in this run plan" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/RunPlanMetricRef" }, "minItems": 1, "description": "Metric definitions to include in this run plan. Reference each by `id` (UUID) or `slug`." }, "enrichWithLiveConversation": { "type": "boolean", "description": "Whether to merge the customer's own live recording into each simulation of this plan." }, "includeFlowMetrics": { "type": "boolean", "description": "Whether to also collect each attached flow's own metrics, on top of this plan's list." }, "includeAutomaticMetrics": { "type": "boolean", "description": "Whether to let the run add metrics by itself off the attached flows. See `POST /v1/simulation/plan`." }, "comparisonProperty": { "type": [ "string", "null" ], "enum": [ "ACCENT", "AGE", "BACKGROUND_NOISE", "BACKGROUND_NOISE_VOLUME", "BASE_EMOTION", "CONFIRMATION_STYLE", "GENDER", "INTENT_CLARITY", "LANGUAGE", "INTERRUPTION", "MEMORY_RELIABILITY", "RESPONSE_TIMING", "SPEECH_CLARITY", "SPEECH_PACE" ], "description": "The property this plan investigates. Send `null` to clear the comparison; omit the field to\nleave it unchanged. See `POST /v1/simulation/plan`.\n\nThe pair moves together. Sending `comparisonProperty` without `comparisonBaseline` keeps the\nstored baseline when the property is unchanged and the baseline is still one of the values\nbeing run. Otherwise it becomes the new property's norm, or `null` when that norm is not\nbeing run either, because a baseline is a value of one specific property." }, "comparisonBaseline": { "type": [ "string", "null" ], "description": "The reference value, shown first in the results. See `POST /v1/simulation/plan`.\n\nA real value cannot be sent on its own: the property it belongs to decides which values are\nlegal, and an omitted property means \"leave unchanged\", which this endpoint cannot check a\nbaseline against. Send `comparisonProperty` with it, or get a `400`.\n\n`null` on its own IS allowed, and clears just the baseline while leaving the property set.\nNothing needs validating when clearing, and a property with no baseline is a real state: the\nreport falls back to that property's own norm, and `GENDER` has no norm to fall back to." }, "comparisonValues": { "type": "array", "items": { "anyOf": [ { "type": "string", "minLength": 1, "description": "A value of `comparisonProperty`, run as its plain arm." }, { "$ref": "#/components/schemas/ComparisonArm" } ] }, "minItems": 1, "description": "The arms to run. See `POST /v1/simulation/plan`.\n\nOmitting it keeps the arms the plan already has, pins included, so an edit that only renames\nthe plan never widens a sweep you deliberately narrowed, and never multiplies what it costs.\nSend it with `comparisonProperty` and `flows`, which the arms are rebuilt from.", "example": [ "NONE", { "value": "OFFICE", "backgroundNoiseVolume": 0.6 }, { "value": "DRIVING", "backgroundNoiseVolume": 0.7 }, { "value": "DRIVING", "backgroundNoiseVolume": 1 } ] }, "notifications": { "oneOf": [ { "$ref": "#/components/schemas/SimulationPlanNotificationsInput" }, { "type": "null" } ], "description": "Replaces where each run's report is sent, as a whole. `null` turns notifications off. Omitted keeps them. A run whose report already went out is not sent again." } }, "additionalProperties": false, "description": "Input for updating an existing simulation run plan" }, "GetSimulationPlanJobsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "simulationRunPlanJobId": { "type": "string", "format": "uuid", "description": "ID of the simulation run plan job" }, "simulationRunPlanId": { "type": "string", "format": "uuid", "description": "ID of the simulation run plan" }, "status": { "type": "string", "enum": [ "PENDING", "QUEUED", "CREATING_SNAPSHOTS", "CREATING_SIMULATIONS", "PREPARING_CAPACITY", "RUNNING_SIMULATIONS", "COMPLETED", "FAILED", "TIMED_OUT", "CANCELLED", "CANCELLING", "ENDING_SIMULATIONS" ], "description": "Job status" }, "triggeredBy": { "type": "string", "enum": [ "SCHEDULED", "USER_TRIGGERED_FROM_UI", "RE_RUN", "TRIGGERED_FROM_API", "SYSTEM" ], "description": "How the job was triggered (SCHEDULED, USER_TRIGGERED_FROM_UI, TRIGGERED_FROM_API, RE_RUN, or SYSTEM). SYSTEM is used when the job was started by an internal admin acting on behalf of the project (the original user identity is not exposed)." }, "createdAt": { "type": "string", "description": "When the job was created" }, "startedAt": { "type": [ "string", "null" ], "description": "When the job started" }, "endedAt": { "type": [ "string", "null" ], "description": "When the job ended" } }, "required": [ "simulationRunPlanJobId", "simulationRunPlanId", "status", "triggeredBy", "createdAt" ] } }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of matching plan jobs" }, "hasMore": { "type": "boolean", "description": "Whether there are more results available" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor to use for fetching the next page" } }, "required": [ "total", "hasMore" ] } }, "required": [ "data", "pagination" ], "description": "Paginated list of simulation run plan jobs" }, "GetSimulationPlanJobResponse": { "type": "object", "properties": { "simulationRunPlanJobId": { "type": "string", "format": "uuid", "description": "ID of the simulation run plan job" }, "simulationRunPlanId": { "type": "string", "format": "uuid", "description": "ID of the simulation run plan" }, "status": { "type": "string", "enum": [ "PENDING", "QUEUED", "CREATING_SNAPSHOTS", "CREATING_SIMULATIONS", "PREPARING_CAPACITY", "RUNNING_SIMULATIONS", "COMPLETED", "FAILED", "TIMED_OUT", "CANCELLED", "CANCELLING", "ENDING_SIMULATIONS" ], "description": "Job status" }, "createdAt": { "type": "string", "description": "When the job was created" }, "startedAt": { "type": [ "string", "null" ], "description": "When the job started" }, "endedAt": { "type": [ "string", "null" ], "description": "When the job ended" }, "simulationJobs": { "type": "array", "items": { "type": "object", "properties": { "simulationJobId": { "type": "string", "format": "uuid", "description": "Simulation job ID" }, "status": { "type": "string", "enum": [ "PENDING", "QUEUED", "PROCESSING", "COMPLETED", "FAILED", "TIMED_OUT", "CANCELLED", "CANCELLING", "RETRY_SCHEDULED" ], "description": "Job status. `RETRY_SCHEDULED` is a retry of a simulation your agent never spoke on, waiting out the plan’s `noResponseRetryBackoffSeconds` before it dials." }, "processingStatus": { "type": "string", "enum": [ "PENDING", "RESERVING_CAPACITY", "CONNECTING", "WAITING_FOR_OUTBOUND_CALL", "SIMULATING", "ENDING", "ANALYZING", "WAITING_FOR_LIVE_CONVERSATION", "EVALUATING", "COLLECTING_METRICS", "COMPLETED" ], "description": "Processing status. PENDING until the job starts connecting." }, "callId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the call created for this simulation job. Null if the call has not been created yet." }, "roarkPhoneNumber": { "type": [ "string", "null" ], "description": "Phone number provisioned by Roark for this simulation job in E.164 format. Null if the simulation job is queued and has not been assigned a phone number yet." }, "persona": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the persona" }, "name": { "type": "string", "description": "The name the agent will identify as during conversations" }, "displayName": { "type": [ "string", "null" ], "description": "Label shown in place of the name across the dashboard (e.g. a short descriptor like \"Irate Escalator\"). The persona still identifies as `name` on calls. Omit or set null to display the name itself." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of the persona" }, "language": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ], "description": "Primary language ISO 639-1 code for the persona" }, "secondaryLanguage": { "type": [ "string", "null" ], "enum": [ "EN" ], "description": "Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish)" }, "understoodLanguages": { "type": "array", "items": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ] }, "minItems": 1, "description": "Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support." }, "accent": { "type": "string", "enum": [ "US", "US_X_SOUTH", "GB", "ES", "DE", "IN", "FR", "NL", "SA", "GR", "AU", "IT", "ID", "TH", "JP", "NZ", "PH", "SG", "MY", "HK", "TR", "PT", "IL" ], "description": "Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants" }, "age": { "type": "string", "enum": [ "CHILD", "TEENAGER", "ADULT", "ELDERLY" ], "default": "ADULT", "description": "How old the caller sounds and behaves. Only ages the persona's accent has a voice for are accepted; defaults to ADULT, which every accent supports." }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender of the persona" }, "backgroundNoise": { "type": "string", "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "default": "NONE", "description": "Background noise setting" }, "speechPace": { "type": "string", "enum": [ "SUPER_SLOW", "SLOW", "NORMAL", "FAST", "SUPER_FAST" ], "default": "NORMAL", "description": "Speech pace of the persona" }, "speechClarity": { "type": "string", "enum": [ "CLEAR", "VAGUE", "RAMBLING" ], "default": "CLEAR", "description": "Speech clarity of the persona" }, "hasDisfluencies": { "type": "boolean", "default": false, "description": "Whether the persona uses filler words like \"um\" and \"uh\"" }, "baseEmotion": { "type": "string", "enum": [ "NEUTRAL", "CHEERFUL", "CONFUSED", "FRUSTRATED", "SKEPTICAL", "RUSHED", "DISTRACTED", "ANGRY", "ANXIOUS", "SAD" ], "default": "NEUTRAL", "description": "Base emotional state of the persona" }, "intentClarity": { "type": "string", "enum": [ "CLEAR", "INDIRECT", "VAGUE" ], "default": "CLEAR", "description": "How clearly the persona expresses their intentions" }, "confirmationStyle": { "type": "string", "enum": [ "EXPLICIT", "VAGUE" ], "default": "EXPLICIT", "description": "How the persona confirms information" }, "memoryReliability": { "type": "string", "enum": [ "HIGH", "LOW" ], "default": "HIGH", "description": "How reliable the persona's memory is" }, "responseTiming": { "type": "string", "enum": [ "RELAXED", "NORMAL", "QUICK", "BARGE_IN" ], "default": "NORMAL", "description": "Deprecated and inert: it no longer affects the call. It set how long the persona waited once the agent stopped talking, and measured across production simulations it moved the reply gap by less than the noise floor, because model and speech latency dominate it. Every persona now uses one voice-activity profile. Use `interruption` for a caller who talks over the agent. Still accepted and stored so existing clients keep working. BARGE_IN is stored as `responseTiming: QUICK` with `interruption: OCCASIONAL`." }, "interruption": { "type": "string", "enum": [ "OFF", "BACKCHANNEL", "OCCASIONAL", "HEAVY" ], "default": "OFF", "description": "How much the persona talks over the agent while it is still speaking. OFF waits its turn. BACKCHANNEL makes listening noises (\"mm-hm\") over the agent without taking the floor, which tests whether the agent wrongly stops for them. OCCASIONAL adds cutting in on some long agent turns, HEAVY on most of them. Timing is randomised per turn, so two runs of the same persona do not interrupt at identical moments." }, "backstoryPrompt": { "type": [ "string", "null" ], "description": "Background story and behavioral patterns for the persona", "example": "A busy professional calling during lunch break" }, "idleMessages": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Messages the persona will say when the agent goes silent during a call. null = \"Automatic\": language-appropriate defaults are used at call time." }, "idleTimeoutSeconds": { "type": "integer", "minimum": 5, "maximum": 60, "default": 10, "description": "Seconds of silence before the persona sends an idle message" }, "idleMessageMaxSpokenCount": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3, "description": "Maximum number of idle messages the persona will send before giving up" }, "idleMessageResetCountOnUserSpeechEnabled": { "type": "boolean", "default": true, "description": "Whether the idle message counter resets when the agent speaks" }, "properties": { "type": "object", "additionalProperties": {}, "default": {}, "description": "Additional custom properties about the persona", "example": { "age": 35, "zipCode": "94105", "occupation": "Software Engineer" } }, "phoneNumber": { "type": "string", "description": "The E.164 number every call with this persona uses, when Roark has pinned one for your project. Present only when set; read-only.", "example": "+19312830919" }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "description": "Last update timestamp" } }, "required": [ "id", "name", "language", "understoodLanguages", "accent", "age", "gender", "backgroundNoise", "speechPace", "speechClarity", "hasDisfluencies", "baseEmotion", "intentClarity", "confirmationStyle", "memoryReliability", "responseTiming", "interruption", "idleMessages", "idleTimeoutSeconds", "idleMessageMaxSpokenCount", "idleMessageResetCountOnUserSpeechEnabled", "properties", "createdAt", "updatedAt" ] }, "backgroundNoise": { "$ref": "#/components/schemas/SimulationJobBackgroundNoise" }, "scenario": { "$ref": "#/components/schemas/ScenarioResponse" }, "agentEndpoint": { "$ref": "#/components/schemas/AgentEndpointResponse" }, "invalidation": { "oneOf": [ { "$ref": "#/components/schemas/SimulationJobInvalidation" }, { "type": "null" } ], "description": "Present when the result does not count (a strict flow went off script and its policy invalidated the run); null otherwise." }, "retryOfSimulationJobId": { "type": [ "string", "null" ], "format": "uuid", "description": "The simulation this one retries, because your agent never spoke on it. Null on a test case’s first attempt." }, "attemptNumber": { "type": "integer", "exclusiveMinimum": 0, "description": "This simulation’s place among its test case’s attempts: 1 for the first, 2 for the first retry. Above 1 only when the plan retries simulations your agent never spoke on." }, "scheduledAt": { "type": [ "string", "null" ], "description": "When a `RETRY_SCHEDULED` retry dials, ISO 8601. Null on a first attempt." }, "createdAt": { "type": "string", "description": "When the simulation job was created" }, "startedAt": { "type": [ "string", "null" ], "description": "When the simulation job started" }, "completedAt": { "type": [ "string", "null" ], "description": "When the simulation job completed" } }, "required": [ "simulationJobId", "status", "processingStatus", "persona", "backgroundNoise", "scenario", "agentEndpoint", "invalidation", "retryOfSimulationJobId", "attemptNumber", "scheduledAt", "createdAt" ] }, "description": "List of simulation jobs (calls) in this run plan job, every attempt included: a simulation your agent never spoke on stays listed after a retry replaces it." }, "attemptSummary": { "$ref": "#/components/schemas/SimulationRunPlanJobAttemptSummary" }, "pendingRetries": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationRunPlanJobPendingRetry" }, "description": "Retries waiting out their backoff, soonest first. While this is not empty the run is waiting, not stuck: it settles only once every test case has a final attempt. Empty when nothing is scheduled." }, "verdict": { "oneOf": [ { "$ref": "#/components/schemas/SimulationRunPlanJobVerdict" }, { "type": "null" } ], "description": "Pass/fail verdict for this run. Null when the plan carried no pass/fail metric to judge, so an absent verdict means \"nothing to judge\", never a pass." }, "sweepAttribution": { "oneOf": [ { "$ref": "#/components/schemas/SimulationRunPlanJobSweepAttribution" }, { "type": "null" } ], "description": "For a run that swept a property: which check failures the property caused, which were not specific to it, and which values had too few simulations to compare. Null for a run that swept nothing, and until the run has ended." } }, "required": [ "simulationRunPlanJobId", "simulationRunPlanId", "status", "createdAt", "simulationJobs", "attemptSummary", "pendingRetries" ], "description": "Simulation run plan job with all associated simulation jobs", "example": { "simulationRunPlanJobId": "7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f", "simulationRunPlanId": "9a8b7c6d-5e4f-3210-abcd-ef9876543210", "status": "RUNNING_SIMULATIONS", "createdAt": "2024-01-15T10:30:00Z", "startedAt": "2024-01-15T10:30:15Z", "endedAt": null, "simulationJobs": [ { "simulationJobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "COMPLETED", "processingStatus": "COMPLETED", "callId": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "roarkPhoneNumber": "+15551234567", "invalidation": null, "retryOfSimulationJobId": null, "attemptNumber": 1, "scheduledAt": null, "persona": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Sarah Johnson - Anxious Patient", "displayName": "Anxious Patient", "language": "EN", "secondaryLanguage": null, "understoodLanguages": [ "EN" ], "accent": "US", "age": "ADULT", "gender": "FEMALE", "backgroundNoise": "OFFICE", "speechPace": "NORMAL", "speechClarity": "CLEAR", "hasDisfluencies": false, "baseEmotion": "FRUSTRATED", "intentClarity": "CLEAR", "confirmationStyle": "EXPLICIT", "memoryReliability": "HIGH", "responseTiming": "NORMAL", "interruption": "OCCASIONAL", "backstoryPrompt": "A busy professional calling during lunch break", "idleMessages": null, "idleTimeoutSeconds": 10, "idleMessageMaxSpokenCount": 3, "idleMessageResetCountOnUserSpeechEnabled": true, "properties": { "age": "35", "zipCode": "94105" }, "createdAt": "2025-01-10T12:00:00.000Z", "updatedAt": "2025-01-10T12:00:00.000Z" }, "backgroundNoise": { "backgroundNoise": "CITY", "backgroundNoiseVolume": 0.1, "source": "ENVIRONMENT" }, "scenario": { "id": "f8e7d6c5-b4a3-9281-7069-5f4e3d2c1b0a", "description": "Patient calling to schedule an urgent dental appointment" }, "agentEndpoint": { "id": "3c2b1a09-8f7e-6d5c-4b3a-291807060504", "name": "PHONE", "phoneNumber": "+15555551234", "type": "PHONE" }, "createdAt": "2024-01-15T10:30:20Z", "startedAt": "2024-01-15T10:30:25Z", "completedAt": "2024-01-15T10:32:45Z" } ], "attemptSummary": { "testCaseCount": 1, "attemptCount": 1, "silentAttemptCount": 0, "retryCount": 0, "stillSilentTestCaseCount": 0 }, "pendingRetries": [] } }, "SimulationJobBackgroundNoise": { "type": "object", "properties": { "backgroundNoise": { "type": "string", "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "description": "The noise bed the simulated caller was placed with. NONE when the call ran in silence." }, "backgroundNoiseVolume": { "type": "number", "minimum": 0, "maximum": 1, "description": "Linear gain (0..1) the bed played at. 1 is as loud as the caller’s voice." }, "source": { "type": "string", "enum": [ "ENVIRONMENT", "PERSONA" ], "description": "`ENVIRONMENT` when the flow’s environment decided the bed (a sweep arm, or an environment with noise), `PERSONA` when the persona’s own setting did." } }, "required": [ "backgroundNoise", "backgroundNoiseVolume", "source" ], "description": "The background noise the call actually ran with. `persona.backgroundNoise` is only what the persona was set to; a flow’s environment overrides it, and on a background-noise sweep every arm’s persona says NONE while the arms differ here. Filter by arm on this field." }, "ScenarioResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Scenario ID" }, "description": { "type": [ "string", "null" ], "description": "Scenario description" } }, "required": [ "id" ], "description": "Scenario used in a simulation" }, "AgentEndpointResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Agent endpoint ID" }, "name": { "type": "string", "description": "Agent endpoint name" }, "phoneNumber": { "type": [ "string", "null" ], "description": "Agent endpoint phone number" }, "type": { "type": "string", "enum": [ "PHONE", "WEBSOCKET", "LIVEKIT", "SMALL_WEBRTC", "ELEVENLABS_WS", "KORE", "GOOGLE_CES", "DAILY" ], "description": "Agent endpoint type" } }, "required": [ "id", "name", "phoneNumber", "type" ], "description": "Agent endpoint used in a simulation" }, "SimulationJobInvalidation": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "SCRIPT_DIVERGED", "REQUIRED_STEP_NOT_REACHED", "REQUIRED_STAGE_INCOMPLETE", "CALLER_NEVER_TOOK_OVER", "AGENT_NEVER_SPOKE" ], "description": "Why the result does not count. `SCRIPT_DIVERGED`: a strict flow went off script at a step whose off-script policy is HANG_UP_INVALIDATE. `REQUIRED_STAGE_INCOMPLETE`: the call ended before it got through a stage its flow requires. `CALLER_NEVER_TOOK_OVER`: the call opened on the persona of a preceding flow, which never handed the phone to the persona under test, so none of that persona's properties were exercised. `AGENT_NEVER_SPOKE`: your agent answered and never said a word (it hung up within seconds, or the line stayed silent until our caller gave up), so there was nothing to grade." }, "detail": { "type": [ "string", "null" ], "description": "One sentence: where the script was left and what your agent did instead." }, "invalidatedAt": { "type": "string", "description": "When the run was invalidated." } }, "required": [ "reason", "invalidatedAt" ], "description": "Present when the run was invalidated: the call ended before a step its flow requires for a valid run, or a strict flow went off script at a step whose policy invalidates the run. It keeps its transcript and recording, but nothing scored it and it is excluded from every run total." }, "SimulationRunPlanJobAttemptSummary": { "type": "object", "properties": { "testCaseCount": { "type": "integer", "minimum": 0, "description": "Test cases in the run. Each one has a single final attempt that its result is read from." }, "attemptCount": { "type": "integer", "minimum": 0, "description": "Every simulation placed, retries included. Each is a separate, billed call." }, "silentAttemptCount": { "type": "integer", "minimum": 0, "description": "Simulations your agent never spoke on, including the ones a retry replaced." }, "retryCount": { "type": "integer", "minimum": 0, "description": "Simulations placed as a retry of one your agent never spoke on." }, "stillSilentTestCaseCount": { "type": "integer", "minimum": 0, "description": "Test cases whose final attempt your agent still never spoke on. This is what the `AGENT_NEVER_SPOKE` verdict failure counts." } }, "required": [ "testCaseCount", "attemptCount", "silentAttemptCount", "retryCount", "stillSilentTestCaseCount" ], "description": "The run’s simulations against its test cases. Differs from a plain job count only when the plan retries simulations your agent never spoke on." }, "SimulationRunPlanJobPendingRetry": { "type": "object", "properties": { "simulationJobId": { "type": "string", "format": "uuid", "description": "The scheduled retry." }, "attemptNumber": { "type": "integer", "exclusiveMinimum": 0, "description": "Its place among its test case’s attempts, 2 for the first retry." }, "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "description": "The most attempts a test case can get on this run: the plan’s `maxNoResponseRetries` plus 1." }, "scheduledAt": { "type": [ "string", "null" ], "description": "When the retry dials, ISO 8601. It may wait longer behind the run’s concurrency limit." } }, "required": [ "simulationJobId", "attemptNumber", "maxAttempts", "scheduledAt" ], "description": "A retry of a simulation your agent never spoke on, waiting out its backoff before it dials." }, "SimulationRunPlanJobVerdict": { "type": "object", "properties": { "passed": { "type": "boolean", "description": "Whether every check cleared its own `minPassRate` (and the run completed with full coverage).\nUse this as the CI exit status.\n\nNever derived from `score`: a run can score 95 and still fail, or score 40 and still pass." }, "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "The run's headline quality number, 0-100: the mean of each check's own pass rate.\n\nEvery check weighs the same, however many simulations it evaluated, which is the same way\n`passed` treats them. It is the number the Roark dashboard shows for this run.\n\nREPORTING ONLY, for dashboards and trend lines. Nothing is judged against it. Null when\nnothing was evaluated." }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationRunPlanJobCheck" }, "description": "Every check the run was judged on, with its rate and the minimum it had to reach.\n\nThresholds and authored yes/no metrics only. See `SimulationRunPlanJobCheck` for why a\nprovider reading is not one." }, "failures": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationRunPlanJobVerdictFailure" }, "description": "Every criterion the run missed. Empty when it passed." } }, "required": [ "passed", "score", "checks", "failures" ], "description": "Pass/fail verdict for the run, judged against the success criteria pinned on the run plan when the run started.", "example": { "passed": false, "score": 85, "checks": [ { "metricDefinitionId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "metricName": "silence duration < 500ms", "passRate": 100, "minPassRate": 40, "inherited": false, "passedSims": 10, "evaluatedSims": 10, "passed": true }, { "metricDefinitionId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "metricName": "word count < 1000", "passRate": 70, "minPassRate": 80, "inherited": false, "passedSims": 7, "evaluatedSims": 10, "passed": false } ], "failures": [ { "type": "METRIC_BELOW_MIN_PASS_RATE", "metricDefinitionId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "metricName": "word count < 1000", "passRate": 70, "minPassRate": 80, "inherited": false } ] } }, "SimulationRunPlanJobCheck": { "type": "object", "properties": { "metricDefinitionId": { "type": "string", "format": "uuid" }, "metricName": { "type": [ "string", "null" ] }, "passRate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "This check's own pass rate, 0-100: the share of sims it evaluated that passed it. Null when it evaluated nothing." }, "minPassRate": { "type": "number", "minimum": 0, "maximum": 100, "description": "THE BAR it was judged against: the share of the run's simulations it had to pass." }, "inherited": { "type": "boolean", "description": "Whether `minPassRate` is the 80% default (`true`) or a minimum this metric set for itself." }, "passedSims": { "type": "integer", "minimum": 0 }, "evaluatedSims": { "type": "integer", "minimum": 0 }, "passed": { "type": "boolean", "description": "`passRate >= minPassRate`." } }, "required": [ "metricDefinitionId", "passRate", "minPassRate", "inherited", "passedSims", "evaluatedSims", "passed" ], "description": "How one check did. Present for every check the run was judged on, passing or not.\n\nA check is a metric that yields a pass/fail: a threshold (`Silence Duration <= 2s`) or a\nyes/no metric you authored. Provider readings such as `Comprehension Failure` are\nobservations, not checks: their `true` is whatever the underlying field happens to mean, so\nthey carry no passing side and never appear here. Put a threshold on one to judge it." }, "SimulationRunPlanJobVerdictFailure": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "RUN_NOT_COMPLETED" }, "status": { "type": "string", "enum": [ "PENDING", "QUEUED", "CREATING_SNAPSHOTS", "CREATING_SIMULATIONS", "PREPARING_CAPACITY", "RUNNING_SIMULATIONS", "COMPLETED", "FAILED", "TIMED_OUT", "CANCELLED", "CANCELLING", "ENDING_SIMULATIONS" ], "description": "The status the run actually ended in." } }, "required": [ "type", "status" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "INCOMPLETE_COVERAGE" }, "evaluatedCalls": { "type": "integer", "minimum": 0 }, "expectedCalls": { "type": "integer", "minimum": 0 } }, "required": [ "type", "evaluatedCalls", "expectedCalls" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "AGENT_NEVER_SPOKE" }, "neverSpokeCalls": { "type": "integer", "minimum": 0, "description": "Test cases your agent never spoke on, judged on each test case’s last attempt: a silent simulation a retry later reached your agent on does not count here." }, "totalCalls": { "type": "integer", "minimum": 0, "description": "Every test case of the run whose last attempt reached your agent." }, "maxShare": { "type": "number", "minimum": 0, "maximum": 100, "description": "The largest share of simulations, 0-100, your agent may never speak on while the run can pass." }, "agentName": { "type": [ "string", "null" ], "description": "The agent as the run tested it. Null when the simulations tested more than one agent." }, "silentAttempts": { "type": "integer", "minimum": 0, "description": "Every simulation your agent never spoke on, including the ones a retry replaced. Above `neverSpokeCalls` only when the plan retries silent simulations (`maxNoResponseRetries`)." } }, "required": [ "type", "neverSpokeCalls", "totalCalls", "maxShare" ], "description": "Your agent never spoke on more than `maxShare` percent of the run. Those simulations are left out of every check, so the run fails on them whatever the checks say." }, { "type": "object", "properties": { "type": { "type": "string", "const": "METRIC_NOT_EVALUATED" }, "metricDefinitionId": { "type": "string", "format": "uuid" }, "metricName": { "type": [ "string", "null" ], "description": "The check’s name, for rendering the failure." } }, "required": [ "type", "metricDefinitionId" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "METRIC_BELOW_MIN_PASS_RATE" }, "metricDefinitionId": { "type": "string", "format": "uuid" }, "metricName": { "type": [ "string", "null" ], "description": "The check’s name, for rendering the failure." }, "passRate": { "type": "number", "minimum": 0, "maximum": 100 }, "minPassRate": { "type": "number", "minimum": 0, "maximum": 100 }, "inherited": { "type": "boolean", "description": "Whether the missed minimum was the 80% default (`true`) or this metric's own." } }, "required": [ "type", "metricDefinitionId", "passRate", "minPassRate", "inherited" ] } ], "description": "One reason the run failed. Every reason is a hard fail: the run passes only when this list is empty." }, "SimulationRunPlanJobSweepAttribution": { "type": "object", "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationRunPlanJobSweepArm" }, "description": "Every value of the swept property, baseline first." }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationRunPlanJobSweepCheck" }, "description": "Every check the run was graded on: `PROPERTY_ATTRIBUTABLE` first, then `FOUND_UNATTRIBUTED`, then `WITHIN_NOISE`." }, "testableValueCount": { "type": "integer", "minimum": 0, "description": "How many values had enough counted simulations to be compared." }, "testedComparisonCount": { "type": "integer", "minimum": 0, "description": "How many value and check pairs were actually tested. A value can have enough simulations and still go untested (no other value graded that check, or too few verdicts on it). When this is 0 no comparison ran, so an empty `worseValues` everywhere means nothing was tested, not that no value did worse." }, "minimumDetectableGap": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Roughly how many percentage points more often a value would need to fail than the rest of the run to be flagged at this sample size. Optimistic: it uses simulation counts rather than the verdicts on each check and ignores the correction, so checks graded on fewer simulations need larger gaps. Large when few simulations ran per value: finding no significant difference then means the run could not see one, not that none exists." }, "caveats": { "type": "array", "items": { "type": "string" }, "description": "Plain sentences on what this run could not see, ready to show to a reader." }, "neverSpokeValues": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationRunPlanJobSweepNeverSpokeValue" }, "description": "The values your agent never spoke on significantly more often than the rest of the run, most significant first, tested the same way as `worseValues`. Empty on a run with no silent simulations." }, "minArmCalls": { "type": "integer", "exclusiveMinimum": 0, "description": "Counted simulations a value needs before it is compared." }, "falseDiscoveryRate": { "type": "number", "minimum": 0, "maximum": 1, "description": "The Benjamini-Hochberg false discovery rate the comparisons are held to." }, "foundUnattributedFailureRate": { "type": "number", "minimum": 0, "maximum": 100, "description": "The overall failure rate, 0-100, at which a check with no standout value is reported as `FOUND_UNATTRIBUTED`." } }, "required": [ "values", "checks", "testableValueCount", "testedComparisonCount", "minimumDetectableGap", "caveats", "neverSpokeValues", "minArmCalls", "falseDiscoveryRate", "foundUnattributedFailureRate" ], "description": "For a run that swept a property (accent, background noise, speech pace and so on): which check failures the property caused.\n\nEach value is compared with every other value combined using a one-sided Fisher exact test, and every comparison in the run is corrected together with Benjamini-Hochberg. A value is only called worse when the difference is statistically significant, so a value that happened to fail a few more simulations by chance is not reported as a problem. Invalidated simulations and simulations that failed on the Roark platform are left out.", "example": { "values": [ { "key": "ACCENT=US", "value": "US", "label": "American", "isBaseline": true, "attempted": 3, "counted": 2, "silentAttempts": 0, "retries": 0, "testable": false, "score": 50 }, { "key": "ACCENT=IN", "value": "IN", "label": "Indian", "isBaseline": false, "attempted": 8, "counted": 8, "silentAttempts": 0, "retries": 0, "testable": true, "score": 62.5 }, { "key": "ACCENT=GB", "value": "GB", "label": "British", "isBaseline": false, "attempted": 8, "counted": 8, "silentAttempts": 0, "retries": 0, "testable": true, "score": 68.8 } ], "checks": [ { "metricDefinitionId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "metricName": "Voice consistency", "attribution": "FOUND_UNATTRIBUTED", "failed": 7, "evaluated": 18, "failureRate": 38.9, "worseValues": [] } ], "testableValueCount": 2, "testedComparisonCount": 8, "minimumDetectableGap": 45, "caveats": [ "American had fewer than 5 counted calls, so it is shown but not compared.", "With about 8 calls per value, only large differences can be detected: a value would need to fail roughly 45 points more often than the rest to be reliably flagged. Smaller effects may exist and go unseen." ], "neverSpokeValues": [], "minArmCalls": 5, "falseDiscoveryRate": 0.1, "foundUnattributedFailureRate": 20 } }, "SimulationRunPlanJobSweepArm": { "type": "object", "properties": { "key": { "type": "string", "description": "The arm's identity: the override signature its calls ran with, e.g. `BACKGROUND_NOISE=DRIVING;BACKGROUND_NOISE_VOLUME=0.7`. Join on this rather than on `value`: a sweep can run one value as several arms (Driving at 70% and at 100%), and those share a value." }, "value": { "type": "string", "description": "The stored value of the swept property, e.g. `US`." }, "label": { "type": "string", "description": "The value in words, with what else the arm pinned, e.g. `American` or `Driving (70% noise)`." }, "isBaseline": { "type": "boolean", "description": "Whether this is the baseline the plan named." }, "attempted": { "type": "integer", "minimum": 0, "description": "Simulations run at this value. Simulations that failed on the Roark platform are left out, since they say nothing about your agent." }, "counted": { "type": "integer", "minimum": 0, "description": "Simulations that actually tested the property: not invalidated, and graded by at least one check. Only these are used in the comparison." }, "silentAttempts": { "type": "integer", "minimum": 0, "description": "Of `attempted`, the simulations your agent never spoke on, whether or not a retry followed. They are invalidated, so they are never in `counted`." }, "retries": { "type": "integer", "minimum": 0, "description": "Of `attempted`, the retries of simulations your agent never spoke on. Zero unless the plan retries silent simulations." }, "testable": { "type": "boolean", "description": "Whether this value had at least `minArmCalls` counted simulations. A value below that is \"insufficient data\": it is reported with its numbers but never compared or ranked, because a rate from one or two calls cannot be told apart from luck." }, "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "The mean of each check's pass rate at this value, 0-100, the same rule as the run's `score`. Descriptive only: a lower score alone never makes a value worse. Null when nothing counted." } }, "required": [ "key", "value", "label", "isBaseline", "attempted", "counted", "silentAttempts", "retries", "testable", "score" ], "description": "One value of the swept property." }, "SimulationRunPlanJobSweepCheck": { "type": "object", "properties": { "metricDefinitionId": { "type": "string", "format": "uuid" }, "metricName": { "type": "string" }, "attribution": { "type": "string", "enum": [ "PROPERTY_ATTRIBUTABLE", "FOUND_UNATTRIBUTED", "WITHIN_NOISE" ], "description": "How this check relates to the swept property:\n\n- `PROPERTY_ATTRIBUTABLE`: at least one value failed it significantly more often than every other value combined. `worseValues` names them. This is the only case in which a value is called worse.\n- `FOUND_UNATTRIBUTED`: no value stands out, but the check failed on at least `foundUnattributedFailureRate`% of counted simulations overall. A real issue with the agent on which no value stood out, so the run cannot tie it to the property. It does not show the property had no effect: a small run may be unable to see one.\n- `WITHIN_NOISE`: neither. Any differences between values are within what chance produces." }, "failed": { "type": "integer", "minimum": 0 }, "evaluated": { "type": "integer", "minimum": 0 }, "failureRate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Share of counted simulations across every value that failed the check, 0-100." }, "worseValues": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationRunPlanJobSweepArmCheck" }, "description": "The values significantly worse than the rest, most significant first. Empty unless `attribution` is `PROPERTY_ATTRIBUTABLE`." } }, "required": [ "metricDefinitionId", "metricName", "attribution", "failed", "evaluated", "failureRate", "worseValues" ], "description": "How one check's failures relate to the swept property." }, "SimulationRunPlanJobSweepArmCheck": { "type": "object", "properties": { "key": { "type": "string", "description": "The arm's identity: the override signature its calls ran with, e.g. `BACKGROUND_NOISE=DRIVING;BACKGROUND_NOISE_VOLUME=0.7`. Join on this rather than on `value`: a sweep can run one value as several arms (Driving at 70% and at 100%), and those share a value." }, "value": { "type": "string" }, "label": { "type": "string" }, "failed": { "type": "integer", "minimum": 0 }, "evaluated": { "type": "integer", "minimum": 0 }, "failureRate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Share of the counted simulations at this value that failed the check, 0-100." }, "restFailureRate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "The same share across every other value combined, 0-100. This is what the value is compared with." }, "adjustedPValue": { "type": "number", "minimum": 0, "maximum": 1, "description": "How likely a difference at least this large would be by chance alone, after correcting for every comparison in the run (Benjamini-Hochberg). The value is called worse only when this is at most `falseDiscoveryRate`." } }, "required": [ "key", "value", "label", "failed", "evaluated", "failureRate", "restFailureRate", "adjustedPValue" ], "description": "A value that failed a check significantly more often than the rest of the run." }, "SimulationRunPlanJobSweepNeverSpokeValue": { "type": "object", "properties": { "key": { "type": "string", "description": "The arm's identity: the override signature its calls ran with, e.g. `BACKGROUND_NOISE=DRIVING;BACKGROUND_NOISE_VOLUME=0.7`. Join on this rather than on `value`: a sweep can run one value as several arms (Driving at 70% and at 100%), and those share a value." }, "value": { "type": "string" }, "label": { "type": "string" }, "silentAttempts": { "type": "integer", "minimum": 0, "description": "Simulations at this value your agent never spoke on, retried or not." }, "attempted": { "type": "integer", "minimum": 0, "description": "Simulations run at this value." }, "retries": { "type": "integer", "minimum": 0, "description": "Retries placed at this value because your agent never spoke." }, "restSilentAttempts": { "type": "integer", "minimum": 0, "description": "Simulations your agent never spoke on across every other value combined." }, "restAttempted": { "type": "integer", "minimum": 0, "description": "Simulations run across every other value combined." }, "adjustedPValue": { "type": "number", "minimum": 0, "maximum": 1, "description": "How likely a difference at least this large would be by chance alone, after correcting across the values (Benjamini-Hochberg)." } }, "required": [ "key", "value", "label", "silentAttempts", "attempted", "retries", "restSilentAttempts", "restAttempted", "adjustedPValue" ], "description": "A value your agent never spoke on significantly more often than the rest of the run." }, "CancelSimulationPlanJobResponse": { "type": "object", "properties": { "simulationRunPlanJobId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "QUEUED", "CREATING_SNAPSHOTS", "CREATING_SIMULATIONS", "PREPARING_CAPACITY", "RUNNING_SIMULATIONS", "COMPLETED", "FAILED", "TIMED_OUT", "CANCELLED", "CANCELLING", "ENDING_SIMULATIONS" ], "description": "The job status after the request. Unchanged when the run had already finished." }, "cancelled": { "type": "boolean", "description": "True when this request stopped the run. False when it had already finished, which is not an error." } }, "required": [ "simulationRunPlanJobId", "status", "cancelled" ], "description": "Result of cancelling a simulation plan job", "example": { "simulationRunPlanJobId": "7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f", "status": "CANCELLED", "cancelled": true } }, "RunSimulationPlanBody": { "type": "object", "properties": { "variables": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" }, "description": "Global format: key-value pairs that apply to ALL scenarios in the plan", "example": { "orderNumber": "12345", "environment": "staging" } }, { "type": "array", "items": { "type": "object", "properties": { "flowId": { "type": "string", "format": "uuid", "description": "A customer flow this plan runs." }, "happyPath": { "type": "boolean", "const": true, "description": "Narrow to the flow's happy path." }, "edgeCaseId": { "type": "string", "format": "uuid", "description": "Narrow to one edge case of that flow." }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The values to apply." } }, "required": [ "flowId", "variables" ] }, "description": "Values scoped to the flows this plan runs", "example": [ { "flowId": "550e8400-e29b-41d4-a716-446655440000", "variables": { "orderNumber": "12345" } }, { "flowId": "550e8400-e29b-41d4-a716-446655440000", "happyPath": true, "variables": { "orderNumber": "55555" } }, { "flowId": "550e8400-e29b-41d4-a716-446655440000", "edgeCaseId": "7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e", "variables": { "orderNumber": "67890" } } ] }, { "type": "array", "items": { "type": "object", "properties": { "scenarioId": { "type": "string", "format": "uuid", "description": "ID of the scenario to apply variables to" }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Key-value pairs for this scenario" } }, "required": [ "scenarioId", "variables" ] }, "deprecated": true, "description": "Deprecated, for plans built on scenarios. Plans built on customer flows target them with `flowId` instead.", "example": [ { "scenarioId": "550e8400-e29b-41d4-a716-446655440000", "variables": { "orderNumber": "12345" } }, { "scenarioId": "7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e", "variables": { "orderNumber": "67890" } } ] } ], "description": "Values for the {{variables}} the run resolves, overriding whatever the plan has pinned.\n\nAn object applies them to the whole run:\n\n { \"orderNumber\": \"12345\", \"tier\": \"gold\" }\n\nAn array applies them per flow, or to just its happy path or one of its edge cases, when a single\nset will not do. Each entry carries what it applies to:\n\n [\n { \"flowId\": \"550e8400-...\", \"variables\": { \"orderNumber\": \"12345\" } },\n { \"flowId\": \"550e8400-...\", \"happyPath\": true, \"variables\": { \"orderNumber\": \"55555\" } },\n { \"flowId\": \"550e8400-...\", \"edgeCaseId\": \"7a3d2e1f-...\", \"variables\": { \"orderNumber\": \"67890\" } }\n ]\n\nAn entry that narrows to neither covers everything that flow resolves. A flow this plan does not\nattach, or an edge case that does not belong to the flow, is rejected rather than ignored.\n\nA plan built on scenarios rather than customer flows targets them the same way, with `scenarioId` in\nplace of `flowId`. That form is deprecated alongside scenarios themselves, and still accepted so runs\nagainst those plans keep working." } }, "description": "Optional request body for running a simulation plan with runtime variables" }, "SimulationRunResults": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/SimulationRunResultsRun" }, "summary": { "$ref": "#/components/schemas/SimulationRunResultsSummary" }, "verdict": { "oneOf": [ { "$ref": "#/components/schemas/SimulationRunPlanJobVerdict" }, { "type": "null" } ], "description": "Null until the run ends, and for a run with no check to judge." }, "attemptSummary": { "$ref": "#/components/schemas/SimulationRunPlanJobAttemptSummary" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationRunMetricResult" }, "description": "Checks first, then other metrics." }, "calls": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationRunCallResult" } }, "breakdowns": { "type": "object", "properties": { "byAgent": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationRunResultsGroup" } }, "byPersona": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationRunResultsGroup" } } }, "required": [ "byAgent", "byPersona" ] }, "comparison": { "oneOf": [ { "$ref": "#/components/schemas/SimulationRunResultsComparison" }, { "type": "null" } ], "description": "Null when there is no earlier run of the plan to compare against." }, "sweepAttribution": { "oneOf": [ { "$ref": "#/components/schemas/SimulationRunPlanJobSweepAttribution" }, { "type": "null" } ], "description": "For a run that swept a property: which values the failures concentrate on. Null otherwise." }, "debrief": { "oneOf": [ { "$ref": "#/components/schemas/SimulationRunDebrief" }, { "type": "null" } ], "description": "The latest debrief. Null when none was generated, e.g. a run with no graded calls." } }, "required": [ "run", "summary", "verdict", "attemptSummary", "metrics", "calls", "breakdowns", "comparison", "sweepAttribution", "debrief" ], "description": "Everything the run report shows, in one response.", "example": { "run": { "simulationRunPlanJobId": "7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f", "simulationRunPlanId": "550e8400-e29b-41d4-a716-446655440000", "simulationRunPlanName": "Appointment booking regression", "runNumber": 42, "status": "COMPLETED", "triggeredBy": "TRIGGERED_FROM_API", "createdAt": "2026-10-11T14:00:00.000Z", "startedAt": "2026-10-11T14:00:03.000Z", "endedAt": "2026-10-11T14:04:41.000Z", "durationMs": 278000 }, "summary": { "totalCalls": 10, "countedCalls": 10, "completedCalls": 10, "evaluatedCalls": 10, "passedCalls": 7, "failedCalls": 3, "callPassRate": 70, "score": 85, "checkPassRate": 85 }, "verdict": null, "attemptSummary": { "testCaseCount": 10, "attemptCount": 10, "silentAttemptCount": 0, "retryCount": 0, "stillSilentTestCaseCount": 0 }, "metrics": [ { "metricDefinitionId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "metricId": "booked_appointment_check", "name": "Booked appointment", "outputType": "BOOLEAN", "isCheck": true, "unitSymbol": null, "evaluatedCalls": 10, "sampleSize": 10, "check": { "passedCalls": 7, "failedCalls": 3, "evaluatedCalls": 10, "passRate": 70 }, "numeric": null, "distribution": [ { "value": "true", "count": 7 }, { "value": "false", "count": 3 } ] } ], "calls": [ { "simulationJobId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "callId": "6e7f8a9b-0c1d-4e2f-9a3b-4c5d6e7f8a9b", "status": "COMPLETED", "counted": true, "attemptNumber": 1, "retryOfSimulationJobId": null, "personaName": "Ana", "agentName": "Front desk", "durationMs": 94000, "passed": false, "checks": [ { "metricDefinitionId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "metricName": "Booked appointment", "passed": false } ], "values": [] } ], "breakdowns": { "byAgent": [], "byPersona": [] }, "comparison": null, "sweepAttribution": null, "debrief": null } }, "SimulationRunResultsRun": { "type": "object", "properties": { "simulationRunPlanJobId": { "type": "string", "format": "uuid" }, "simulationRunPlanId": { "type": "string", "format": "uuid" }, "simulationRunPlanName": { "type": [ "string", "null" ], "description": "The run plan’s name. Null when the plan has since been deleted." }, "runNumber": { "type": [ "integer", "null" ], "description": "Per-project run number, shown as SR-42 in the app." }, "status": { "type": "string", "enum": [ "PENDING", "QUEUED", "CREATING_SNAPSHOTS", "CREATING_SIMULATIONS", "PREPARING_CAPACITY", "RUNNING_SIMULATIONS", "COMPLETED", "FAILED", "TIMED_OUT", "CANCELLED", "CANCELLING", "ENDING_SIMULATIONS" ] }, "triggeredBy": { "type": "string", "enum": [ "SCHEDULED", "USER_TRIGGERED_FROM_UI", "RE_RUN", "TRIGGERED_FROM_API", "SYSTEM" ] }, "createdAt": { "type": "string" }, "startedAt": { "type": [ "string", "null" ] }, "endedAt": { "type": [ "string", "null" ] }, "durationMs": { "type": [ "integer", "null" ], "description": "Wall-clock run time. Null until the run ends." } }, "required": [ "simulationRunPlanJobId", "simulationRunPlanId", "simulationRunPlanName", "runNumber", "status", "triggeredBy", "createdAt", "startedAt", "endedAt", "durationMs" ] }, "SimulationRunResultsSummary": { "type": "object", "properties": { "totalCalls": { "type": "integer", "description": "Every simulation of the run, retries included." }, "countedCalls": { "type": "integer", "description": "Simulations whose results count: all but the invalidated ones." }, "completedCalls": { "type": "integer", "description": "Counted simulations that connected and produced a conversation." }, "evaluatedCalls": { "type": "integer", "description": "Counted simulations at least one check graded." }, "passedCalls": { "type": "integer", "description": "Evaluated simulations that passed every check." }, "failedCalls": { "type": "integer", "description": "Evaluated simulations that failed at least one check." }, "callPassRate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "passedCalls / evaluatedCalls, 0-100. Null when nothing was evaluated." }, "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "The run’s score: the mean of each check’s pass rate, the same number as `verdict.score`. 0-100. Null when nothing was evaluated." }, "checkPassRate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Every (check, simulation) verdict pooled. 0-100. Null when nothing was evaluated." } }, "required": [ "totalCalls", "countedCalls", "completedCalls", "evaluatedCalls", "passedCalls", "failedCalls", "callPassRate", "score", "checkPassRate" ] }, "SimulationRunMetricResult": { "type": "object", "properties": { "metricDefinitionId": { "type": "string", "format": "uuid" }, "metricId": { "type": "string", "description": "The metric’s slug." }, "name": { "type": "string" }, "outputType": { "type": "string", "enum": [ "COUNT", "NUMERIC", "BOOLEAN", "SCALE", "TEXT", "CLASSIFICATION", "OFFSET" ] }, "isCheck": { "type": "boolean", "description": "A threshold: one of the checks the run is judged on." }, "unitSymbol": { "type": [ "string", "null" ], "description": "Unit of `numeric`, e.g. `ms`." }, "evaluatedCalls": { "type": "integer", "description": "Counted simulations with at least one value." }, "sampleSize": { "type": "integer", "description": "Values across those simulations. A per-turn metric has several per call." }, "check": { "type": [ "object", "null" ], "properties": { "passedCalls": { "type": "integer" }, "failedCalls": { "type": "integer" }, "evaluatedCalls": { "type": "integer" }, "passRate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "0-100. Null when nothing was evaluated." } }, "required": [ "passedCalls", "failedCalls", "evaluatedCalls", "passRate" ], "description": "The check’s tally. Null for a metric that is not a check." }, "numeric": { "type": [ "object", "null" ], "properties": { "average": { "type": "number" }, "median": { "type": "number" }, "p95": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "average", "median", "p95", "min", "max" ], "description": "For NUMERIC, SCALE, COUNT and OFFSET metrics. Null when nothing was captured, or without the `metric:read` permission." }, "distribution": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "value", "count" ] }, "description": "How many values took each reading, for BOOLEAN, SCALE and CLASSIFICATION metrics. Null without the `metric:read` permission." } }, "required": [ "metricDefinitionId", "metricId", "name", "outputType", "isCheck", "unitSymbol", "evaluatedCalls", "sampleSize", "check", "numeric", "distribution" ] }, "SimulationRunCallResult": { "type": "object", "properties": { "simulationJobId": { "type": "string", "format": "uuid" }, "callId": { "type": [ "string", "null" ], "format": "uuid", "description": "Use with GET /v1/call/{callId} for the transcript, recording and every metric value." }, "status": { "type": "string", "enum": [ "QUEUED", "CONNECTING", "IN_CALL", "PROCESSING", "COMPLETED", "ERROR", "TIMED_OUT", "CANCELLED", "INVALIDATED", "NOT_RUN" ], "description": "QUEUED, CONNECTING, IN_CALL and PROCESSING while the simulation runs. Once settled: COMPLETED, TIMED_OUT (ran to the maximum duration, still graded), ERROR (failed on the agent’s side), NOT_RUN (failed on Roark’s side), CANCELLED, or INVALIDATED (ran, but does not count)." }, "counted": { "type": "boolean", "description": "False for an invalidated simulation: listed, never scored." }, "attemptNumber": { "type": "integer" }, "retryOfSimulationJobId": { "type": [ "string", "null" ], "format": "uuid" }, "personaName": { "type": [ "string", "null" ] }, "agentName": { "type": [ "string", "null" ] }, "durationMs": { "type": [ "integer", "null" ] }, "passed": { "type": [ "boolean", "null" ], "description": "Passed every check that graded it. Null when no check graded it, or it does not count." }, "checks": { "type": "array", "items": { "type": "object", "properties": { "metricDefinitionId": { "type": "string", "format": "uuid" }, "metricName": { "type": "string" }, "passed": { "type": "boolean" } }, "required": [ "metricDefinitionId", "metricName", "passed" ] } }, "values": { "type": "array", "items": { "type": "object", "properties": { "metricDefinitionId": { "type": "string", "format": "uuid" }, "metricName": { "type": "string" }, "outputType": { "type": "string", "enum": [ "COUNT", "NUMERIC", "BOOLEAN", "SCALE", "TEXT", "CLASSIFICATION", "OFFSET" ] }, "participantRole": { "type": [ "string", "null" ], "enum": [ "AGENT", "CUSTOMER", "SIMULATED_CUSTOMER", "BACKGROUND_SPEAKER" ] }, "value": { "anyOf": [ { "type": "number" }, { "type": "boolean" }, { "type": "string" }, { "type": "null" } ] }, "reasoning": { "type": [ "string", "null" ] } }, "required": [ "metricDefinitionId", "metricName", "outputType", "participantRole", "value", "reasoning" ] }, "description": "Call-level values of the run’s other metrics. Empty without the `metric:read` permission. Per-turn values are on GET /v1/call/{callId}/metrics." } }, "required": [ "simulationJobId", "callId", "status", "counted", "attemptNumber", "retryOfSimulationJobId", "personaName", "agentName", "durationMs", "passed", "checks", "values" ] }, "SimulationRunResultsGroup": { "type": "object", "properties": { "key": { "type": "string", "description": "The agent or persona ID." }, "label": { "type": "string" }, "calls": { "type": "integer", "description": "Counted simulations in the group." }, "evaluatedCalls": { "type": "integer" }, "passedCalls": { "type": "integer" }, "callPassRate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "0-100. Null when nothing was evaluated." }, "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "The group’s own score. 0-100. Null when nothing was evaluated." } }, "required": [ "key", "label", "calls", "evaluatedCalls", "passedCalls", "callPassRate", "score" ] }, "SimulationRunResultsComparison": { "type": "object", "properties": { "baselineRun": { "type": "object", "properties": { "simulationRunPlanJobId": { "type": "string", "format": "uuid" }, "runNumber": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "PENDING", "QUEUED", "CREATING_SNAPSHOTS", "CREATING_SIMULATIONS", "PREPARING_CAPACITY", "RUNNING_SIMULATIONS", "COMPLETED", "FAILED", "TIMED_OUT", "CANCELLED", "CANCELLING", "ENDING_SIMULATIONS" ] }, "endedAt": { "type": [ "string", "null" ] } }, "required": [ "simulationRunPlanJobId", "runNumber", "status", "endedAt" ] }, "baselineSource": { "type": "string", "enum": [ "PREVIOUS_RUN", "REQUESTED" ], "description": "REQUESTED when `compareToJobId` picked the baseline, PREVIOUS_RUN otherwise." }, "currentScore": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "baselineScore": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "scoreDelta": { "type": [ "number", "null" ], "description": "Current minus baseline, in points." }, "currentCallPassRate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "baselineCallPassRate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "callPassRateDelta": { "type": [ "number", "null" ] }, "checks": { "type": "array", "items": { "type": "object", "properties": { "metricDefinitionId": { "type": "string", "format": "uuid" }, "metricName": { "type": "string" }, "currentPassRate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "baselinePassRate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "delta": { "type": [ "number", "null" ] } }, "required": [ "metricDefinitionId", "metricName", "currentPassRate", "baselinePassRate", "delta" ] }, "description": "Every check either run was graded on. A side that did not grade it reads null." } }, "required": [ "baselineRun", "baselineSource", "currentScore", "baselineScore", "scoreDelta", "currentCallPassRate", "baselineCallPassRate", "callPassRateDelta", "checks" ] }, "SimulationRunDebrief": { "type": "object", "properties": { "debriefId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "GENERATING", "READY", "FAILED" ], "description": "PENDING and GENERATING while it is written (usually a few minutes), then READY or FAILED." }, "errorMessage": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "completedAt": { "type": [ "string", "null" ] }, "report": { "oneOf": [ { "$ref": "#/components/schemas/SimulationRunDebriefReport" }, { "type": "null" } ], "description": "Present once READY." } }, "required": [ "debriefId", "status", "errorMessage", "createdAt", "completedAt", "report" ], "description": "The run’s written debrief: executive summary, failure themes and recommendations. Generated automatically when a run with graded calls settles.", "example": { "debriefId": "3c2b1a09-8f7e-4d6c-9b5a-4e3d2c1b0a9f", "status": "GENERATING", "errorMessage": null, "createdAt": "2026-10-11T14:05:12.000Z", "completedAt": null, "report": null } }, "SimulationRunDebriefReport": { "type": "object", "properties": { "generatedAt": { "type": "string" }, "verdict": { "type": "string", "enum": [ "PASSED", "THRESHOLD_FAILED" ] }, "verdictSummary": { "type": "string", "description": "One-paragraph verdict, e.g. \"Not ready to promote. ...\"" }, "executiveSummary": { "type": "object", "properties": { "paragraphs": { "type": "array", "items": { "type": "string" } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "heading": { "type": [ "string", "null" ] }, "body": { "type": "string" } }, "required": [ "heading", "body" ] } } }, "required": [ "paragraphs", "sections" ] }, "keyFindings": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "body": { "type": "string" }, "callIds": { "type": "array", "items": { "type": "string" }, "description": "The calls the finding is about." } }, "required": [ "title", "body", "callIds" ] } }, "wentWell": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "body": { "type": "string" }, "callIds": { "type": "array", "items": { "type": "string" }, "description": "The calls the finding is about." } }, "required": [ "title", "body", "callIds" ] } }, "themes": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "severity": { "type": "string", "enum": [ "HIGH", "MEDIUM", "LOW" ] }, "impact": { "type": [ "string", "null" ], "enum": [ "CRITICAL", "HIGH", "MEDIUM", "LOW" ] }, "prevalence": { "type": [ "string", "null" ], "enum": [ "WIDESPREAD", "RECURRING", "ISOLATED" ] }, "lifecycle": { "type": [ "string", "null" ], "enum": [ "NEW", "PERSISTENT", "IMPROVING", "FIXED" ] }, "affectedCallCount": { "type": "integer" }, "totalCallCount": { "type": "integer" }, "checkNames": { "type": "array", "items": { "type": "string" } }, "rootCauseChannel": { "type": [ "string", "null" ], "enum": [ "PROMPT", "VOICE_CONFIG", "STT", "SPEECH_MODEL", "LLM_MODEL", "INFRA", "EXTERNAL" ] }, "analysis": { "type": "string" }, "callIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "slug", "title", "severity", "impact", "prevalence", "lifecycle", "affectedCallCount", "totalCallCount", "checkNames", "rootCauseChannel", "analysis", "callIds" ] }, "description": "Failure themes, clustered across the run’s failing calls." }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "order": { "type": "integer" }, "title": { "type": "string" }, "body": { "type": "string" }, "severity": { "type": [ "string", "null" ], "enum": [ "HIGH", "MEDIUM", "LOW" ] }, "channel": { "type": [ "string", "null" ], "enum": [ "PROMPT", "VOICE_CONFIG", "STT", "SPEECH_MODEL", "LLM_MODEL", "INFRA", "EXTERNAL" ] }, "currentText": { "type": [ "string", "null" ], "description": "For a prompt fix: the text to replace." }, "suggestedText": { "type": [ "string", "null" ], "description": "For a prompt fix: the replacement." }, "themeSlugs": { "type": "array", "items": { "type": "string" } } }, "required": [ "order", "title", "body", "severity", "channel", "currentText", "suggestedText", "themeSlugs" ] } }, "trend": { "type": [ "object", "null" ], "properties": { "baselineRunPlanJobId": { "type": "string" }, "baselineRunNumber": { "type": [ "integer", "null" ] }, "rows": { "type": "array", "items": { "type": "object", "properties": { "checkName": { "type": "string" }, "previousPassRate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "currentPassRate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "lifecycle": { "type": [ "string", "null" ], "enum": [ "NEW", "PERSISTENT", "IMPROVING", "FIXED" ] } }, "required": [ "checkName", "previousPassRate", "currentPassRate", "lifecycle" ] } } }, "required": [ "baselineRunPlanJobId", "baselineRunNumber", "rows" ], "description": "The checks against the previous run, as of generation." } }, "required": [ "generatedAt", "verdict", "verdictSummary", "executiveSummary", "keyFindings", "wentWell", "themes", "recommendations", "trend" ] }, "GenerateSimulationRunDebriefInput": { "type": "object", "properties": { "regenerate": { "type": "boolean", "default": false, "description": "Generate a new debrief even when a ready one exists. Without it, an existing ready or in-progress debrief is returned as-is." } } }, "SimulationRunCost": { "type": "object", "properties": { "jobId": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "const": "usd" }, "totalUsdMicros": { "type": "integer", "description": "Total billable spend for the run, in micro-dollars." }, "totalUsd": { "type": "number" }, "breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/CostBreakdownItem" }, "description": "Spend by cost type. Sums to totalUsdMicros." }, "calls": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationRunCallCost" }, "description": "Spend per simulated call in the run." } }, "required": [ "jobId", "currency", "totalUsdMicros", "totalUsd", "breakdown", "calls" ] }, "SimulationRunCallCost": { "type": "object", "properties": { "conversationId": { "type": [ "string", "null" ], "format": "uuid", "description": "The call (voice runs) or chat (chat runs) the spend is attributed to. Null for costs incurred before the conversation existed; use simulationJobId to join those." }, "simulationJobId": { "type": [ "string", "null" ], "format": "uuid" }, "amountUsdMicros": { "type": "integer" }, "amountUsd": { "type": "number" }, "breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/CostBreakdownItem" } } }, "required": [ "conversationId", "simulationJobId", "amountUsdMicros", "amountUsd", "breakdown" ] }, "GetSimulationTemplatesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationTemplate" } } }, "required": [ "data" ], "description": "The built-in simulation templates." }, "SimulationTemplate": { "type": "object", "properties": { "slug": { "type": "string", "description": "Stable identifier. Name this in a run request.", "example": "health-check" }, "title": { "type": "string", "description": "Display name", "example": "Health check" }, "description": { "type": "string", "description": "What this template tests" }, "category": { "type": "string", "description": "Grouping used in the dashboard library", "example": "Performance" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationTemplateMetricRef" }, "description": "The metrics this template collects, resolved to this project's definitions." }, "thresholds": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationTemplateMetricRef" }, "description": "The Pass/Fail checks this template attaches alongside its metrics." }, "flows": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationTemplateFlow" }, "description": "The flows this template runs, and which of their ways of running it covers.\n\nEmpty means the template presets only what to measure, and a run has to say what to measure it\non: pass `flows` to POST /v1/simulation/run. When it is not empty you can still pass `flows` to\nnarrow it, naming a subset of the ids listed here." }, "includeFlowMetrics": { "type": "boolean", "description": "Whether runs from this template also collect each attached flow's own metrics, on top of the template's set." }, "defaultMaxSimulationDurationSeconds": { "type": "integer", "description": "The per-simulation cap a run from this template uses unless the request sets its own.", "example": 60 }, "sweep": { "oneOf": [ { "$ref": "#/components/schemas/SimulationTemplateSweep" }, { "type": "null" } ], "description": "Set when this template is a property sweep: it runs ONE flow once per value of a single\ncaller or environment property, and the report compares the values against `baseline`.\n\nThis is what decides the size of the run. A sweep attaches the flow once per entry in\n`values`, so a plan built from it costs `values.length` times the calls a normal template\nwould, before iterations. Read it before creating a plan you have to pay for.\n\n`null` for every other template." }, "defaultEndCallReasons": { "type": "array", "items": { "type": "string" }, "description": "The end-call conditions a run from this template uses unless the request sets its own.\n\nEmpty for templates whose calls end when the agent says goodbye. Non-empty where the template\nruns scripted flows that finish on a verdict: the simulated caller hangs up on an end-call\nphrase or one of these, so a run that discards them would stay on the line until the duration\ncap.", "example": [] } }, "required": [ "slug", "title", "description", "category", "metrics", "thresholds", "flows", "includeFlowMetrics", "defaultMaxSimulationDurationSeconds", "sweep", "defaultEndCallReasons" ], "description": "A built-in simulation template, resolved against this project: what it measures and what it runs.", "example": { "slug": "red-teaming", "title": "Red teaming", "description": "Adversarial probing. Tests refusals, jailbreak resistance, and whether the agent’s policy holds.", "category": "Safety", "metrics": [ { "id": "9c1e2f3a-4b5c-4d6e-8f70-1a2b3c4d5e6f", "slug": "compliance_prompt_injection_resistance" } ], "thresholds": [ { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "slug": "compliance_prompt_injection_resistance_check" } ], "flows": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "Prompt injection", "slug": "sf-prompt-injection", "happyPath": { "title": "Direct attempt" }, "edgeCases": [ { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "title": "Encoded payload", "slug": "data-embedded-injection" } ] } ], "includeFlowMetrics": false, "sweep": null, "defaultMaxSimulationDurationSeconds": 900, "defaultEndCallReasons": [] } }, "SimulationTemplateMetricRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Metric definition ID" }, "slug": { "type": "string", "description": "Stable metric slug, e.g. \"response_time\"", "example": "response_time" } }, "required": [ "id", "slug" ] }, "SimulationTemplateFlow": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Customer flow ID" }, "title": { "type": "string", "description": "Flow title" }, "slug": { "type": [ "string", "null" ], "description": "The stable slug of a Roark-curated flow, null for one of your own.\n\nPrefer this over `id` when you are storing a run in version control: a curated flow is a\nglobal row, so its id is the same for every project but differs between deployments, while\nthe slug is stable wherever the flow exists. Both are accepted by a run request.", "example": "sf-prompt-injection" }, "happyPath": { "type": [ "object", "null" ], "properties": { "title": { "type": "string" } }, "required": [ "title" ], "description": "The flow's default way of running, when this template covers it. Null when it does not, or the flow has none." }, "edgeCases": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationTemplateEdgeCase" }, "description": "The other ways of running this flow that this template covers." } }, "required": [ "id", "title", "slug", "happyPath", "edgeCases" ] }, "SimulationTemplateEdgeCase": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Customer flow variant ID" }, "title": { "type": "string", "description": "What this way of running the flow is called" }, "slug": { "type": [ "string", "null" ], "description": "The stable slug of a Roark-curated edge case, null for one of your own.\n\nPrefer this over `id` in a run you keep in version control. A curated edge case is a global\nrow, so its id differs between deployments, and renaming one replaces the row and its id\noutright. The slug survives both.", "example": "data-embedded-injection" } }, "required": [ "id", "title", "slug" ] }, "SimulationTemplateSweep": { "type": "object", "properties": { "property": { "type": "string", "enum": [ "ACCENT", "AGE", "BACKGROUND_NOISE", "BACKGROUND_NOISE_VOLUME", "BASE_EMOTION", "CONFIRMATION_STYLE", "GENDER", "INTENT_CLARITY", "LANGUAGE", "INTERRUPTION", "MEMORY_RELIABILITY", "RESPONSE_TIMING", "SPEECH_CLARITY", "SPEECH_PACE" ], "description": "The property this template varies across the flow it runs.", "example": "BACKGROUND_NOISE" }, "baseline": { "type": [ "string", "null" ], "description": "The reference value, shown first in the results, resolved to what a plan built from this\ntemplate will actually record. `null` when the property has no obvious norm. It does not\nchange the verdict: each value is compared with every other value combined.", "example": "NONE" }, "values": { "type": "array", "items": { "type": "string" }, "description": "Every value the template sweeps, in the order the plan attaches them." } }, "required": [ "property", "baseline", "values" ] }, "SimulationJobResponse": { "type": "object", "properties": { "simulationJobId": { "type": "string", "format": "uuid", "description": "Simulation job ID" }, "status": { "type": "string", "description": "Job status. `RETRY_SCHEDULED` is a retry of a simulation your agent never spoke on, waiting out the plan’s `noResponseRetryBackoffSeconds` before it dials." }, "processingStatus": { "type": "string", "description": "Processing status" }, "queuePosition": { "type": [ "integer", "null" ], "exclusiveMinimum": 0, "description": "This simulation's 1-based place in its run's queue, in the order the queue releases simulations. Null unless the status is QUEUED." }, "callId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the call created for this simulation job. Null if the call has not been created yet." }, "roarkPhoneNumber": { "type": [ "string", "null" ], "description": "Phone number provisioned by Roark for this simulation job in E.164 format. Null if the simulation job is queued and has not been assigned a phone number yet." }, "runPlan": { "$ref": "#/components/schemas/SimulationRunPlanRef" }, "enrichment": { "$ref": "#/components/schemas/SimulationJobEnrichment" }, "invalidation": { "oneOf": [ { "$ref": "#/components/schemas/SimulationJobInvalidation" }, { "type": "null" } ], "description": "Null while the result counts. See SimulationJobInvalidation." }, "failureOwner": { "type": [ "string", "null" ], "enum": [ "ROARK", "AGENT" ], "description": "Who a FAILED or TIMED_OUT job failed because of. Null when the job did not fail. `AGENT`: your agent under test did not answer, was busy, declined, hung up or went silent, or its outbound-dial HTTP endpoint refused. This is a real result. `ROARK`: the simulation itself failed on the Roark platform (pipeline, capacity or analysis). It says nothing about your agent, and the run report leaves these jobs out of every count." }, "retryOfSimulationJobId": { "type": [ "string", "null" ], "format": "uuid", "description": "The simulation this one retries, because your agent never spoke on it. Null on a test case’s first attempt." }, "attemptNumber": { "type": "integer", "exclusiveMinimum": 0, "description": "This simulation’s place among its test case’s attempts: 1 for the first, 2 for the first retry. Above 1 only when the plan retries simulations your agent never spoke on." }, "scheduledAt": { "type": [ "string", "null" ], "description": "When a `RETRY_SCHEDULED` retry dials, ISO 8601. Null on a first attempt." }, "persona": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the persona" }, "name": { "type": "string", "description": "The name the agent will identify as during conversations" }, "displayName": { "type": [ "string", "null" ], "description": "Label shown in place of the name across the dashboard (e.g. a short descriptor like \"Irate Escalator\"). The persona still identifies as `name` on calls. Omit or set null to display the name itself." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of the persona" }, "language": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ], "description": "Primary language ISO 639-1 code for the persona" }, "secondaryLanguage": { "type": [ "string", "null" ], "enum": [ "EN" ], "description": "Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish)" }, "understoodLanguages": { "type": "array", "items": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ] }, "minItems": 1, "description": "Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support." }, "accent": { "type": "string", "enum": [ "US", "US_X_SOUTH", "GB", "ES", "DE", "IN", "FR", "NL", "SA", "GR", "AU", "IT", "ID", "TH", "JP", "NZ", "PH", "SG", "MY", "HK", "TR", "PT", "IL" ], "description": "Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants" }, "age": { "type": "string", "enum": [ "CHILD", "TEENAGER", "ADULT", "ELDERLY" ], "default": "ADULT", "description": "How old the caller sounds and behaves. Only ages the persona's accent has a voice for are accepted; defaults to ADULT, which every accent supports." }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender of the persona" }, "backgroundNoise": { "type": "string", "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "default": "NONE", "description": "Background noise setting" }, "speechPace": { "type": "string", "enum": [ "SUPER_SLOW", "SLOW", "NORMAL", "FAST", "SUPER_FAST" ], "default": "NORMAL", "description": "Speech pace of the persona" }, "speechClarity": { "type": "string", "enum": [ "CLEAR", "VAGUE", "RAMBLING" ], "default": "CLEAR", "description": "Speech clarity of the persona" }, "hasDisfluencies": { "type": "boolean", "default": false, "description": "Whether the persona uses filler words like \"um\" and \"uh\"" }, "baseEmotion": { "type": "string", "enum": [ "NEUTRAL", "CHEERFUL", "CONFUSED", "FRUSTRATED", "SKEPTICAL", "RUSHED", "DISTRACTED", "ANGRY", "ANXIOUS", "SAD" ], "default": "NEUTRAL", "description": "Base emotional state of the persona" }, "intentClarity": { "type": "string", "enum": [ "CLEAR", "INDIRECT", "VAGUE" ], "default": "CLEAR", "description": "How clearly the persona expresses their intentions" }, "confirmationStyle": { "type": "string", "enum": [ "EXPLICIT", "VAGUE" ], "default": "EXPLICIT", "description": "How the persona confirms information" }, "memoryReliability": { "type": "string", "enum": [ "HIGH", "LOW" ], "default": "HIGH", "description": "How reliable the persona's memory is" }, "responseTiming": { "type": "string", "enum": [ "RELAXED", "NORMAL", "QUICK", "BARGE_IN" ], "default": "NORMAL", "description": "Deprecated and inert: it no longer affects the call. It set how long the persona waited once the agent stopped talking, and measured across production simulations it moved the reply gap by less than the noise floor, because model and speech latency dominate it. Every persona now uses one voice-activity profile. Use `interruption` for a caller who talks over the agent. Still accepted and stored so existing clients keep working. BARGE_IN is stored as `responseTiming: QUICK` with `interruption: OCCASIONAL`." }, "interruption": { "type": "string", "enum": [ "OFF", "BACKCHANNEL", "OCCASIONAL", "HEAVY" ], "default": "OFF", "description": "How much the persona talks over the agent while it is still speaking. OFF waits its turn. BACKCHANNEL makes listening noises (\"mm-hm\") over the agent without taking the floor, which tests whether the agent wrongly stops for them. OCCASIONAL adds cutting in on some long agent turns, HEAVY on most of them. Timing is randomised per turn, so two runs of the same persona do not interrupt at identical moments." }, "backstoryPrompt": { "type": [ "string", "null" ], "description": "Background story and behavioral patterns for the persona", "example": "A busy professional calling during lunch break" }, "idleMessages": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Messages the persona will say when the agent goes silent during a call. null = \"Automatic\": language-appropriate defaults are used at call time." }, "idleTimeoutSeconds": { "type": "integer", "minimum": 5, "maximum": 60, "default": 10, "description": "Seconds of silence before the persona sends an idle message" }, "idleMessageMaxSpokenCount": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3, "description": "Maximum number of idle messages the persona will send before giving up" }, "idleMessageResetCountOnUserSpeechEnabled": { "type": "boolean", "default": true, "description": "Whether the idle message counter resets when the agent speaks" }, "properties": { "type": "object", "additionalProperties": {}, "default": {}, "description": "Additional custom properties about the persona", "example": { "age": 35, "zipCode": "94105", "occupation": "Software Engineer" } }, "phoneNumber": { "type": "string", "description": "The E.164 number every call with this persona uses, when Roark has pinned one for your project. Present only when set; read-only.", "example": "+19312830919" }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "description": "Last update timestamp" } }, "required": [ "id", "name", "language", "understoodLanguages", "accent", "age", "gender", "backgroundNoise", "speechPace", "speechClarity", "hasDisfluencies", "baseEmotion", "intentClarity", "confirmationStyle", "memoryReliability", "responseTiming", "interruption", "idleMessages", "idleTimeoutSeconds", "idleMessageMaxSpokenCount", "idleMessageResetCountOnUserSpeechEnabled", "properties", "createdAt", "updatedAt" ] }, "backgroundNoise": { "$ref": "#/components/schemas/SimulationJobBackgroundNoise" }, "scenario": { "$ref": "#/components/schemas/ScenarioResponse" }, "agentEndpoint": { "$ref": "#/components/schemas/AgentEndpointResponse" }, "createdAt": { "type": "string", "description": "When the job was created" }, "startedAt": { "type": [ "string", "null" ], "description": "When the job started" }, "completedAt": { "type": [ "string", "null" ], "description": "When the job completed" } }, "required": [ "simulationJobId", "status", "processingStatus", "queuePosition", "runPlan", "enrichment", "invalidation", "failureOwner", "retryOfSimulationJobId", "attemptNumber", "scheduledAt", "persona", "backgroundNoise", "scenario", "agentEndpoint", "createdAt" ], "description": "Simulation job with related entities", "example": { "simulationJobId": "7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f", "status": "COMPLETED", "processingStatus": "PROCESSED", "queuePosition": null, "callId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "roarkPhoneNumber": "+15551234567", "runPlan": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Billing Flow Test", "variables": { "promptToUse": "v1", "accountTier": "premium" } }, "enrichment": { "requested": true, "outcome": "TIMED_OUT", "waitStartedAt": "2025-01-15T14:28:32.789Z", "waitEndedAt": "2025-01-15T14:43:32.789Z", "metricsScoredOnSimulationInstead": 4, "metricsNotCollected": 1 }, "invalidation": null, "failureOwner": null, "retryOfSimulationJobId": null, "attemptNumber": 1, "scheduledAt": null, "persona": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Sarah Johnson - Anxious Patient", "displayName": "Anxious Patient", "language": "EN", "secondaryLanguage": null, "understoodLanguages": [ "EN" ], "accent": "US", "age": "ADULT", "gender": "FEMALE", "backgroundNoise": "OFFICE", "speechPace": "NORMAL", "speechClarity": "CLEAR", "hasDisfluencies": false, "baseEmotion": "FRUSTRATED", "intentClarity": "CLEAR", "confirmationStyle": "EXPLICIT", "memoryReliability": "HIGH", "responseTiming": "NORMAL", "interruption": "OCCASIONAL", "backstoryPrompt": "A busy professional calling during lunch break", "idleMessages": null, "idleTimeoutSeconds": 10, "idleMessageMaxSpokenCount": 3, "idleMessageResetCountOnUserSpeechEnabled": true, "properties": { "age": "35", "zipCode": "94105" }, "createdAt": "2025-01-10T12:00:00.000Z", "updatedAt": "2025-01-10T12:00:00.000Z" }, "backgroundNoise": { "backgroundNoise": "CITY", "backgroundNoiseVolume": 0.1, "source": "ENVIRONMENT" }, "scenario": { "id": "f8e7d6c5-b4a3-9281-7069-5f4e3d2c1b0a", "description": "Patient calling to schedule an urgent dental appointment due to severe tooth pain" }, "agentEndpoint": { "id": "3c2b1a09-8f7e-6d5c-4b3a-291807060504", "name": "PHONE", "phoneNumber": "+15555551234", "type": "PHONE" }, "createdAt": "2025-01-15T14:23:45.123Z", "startedAt": "2025-01-15T14:24:15.456Z", "completedAt": "2025-01-15T14:28:32.789Z" } }, "SimulationRunPlanRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Run plan ID" }, "name": { "type": "string", "description": "Run plan name" }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Run-plan-level variables resolved for this job, keyed by variable name. Values are stringified by their declared type." } }, "required": [ "id", "name", "variables" ] }, "SimulationJobEnrichment": { "type": "object", "properties": { "requested": { "type": "boolean", "description": "Whether the run plan asked for the customer's live conversation to be merged into this run." }, "outcome": { "type": "string", "enum": [ "NOT_REQUESTED", "WAITING", "MERGED", "TIMED_OUT", "SKIPPED", "UNKNOWN" ], "description": "How the wait for the live conversation resolved. `WAITING` means the run is holding open for it right now. `MERGED` means it arrived and live-sourced metrics were scored against it. `TIMED_OUT` and `SKIPPED` both mean it never arrived, so scoring fell back to the simulated side: read `metricsScoredOnSimulationInstead` and `metricsNotCollected` for what that cost. `UNKNOWN` is a run that finished before Roark started recording this." }, "waitStartedAt": { "type": [ "string", "null" ], "description": "When the run began holding open for the live conversation. Null if it never waited." }, "waitEndedAt": { "type": [ "string", "null" ], "description": "When the wait ended, however it ended. Null if it never waited or is still waiting." }, "metricsScoredOnSimulationInstead": { "type": [ "integer", "null" ], "description": "Metrics that asked for the live side and were scored against the simulated side because no live conversation arrived. Null on runs that predate this recording." }, "metricsNotCollected": { "type": [ "integer", "null" ], "description": "Metrics that only support the live side and so were not scored at all. Null on runs that predate this recording." } }, "required": [ "requested", "outcome" ], "description": "What happened to this run's live-conversation enrichment, and what scoring fell back to when none arrived." }, "SimulationToolMockRecord": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "toolName": { "type": "string" }, "arguments": { "description": "What the agent called the tool with, verbatim." }, "result": { "description": "The simulated response the agent received." }, "source": { "type": "string", "enum": [ "GENERATED", "FIXTURE" ], "description": "GENERATED = the scenario-aware model answered; FIXTURE = a pinned deterministic response." }, "sessionId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "ISO 8601." } }, "required": [ "id", "toolName", "source", "sessionId", "createdAt" ], "description": "One guarded tool invocation during a test call: what the agent tried to call, and what it got." }, "SimulationToolMockResponse": { "type": "object", "properties": { "simulationJobId": { "type": "string", "format": "uuid" }, "toolName": { "type": "string" }, "result": { "description": "The simulated tool response: valid JSON, shaped by the tool contract, consistent with the test scenario and with earlier mocked responses in the same call. Return this from your tool instead of executing it." }, "source": { "type": "string", "enum": [ "GENERATED", "FIXTURE" ], "description": "GENERATED = the scenario-aware model answered; FIXTURE = a pinned deterministic response you configured answered." }, "reused": { "type": "boolean", "description": "True when this exact invocation (same tool, same arguments) was answered moments ago and the stored response was returned, e.g. on a retry." } }, "required": [ "simulationJobId", "toolName", "source", "reused" ], "description": "A simulated backend response for a guarded tool during a Roark test call. The real tool was not, and must not be, executed." }, "SimulationToolMockRequest": { "type": "object", "properties": { "simulationJobId": { "type": "string", "format": "uuid", "description": "The simulation this session belongs to, from the agent-config resolve response (`simulationJobId`). Roark re-validates it against the live simulation before answering." }, "sessionId": { "type": "string", "maxLength": 256, "description": "Your session or room identifier, echoed back in logs for correlation." }, "toolName": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The tool the agent invoked.", "example": "book_appointment" }, "toolDescription": { "type": "string", "maxLength": 4000, "description": "The tool's contract: its description and, ideally, its parameter and return shape. The more contract you pass, the more faithful the simulated response.", "example": "Books an appointment. Args: date (YYYY-MM-DD), time (HH:MM). Returns {confirmationId, status}." }, "arguments": { "type": "object", "additionalProperties": {}, "description": "The arguments the agent called the tool with, verbatim.", "example": { "date": "2026-10-01", "time": "15:00" } } }, "required": [ "simulationJobId", "toolName" ] }, "SimulationToolFixture": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "toolName": { "type": "string", "example": "lookup_availability" }, "customerFlowVariantId": { "type": [ "string", "null" ], "format": "uuid", "description": "The flow variant this fixture is pinned to. Null = project-wide." }, "response": { "description": "The exact JSON the tool returns during Roark test calls." }, "description": { "type": [ "string", "null" ], "description": "Why this fixture exists." }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "description": "ISO 8601." }, "updatedAt": { "type": "string", "description": "ISO 8601." } }, "required": [ "id", "toolName", "customerFlowVariantId", "description", "enabled", "createdAt", "updatedAt" ], "description": "A deterministic tool response for Roark test calls: where the scenario-aware model makes mocked tools plausible, a fixture makes one exact, so a simulation can force the branch under test. Never applies to real callers." }, "UpsertSimulationToolFixtureRequest": { "type": "object", "properties": { "toolName": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The tool this fixture answers for.", "example": "lookup_availability" }, "response": { "description": "The exact JSON to return.", "example": { "slots": [] } }, "customerFlowVariantId": { "type": "string", "format": "uuid", "description": "Pin the fixture to one flow variant (scenario). Omit for a project-wide fixture. A variant-pinned fixture beats the project-wide one." }, "description": { "type": "string", "maxLength": 1000, "description": "Why this fixture exists.", "example": "Forces the no-availability branch" }, "enabled": { "type": "boolean", "description": "Defaults to true." } }, "required": [ "toolName" ] }, "UpdateSimulationToolFixtureRequest": { "type": "object", "properties": { "response": {}, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "enabled": { "type": "boolean" } } }, "GetCustomerFlowsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerFlow" } }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of items" }, "hasMore": { "type": "boolean", "description": "Whether there are more items to fetch" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page of items" } }, "required": [ "total", "hasMore", "nextCursor" ] } }, "required": [ "data", "pagination" ], "description": "Paginated list of customer flows" }, "CustomerFlow": { "oneOf": [ { "$ref": "#/components/schemas/ScriptedCustomerFlow" }, { "$ref": "#/components/schemas/ImprovCustomerFlow" }, { "$ref": "#/components/schemas/VoicemailCustomerFlow" } ], "discriminator": { "propertyName": "type", "mapping": { "SCRIPTED": "#/components/schemas/ScriptedCustomerFlow", "IMPROV": "#/components/schemas/ImprovCustomerFlow", "VOICEMAIL": "#/components/schemas/VoicemailCustomerFlow" } }, "description": "The conversation a simulated customer has with the agent under test." }, "ScriptedCustomerFlow": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "SYSTEM", "CUSTOM" ], "default": "CUSTOM" }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format" }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format" }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the agent" }, "name": { "type": "string", "description": "Name of the agent" }, "description": { "type": [ "string", "null" ], "description": "Description of the agent" }, "customId": { "type": [ "string", "null" ], "description": "Custom identifier for the agent" }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format" }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format" } }, "required": [ "id", "name", "description", "customId", "createdAt", "updatedAt" ] }, "description": "The agents this flow is run against." }, "agentExpectations": { "type": "array", "items": { "$ref": "#/components/schemas/FlowExpectation" } }, "type": { "type": "string", "const": "SCRIPTED" }, "scriptAdherence": { "type": "string", "enum": [ "LOOSE", "STRICT" ], "description": "How closely a run follows the script. LOOSE (default) hands the whole script to the simulated customer as one prompt; it keeps the call moving whatever your agent says. STRICT runs the script as a state machine on the agent service: at every agent step the simulated customer waits, silent, until your agent has said the expected line, and only then moves on. Scripted flows only; STRICT needs the agent-service transport and is not available on realtime models." }, "offScriptPolicy": { "oneOf": [ { "$ref": "#/components/schemas/OffScriptPolicy" }, { "type": "null" } ] }, "branchingMode": { "type": "string", "enum": [ "DETERMINISTIC", "ADAPTIVE" ], "description": "How a run walks the graph. DETERMINISTIC (\"Simulate every path\" in the app) places one call per variant, each following its path exactly whatever the agent says. ADAPTIVE (\"Adapt to your agent\") collapses the paths into one call PER PERSONA, on which the simulated customer picks a branch from what the agent actually said. Both modes speak the exact authored lines, and neither changes how metrics or expectations grade." }, "graph": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStep" }, "description": "The conversation, as a graph of steps. Present on a single flow; omitted from the list, where reading it would mean walking the project step graph once per row." }, "happyPath": { "oneOf": [ { "$ref": "#/components/schemas/ScriptedFlowHappyPath" }, { "type": "null" } ], "description": "The way this flow is meant to go. Null when the flow has none, and then every way is an edge case." }, "edgeCases": { "type": "array", "items": { "$ref": "#/components/schemas/ScriptedFlowVariant" }, "description": "Every other way of running this flow." } }, "required": [ "id", "title", "source", "createdAt", "updatedAt", "agents", "agentExpectations", "type", "scriptAdherence", "offScriptPolicy", "branchingMode", "happyPath", "edgeCases" ], "title": "Scripted", "description": "A flow whose conversation is written out as a graph of turns." }, "FlowExpectation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "prompt": { "type": "string", "description": "What the agent under test is graded against." } }, "required": [ "id", "prompt" ], "description": "One thing the agent under test is graded against." }, "OffScriptPolicy": { "type": "object", "properties": { "reaction": { "type": "string", "enum": [ "STAY_SILENT", "REPEAT", "RESPOND", "SAY" ], "default": "STAY_SILENT" }, "sayLine": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2000 }, "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 20, "default": 3 }, "then": { "type": "string", "enum": [ "HANG_UP", "MOVE_ON", "ADAPT", "HANG_UP_INVALIDATE" ], "default": "HANG_UP" }, "waitSeconds": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 600 } }, "required": [ "reaction", "maxAttempts", "then" ], "description": "STRICT only. What the simulated customer does when your agent does not say the expected line. Each unmatched agent utterance is an attempt: `reaction` runs per attempt (STAY_SILENT, REPEAT its last scripted line, RESPOND once in character without moving on, or SAY `sayLine`), and `then` runs when attempts reach `maxAttempts` or your agent stays silent for `waitSeconds` (HANG_UP ends the call with ended reason SCRIPT_DIVERGED, HANG_UP_INVALIDATE ends it the same way and invalidates the run so it is scored by nothing and counted nowhere, MOVE_ON advances anyway, ADAPT hands the rest of the call to loose behaviour). Null: stay silent, 3 attempts, hang up. The default for every agent step; an AGENT_TURN step can carry its own." }, "FlowStep": { "oneOf": [ { "type": "object", "properties": { "nodeId": { "type": "string", "format": "uuid" }, "ref": { "type": "string", "minLength": 1, "maxLength": 64 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStep" } }, "mergeIntoNodeIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "stage": { "type": [ "object", "null" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": { "type": "boolean" }, "analyze": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false }, "type": { "type": "string", "const": "AGENT_TURN" }, "content": { "type": [ "string", "null" ] }, "offScriptPolicy": { "type": [ "object", "null" ], "properties": { "reaction": { "type": "string", "enum": [ "STAY_SILENT", "REPEAT", "RESPOND", "SAY" ], "default": "STAY_SILENT" }, "sayLine": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2000 }, "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 20, "default": 3 }, "then": { "type": "string", "enum": [ "HANG_UP", "MOVE_ON", "ADAPT", "HANG_UP_INVALIDATE" ], "default": "HANG_UP" }, "waitSeconds": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 600 } }, "required": [ "reaction", "maxAttempts", "then" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "nodeId": { "type": "string", "format": "uuid" }, "ref": { "type": "string", "minLength": 1, "maxLength": 64 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStep" } }, "mergeIntoNodeIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "stage": { "type": [ "object", "null" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": { "type": "boolean" }, "analyze": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false }, "type": { "type": "string", "const": "CUSTOMER_TURN" }, "content": { "type": [ "string", "null" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "nodeId": { "type": "string", "format": "uuid" }, "ref": { "type": "string", "minLength": 1, "maxLength": 64 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStep" } }, "mergeIntoNodeIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "stage": { "type": [ "object", "null" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": { "type": "boolean" }, "analyze": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false }, "type": { "type": "string", "const": "CUSTOMER_FIRST_MESSAGE" }, "content": { "type": [ "string", "null" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "nodeId": { "type": "string", "format": "uuid" }, "ref": { "type": "string", "minLength": 1, "maxLength": 64 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStep" } }, "mergeIntoNodeIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "stage": { "type": [ "object", "null" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": { "type": "boolean" }, "analyze": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false }, "type": { "type": "string", "const": "CUSTOMER_VERBATIM_TURN" }, "content": { "type": [ "string", "null" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "nodeId": { "type": "string", "format": "uuid" }, "ref": { "type": "string", "minLength": 1, "maxLength": 64 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStep" } }, "mergeIntoNodeIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "stage": { "type": [ "object", "null" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": { "type": "boolean" }, "analyze": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false }, "type": { "type": "string", "const": "CUSTOMER_SILENCE" }, "silenceDurationSeconds": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "nodeId": { "type": "string", "format": "uuid" }, "ref": { "type": "string", "minLength": 1, "maxLength": 64 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStep" } }, "mergeIntoNodeIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "stage": { "type": [ "object", "null" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": { "type": "boolean" }, "analyze": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false }, "type": { "type": "string", "const": "CUSTOMER_DTMF" }, "dtmfDigits": { "type": [ "string", "null" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "nodeId": { "type": "string", "format": "uuid" }, "ref": { "type": "string", "minLength": 1, "maxLength": 64 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStep" } }, "mergeIntoNodeIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "stage": { "type": [ "object", "null" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": { "type": "boolean" }, "analyze": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false }, "type": { "type": "string", "const": "AGENT_DTMF" }, "dtmfDigits": { "type": [ "string", "null" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "nodeId": { "type": "string", "format": "uuid" }, "ref": { "type": "string", "minLength": 1, "maxLength": 64 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStep" } }, "mergeIntoNodeIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "stage": { "type": [ "object", "null" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": { "type": "boolean" }, "analyze": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false }, "type": { "type": "string", "const": "VOICEMAIL" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "nodeId": { "type": "string", "format": "uuid" }, "ref": { "type": "string", "minLength": 1, "maxLength": 64 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStep" } }, "mergeIntoNodeIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "stage": { "type": [ "object", "null" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": { "type": "boolean" }, "analyze": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false }, "type": { "type": "string", "const": "CUSTOMER_HANDOFF" }, "handoffPersonaId": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "nodeId": { "type": "string", "format": "uuid" }, "ref": { "type": "string", "minLength": 1, "maxLength": 64 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStep" } }, "mergeIntoNodeIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "stage": { "type": [ "object", "null" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": { "type": "boolean" }, "analyze": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false }, "type": { "type": "string", "const": "SCENARIO_LINK" }, "linkedCustomerFlowId": { "type": [ "string", "null" ], "format": "uuid" }, "linkedCustomerFlowVariantId": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "type" ], "additionalProperties": false } ], "description": "One step in a scripted flow's conversation.\n\n`nodeId` is the identity contract: include it to update the existing step, omit it to create a new one.\nA step continues into `steps` (more than one child is a branch point) and/or `mergeIntoNodeIds`, which\nnames steps elsewhere in the same request that this step rejoins. Branches that come back together are\nrepresented that way rather than by repeating the shared step, so reading a flow, editing it and writing\nit back preserves it exactly.\n\nA merge target is named by its `nodeId` when it already exists, or by `ref` when it is being created in\nthe same request. `ref` is a label you choose, it is request-local, and it is never stored or returned.\nPut the shared step inline under the first branch that reaches it and point the others at it: a top-level\nstep is a root wired straight from the start of the flow, so a merge target parked there would also be\nreachable directly.\n\nA `CUSTOMER_TURN` describes what the simulated customer says and the persona phrases it; a\n`CUSTOMER_VERBATIM_TURN` is said word for word, and one placed as a top-level step opens the call\nthe moment it connects, before the agent speaks. `CUSTOMER_FIRST_MESSAGE` is the retired name for\nthat opening case: still accepted, stored and returned as `CUSTOMER_VERBATIM_TURN`.\n\nThe two DTMF types are mirror images and both require `dtmfDigits`. `CUSTOMER_DTMF` is keys the\nsimulated caller presses while navigating your agent. `AGENT_DTMF` is keys your agent under test is\nexpected to press while navigating a menu the simulation is playing, so its digits are an assertion the\nrun is graded against rather than an instruction, and it counts as an agent turn for role alternation.\n\nA `CUSTOMER_HANDOFF` hands the phone to another persona (`handoffPersonaId`), or back to the flow's\nown persona when it is null. The steps after it are spoken by whoever holds the phone. It sits between\nturns like a silence, so it may follow either side.\n\nIn a STRICT flow an `AGENT_TURN` may carry its own `offScriptPolicy`, which replaces the flow-level one at\nthat step. Omit it (or send null) to follow the flow's policy. Use it where one missed step makes the rest\nof the call meaningless: an authentication menu, say, with `then: HANG_UP_INVALIDATE`.\n\nAny step may set `stage`, the named phase of the flow it belongs to: the IVR, the login, the scenario\nitself. Steps in one stage are drawn as a group in the editor, and the name is yours: the reports say it\nback to you. The stage does not have to exist first, it is created the first time a step names it, and a\nname already in the project is matched ignoring case.\n\nA stage with `required: true` is a gate. A run that ends without getting PAST it never reached what was\nbeing measured, so it stays in the report, labelled with the stage it never completed and the one it\nstopped in, and is left out of the run score and the success-criteria verdict: an agent that never clears\nthe IVR does not fail every check in a scenario it never started. `required` belongs to the stage rather\nthan to the step, so a read returns it on every step in that stage, and a write that sets it on any one\nof them marks the whole stage. A flow that requires no stage is scored exactly as before.\n\nA stage with `analyze: false` is not measured. Its turns are kept out of the core call metrics (talk\ntime, speech pace, turn and response timings), which is what an IVR usually wants alongside\n`required: true`: the run has to get through the menu, but how the agent sounded reading it is not what\nis being tested. Coverage is being extended package by package, so the judged metrics (quality,\ncompliance, repetition, escalation, tone) still read the whole call for now. Nothing is cut and nothing\nis re-timed, so a turn at 4:10 is still at 4:10 with an earlier stage excluded, and rate metrics divide\nby the part of the call that was measured rather than by the whole of it. Defaults to true, belongs to\nthe stage the same way `required` does, and turning it off on any one step turns it off for the stage." }, "ScriptedFlowVariant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1 }, "systemKey": { "type": [ "string", "null" ] }, "precededByCustomerFlowId": { "type": [ "string", "null" ], "format": "uuid" }, "precededByCustomerFlowVariantId": { "type": [ "string", "null" ], "format": "uuid" }, "isGenerated": { "type": "boolean", "default": false }, "includeFlowExpectations": { "type": "boolean", "description": "Whether this variant is graded on the flow's agentExpectations as well as its additionalExpectations. False grades it on its additionalExpectations only. Always true on the happy path." }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format" }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format" }, "personaOverride": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the persona" }, "name": { "type": "string", "description": "The name the agent will identify as during conversations" }, "displayName": { "type": [ "string", "null" ], "description": "Label shown in place of the name across the dashboard (e.g. a short descriptor like \"Irate Escalator\"). The persona still identifies as `name` on calls. Omit or set null to display the name itself." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of the persona" }, "language": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ], "description": "Primary language ISO 639-1 code for the persona" }, "secondaryLanguage": { "type": [ "string", "null" ], "enum": [ "EN" ], "description": "Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish)" }, "understoodLanguages": { "type": "array", "items": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ] }, "minItems": 1, "description": "Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support." }, "accent": { "type": "string", "enum": [ "US", "US_X_SOUTH", "GB", "ES", "DE", "IN", "FR", "NL", "SA", "GR", "AU", "IT", "ID", "TH", "JP", "NZ", "PH", "SG", "MY", "HK", "TR", "PT", "IL" ], "description": "Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants" }, "age": { "type": "string", "enum": [ "CHILD", "TEENAGER", "ADULT", "ELDERLY" ], "default": "ADULT", "description": "How old the caller sounds and behaves. Only ages the persona's accent has a voice for are accepted; defaults to ADULT, which every accent supports." }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender of the persona" }, "backgroundNoise": { "type": "string", "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "default": "NONE", "description": "Background noise setting" }, "speechPace": { "type": "string", "enum": [ "SUPER_SLOW", "SLOW", "NORMAL", "FAST", "SUPER_FAST" ], "default": "NORMAL", "description": "Speech pace of the persona" }, "speechClarity": { "type": "string", "enum": [ "CLEAR", "VAGUE", "RAMBLING" ], "default": "CLEAR", "description": "Speech clarity of the persona" }, "hasDisfluencies": { "type": "boolean", "default": false, "description": "Whether the persona uses filler words like \"um\" and \"uh\"" }, "baseEmotion": { "type": "string", "enum": [ "NEUTRAL", "CHEERFUL", "CONFUSED", "FRUSTRATED", "SKEPTICAL", "RUSHED", "DISTRACTED", "ANGRY", "ANXIOUS", "SAD" ], "default": "NEUTRAL", "description": "Base emotional state of the persona" }, "intentClarity": { "type": "string", "enum": [ "CLEAR", "INDIRECT", "VAGUE" ], "default": "CLEAR", "description": "How clearly the persona expresses their intentions" }, "confirmationStyle": { "type": "string", "enum": [ "EXPLICIT", "VAGUE" ], "default": "EXPLICIT", "description": "How the persona confirms information" }, "memoryReliability": { "type": "string", "enum": [ "HIGH", "LOW" ], "default": "HIGH", "description": "How reliable the persona's memory is" }, "responseTiming": { "type": "string", "enum": [ "RELAXED", "NORMAL", "QUICK", "BARGE_IN" ], "default": "NORMAL", "description": "Deprecated and inert: it no longer affects the call. It set how long the persona waited once the agent stopped talking, and measured across production simulations it moved the reply gap by less than the noise floor, because model and speech latency dominate it. Every persona now uses one voice-activity profile. Use `interruption` for a caller who talks over the agent. Still accepted and stored so existing clients keep working. BARGE_IN is stored as `responseTiming: QUICK` with `interruption: OCCASIONAL`." }, "interruption": { "type": "string", "enum": [ "OFF", "BACKCHANNEL", "OCCASIONAL", "HEAVY" ], "default": "OFF", "description": "How much the persona talks over the agent while it is still speaking. OFF waits its turn. BACKCHANNEL makes listening noises (\"mm-hm\") over the agent without taking the floor, which tests whether the agent wrongly stops for them. OCCASIONAL adds cutting in on some long agent turns, HEAVY on most of them. Timing is randomised per turn, so two runs of the same persona do not interrupt at identical moments." }, "backstoryPrompt": { "type": [ "string", "null" ], "description": "Background story and behavioral patterns for the persona", "example": "A busy professional calling during lunch break" }, "idleMessages": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Messages the persona will say when the agent goes silent during a call. null = \"Automatic\": language-appropriate defaults are used at call time." }, "idleTimeoutSeconds": { "type": "integer", "minimum": 5, "maximum": 60, "default": 10, "description": "Seconds of silence before the persona sends an idle message" }, "idleMessageMaxSpokenCount": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3, "description": "Maximum number of idle messages the persona will send before giving up" }, "idleMessageResetCountOnUserSpeechEnabled": { "type": "boolean", "default": true, "description": "Whether the idle message counter resets when the agent speaks" }, "properties": { "type": "object", "additionalProperties": {}, "default": {}, "description": "Additional custom properties about the persona", "example": { "age": 35, "zipCode": "94105", "occupation": "Software Engineer" } }, "phoneNumber": { "type": "string", "description": "The E.164 number every call with this persona uses, when Roark has pinned one for your project. Present only when set; read-only.", "example": "+19312830919" }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "description": "Last update timestamp" } }, "required": [ "id", "name", "language", "understoodLanguages", "accent", "age", "gender", "backgroundNoise", "speechPace", "speechClarity", "hasDisfluencies", "baseEmotion", "intentClarity", "confirmationStyle", "memoryReliability", "responseTiming", "interruption", "idleMessages", "idleTimeoutSeconds", "idleMessageMaxSpokenCount", "idleMessageResetCountOnUserSpeechEnabled", "properties", "createdAt", "updatedAt" ], "description": "The persona this runs as instead of the happy path's. Null means it inherits." }, "environment": { "oneOf": [ { "$ref": "#/components/schemas/EnvironmentResponse" }, { "type": "null" } ], "description": "The conditions this runs under. Null means it inherits the happy path's." }, "additionalExpectations": { "type": "array", "items": { "$ref": "#/components/schemas/FlowExpectation" }, "description": "Graded on top of the flow's own expectations, for this variant only." }, "type": { "type": "string", "const": "SCRIPTED" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStep" }, "description": "The one path through the graph this variant runs, in order. Linear by construction, so these steps never nest." } }, "required": [ "id", "title", "precededByCustomerFlowId", "precededByCustomerFlowVariantId", "isGenerated", "includeFlowExpectations", "createdAt", "updatedAt", "personaOverride", "environment", "additionalExpectations", "type", "steps" ], "title": "Scripted", "description": "One path through a scripted flow. The path engine owns which paths exist, so editing the graph is what creates and removes these." }, "ScriptedFlowHappyPath": { "allOf": [ { "$ref": "#/components/schemas/ScriptedFlowVariant" } ], "title": "Scripted", "description": "One path through a scripted flow. The path engine owns which paths exist, so editing the graph is what creates and removes these." }, "ImprovCustomerFlow": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "SYSTEM", "CUSTOM" ], "default": "CUSTOM" }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format" }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format" }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the agent" }, "name": { "type": "string", "description": "Name of the agent" }, "description": { "type": [ "string", "null" ], "description": "Description of the agent" }, "customId": { "type": [ "string", "null" ], "description": "Custom identifier for the agent" }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format" }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format" } }, "required": [ "id", "name", "description", "customId", "createdAt", "updatedAt" ] }, "description": "The agents this flow is run against." }, "agentExpectations": { "type": "array", "items": { "$ref": "#/components/schemas/FlowExpectation" } }, "type": { "type": "string", "const": "IMPROV" }, "happyPath": { "oneOf": [ { "$ref": "#/components/schemas/ImprovFlowHappyPath" }, { "type": "null" } ], "description": "The way this flow is meant to go. Null when the flow has none, and then every way is an edge case." }, "edgeCases": { "type": "array", "items": { "$ref": "#/components/schemas/ImprovFlowVariant" }, "description": "Every other way of running this flow." } }, "required": [ "id", "title", "source", "createdAt", "updatedAt", "agents", "agentExpectations", "type", "happyPath", "edgeCases" ], "title": "Improv", "description": "A flow whose conversation is not written out: each variant gives the simulated customer a brief and lets it improvise." }, "ImprovFlowVariant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1 }, "systemKey": { "type": [ "string", "null" ] }, "precededByCustomerFlowId": { "type": [ "string", "null" ], "format": "uuid" }, "precededByCustomerFlowVariantId": { "type": [ "string", "null" ], "format": "uuid" }, "isGenerated": { "type": "boolean", "default": false }, "includeFlowExpectations": { "type": "boolean", "description": "Whether this variant is graded on the flow's agentExpectations as well as its additionalExpectations. False grades it on its additionalExpectations only. Always true on the happy path." }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format" }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format" }, "personaOverride": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the persona" }, "name": { "type": "string", "description": "The name the agent will identify as during conversations" }, "displayName": { "type": [ "string", "null" ], "description": "Label shown in place of the name across the dashboard (e.g. a short descriptor like \"Irate Escalator\"). The persona still identifies as `name` on calls. Omit or set null to display the name itself." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of the persona" }, "language": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ], "description": "Primary language ISO 639-1 code for the persona" }, "secondaryLanguage": { "type": [ "string", "null" ], "enum": [ "EN" ], "description": "Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish)" }, "understoodLanguages": { "type": "array", "items": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ] }, "minItems": 1, "description": "Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support." }, "accent": { "type": "string", "enum": [ "US", "US_X_SOUTH", "GB", "ES", "DE", "IN", "FR", "NL", "SA", "GR", "AU", "IT", "ID", "TH", "JP", "NZ", "PH", "SG", "MY", "HK", "TR", "PT", "IL" ], "description": "Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants" }, "age": { "type": "string", "enum": [ "CHILD", "TEENAGER", "ADULT", "ELDERLY" ], "default": "ADULT", "description": "How old the caller sounds and behaves. Only ages the persona's accent has a voice for are accepted; defaults to ADULT, which every accent supports." }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender of the persona" }, "backgroundNoise": { "type": "string", "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "default": "NONE", "description": "Background noise setting" }, "speechPace": { "type": "string", "enum": [ "SUPER_SLOW", "SLOW", "NORMAL", "FAST", "SUPER_FAST" ], "default": "NORMAL", "description": "Speech pace of the persona" }, "speechClarity": { "type": "string", "enum": [ "CLEAR", "VAGUE", "RAMBLING" ], "default": "CLEAR", "description": "Speech clarity of the persona" }, "hasDisfluencies": { "type": "boolean", "default": false, "description": "Whether the persona uses filler words like \"um\" and \"uh\"" }, "baseEmotion": { "type": "string", "enum": [ "NEUTRAL", "CHEERFUL", "CONFUSED", "FRUSTRATED", "SKEPTICAL", "RUSHED", "DISTRACTED", "ANGRY", "ANXIOUS", "SAD" ], "default": "NEUTRAL", "description": "Base emotional state of the persona" }, "intentClarity": { "type": "string", "enum": [ "CLEAR", "INDIRECT", "VAGUE" ], "default": "CLEAR", "description": "How clearly the persona expresses their intentions" }, "confirmationStyle": { "type": "string", "enum": [ "EXPLICIT", "VAGUE" ], "default": "EXPLICIT", "description": "How the persona confirms information" }, "memoryReliability": { "type": "string", "enum": [ "HIGH", "LOW" ], "default": "HIGH", "description": "How reliable the persona's memory is" }, "responseTiming": { "type": "string", "enum": [ "RELAXED", "NORMAL", "QUICK", "BARGE_IN" ], "default": "NORMAL", "description": "Deprecated and inert: it no longer affects the call. It set how long the persona waited once the agent stopped talking, and measured across production simulations it moved the reply gap by less than the noise floor, because model and speech latency dominate it. Every persona now uses one voice-activity profile. Use `interruption` for a caller who talks over the agent. Still accepted and stored so existing clients keep working. BARGE_IN is stored as `responseTiming: QUICK` with `interruption: OCCASIONAL`." }, "interruption": { "type": "string", "enum": [ "OFF", "BACKCHANNEL", "OCCASIONAL", "HEAVY" ], "default": "OFF", "description": "How much the persona talks over the agent while it is still speaking. OFF waits its turn. BACKCHANNEL makes listening noises (\"mm-hm\") over the agent without taking the floor, which tests whether the agent wrongly stops for them. OCCASIONAL adds cutting in on some long agent turns, HEAVY on most of them. Timing is randomised per turn, so two runs of the same persona do not interrupt at identical moments." }, "backstoryPrompt": { "type": [ "string", "null" ], "description": "Background story and behavioral patterns for the persona", "example": "A busy professional calling during lunch break" }, "idleMessages": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Messages the persona will say when the agent goes silent during a call. null = \"Automatic\": language-appropriate defaults are used at call time." }, "idleTimeoutSeconds": { "type": "integer", "minimum": 5, "maximum": 60, "default": 10, "description": "Seconds of silence before the persona sends an idle message" }, "idleMessageMaxSpokenCount": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3, "description": "Maximum number of idle messages the persona will send before giving up" }, "idleMessageResetCountOnUserSpeechEnabled": { "type": "boolean", "default": true, "description": "Whether the idle message counter resets when the agent speaks" }, "properties": { "type": "object", "additionalProperties": {}, "default": {}, "description": "Additional custom properties about the persona", "example": { "age": 35, "zipCode": "94105", "occupation": "Software Engineer" } }, "phoneNumber": { "type": "string", "description": "The E.164 number every call with this persona uses, when Roark has pinned one for your project. Present only when set; read-only.", "example": "+19312830919" }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "description": "Last update timestamp" } }, "required": [ "id", "name", "language", "understoodLanguages", "accent", "age", "gender", "backgroundNoise", "speechPace", "speechClarity", "hasDisfluencies", "baseEmotion", "intentClarity", "confirmationStyle", "memoryReliability", "responseTiming", "interruption", "idleMessages", "idleTimeoutSeconds", "idleMessageMaxSpokenCount", "idleMessageResetCountOnUserSpeechEnabled", "properties", "createdAt", "updatedAt" ], "description": "The persona this runs as instead of the happy path's. Null means it inherits." }, "environment": { "oneOf": [ { "$ref": "#/components/schemas/EnvironmentResponse" }, { "type": "null" } ], "description": "The conditions this runs under. Null means it inherits the happy path's." }, "additionalExpectations": { "type": "array", "items": { "$ref": "#/components/schemas/FlowExpectation" }, "description": "Graded on top of the flow's own expectations, for this variant only." }, "type": { "type": "string", "const": "IMPROV" }, "prompt": { "type": [ "string", "null" ], "description": "The brief the simulated customer improvises from. A `@{persona:}` mention hands the phone to that persona mid-call; the sentences around the mention say when." }, "handoffPersonas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the persona" }, "name": { "type": "string", "description": "The name the agent will identify as during conversations" }, "displayName": { "type": [ "string", "null" ], "description": "Label shown in place of the name across the dashboard (e.g. a short descriptor like \"Irate Escalator\"). The persona still identifies as `name` on calls. Omit or set null to display the name itself." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of the persona" }, "language": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ], "description": "Primary language ISO 639-1 code for the persona" }, "secondaryLanguage": { "type": [ "string", "null" ], "enum": [ "EN" ], "description": "Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish)" }, "understoodLanguages": { "type": "array", "items": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ] }, "minItems": 1, "description": "Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support." }, "accent": { "type": "string", "enum": [ "US", "US_X_SOUTH", "GB", "ES", "DE", "IN", "FR", "NL", "SA", "GR", "AU", "IT", "ID", "TH", "JP", "NZ", "PH", "SG", "MY", "HK", "TR", "PT", "IL" ], "description": "Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants" }, "age": { "type": "string", "enum": [ "CHILD", "TEENAGER", "ADULT", "ELDERLY" ], "default": "ADULT", "description": "How old the caller sounds and behaves. Only ages the persona's accent has a voice for are accepted; defaults to ADULT, which every accent supports." }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender of the persona" }, "backgroundNoise": { "type": "string", "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "default": "NONE", "description": "Background noise setting" }, "speechPace": { "type": "string", "enum": [ "SUPER_SLOW", "SLOW", "NORMAL", "FAST", "SUPER_FAST" ], "default": "NORMAL", "description": "Speech pace of the persona" }, "speechClarity": { "type": "string", "enum": [ "CLEAR", "VAGUE", "RAMBLING" ], "default": "CLEAR", "description": "Speech clarity of the persona" }, "hasDisfluencies": { "type": "boolean", "default": false, "description": "Whether the persona uses filler words like \"um\" and \"uh\"" }, "baseEmotion": { "type": "string", "enum": [ "NEUTRAL", "CHEERFUL", "CONFUSED", "FRUSTRATED", "SKEPTICAL", "RUSHED", "DISTRACTED", "ANGRY", "ANXIOUS", "SAD" ], "default": "NEUTRAL", "description": "Base emotional state of the persona" }, "intentClarity": { "type": "string", "enum": [ "CLEAR", "INDIRECT", "VAGUE" ], "default": "CLEAR", "description": "How clearly the persona expresses their intentions" }, "confirmationStyle": { "type": "string", "enum": [ "EXPLICIT", "VAGUE" ], "default": "EXPLICIT", "description": "How the persona confirms information" }, "memoryReliability": { "type": "string", "enum": [ "HIGH", "LOW" ], "default": "HIGH", "description": "How reliable the persona's memory is" }, "responseTiming": { "type": "string", "enum": [ "RELAXED", "NORMAL", "QUICK", "BARGE_IN" ], "default": "NORMAL", "description": "Deprecated and inert: it no longer affects the call. It set how long the persona waited once the agent stopped talking, and measured across production simulations it moved the reply gap by less than the noise floor, because model and speech latency dominate it. Every persona now uses one voice-activity profile. Use `interruption` for a caller who talks over the agent. Still accepted and stored so existing clients keep working. BARGE_IN is stored as `responseTiming: QUICK` with `interruption: OCCASIONAL`." }, "interruption": { "type": "string", "enum": [ "OFF", "BACKCHANNEL", "OCCASIONAL", "HEAVY" ], "default": "OFF", "description": "How much the persona talks over the agent while it is still speaking. OFF waits its turn. BACKCHANNEL makes listening noises (\"mm-hm\") over the agent without taking the floor, which tests whether the agent wrongly stops for them. OCCASIONAL adds cutting in on some long agent turns, HEAVY on most of them. Timing is randomised per turn, so two runs of the same persona do not interrupt at identical moments." }, "backstoryPrompt": { "type": [ "string", "null" ], "description": "Background story and behavioral patterns for the persona", "example": "A busy professional calling during lunch break" }, "idleMessages": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Messages the persona will say when the agent goes silent during a call. null = \"Automatic\": language-appropriate defaults are used at call time." }, "idleTimeoutSeconds": { "type": "integer", "minimum": 5, "maximum": 60, "default": 10, "description": "Seconds of silence before the persona sends an idle message" }, "idleMessageMaxSpokenCount": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3, "description": "Maximum number of idle messages the persona will send before giving up" }, "idleMessageResetCountOnUserSpeechEnabled": { "type": "boolean", "default": true, "description": "Whether the idle message counter resets when the agent speaks" }, "properties": { "type": "object", "additionalProperties": {}, "default": {}, "description": "Additional custom properties about the persona", "example": { "age": 35, "zipCode": "94105", "occupation": "Software Engineer" } }, "phoneNumber": { "type": "string", "description": "The E.164 number every call with this persona uses, when Roark has pinned one for your project. Present only when set; read-only.", "example": "+19312830919" }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "description": "Last update timestamp" } }, "required": [ "id", "name", "language", "understoodLanguages", "accent", "age", "gender", "backgroundNoise", "speechPace", "speechClarity", "hasDisfluencies", "baseEmotion", "intentClarity", "confirmationStyle", "memoryReliability", "responseTiming", "interruption", "idleMessages", "idleTimeoutSeconds", "idleMessageMaxSpokenCount", "idleMessageResetCountOnUserSpeechEnabled", "properties", "createdAt", "updatedAt" ] }, "description": "The personas this brief hands the phone to, in order of first mention. Empty when the brief inherits the happy path's: read the happy path's list." } }, "required": [ "id", "title", "precededByCustomerFlowId", "precededByCustomerFlowVariantId", "isGenerated", "includeFlowExpectations", "createdAt", "updatedAt", "personaOverride", "environment", "additionalExpectations", "type", "handoffPersonas" ], "title": "Improv", "description": "One brief to run an improv flow with." }, "ImprovFlowHappyPath": { "allOf": [ { "$ref": "#/components/schemas/ImprovFlowVariant" } ], "title": "Improv", "description": "One brief to run an improv flow with." }, "VoicemailCustomerFlow": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "SYSTEM", "CUSTOM" ], "default": "CUSTOM" }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format" }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format" }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the agent" }, "name": { "type": "string", "description": "Name of the agent" }, "description": { "type": [ "string", "null" ], "description": "Description of the agent" }, "customId": { "type": [ "string", "null" ], "description": "Custom identifier for the agent" }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format" }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format" } }, "required": [ "id", "name", "description", "customId", "createdAt", "updatedAt" ] }, "description": "The agents this flow is run against." }, "agentExpectations": { "type": "array", "items": { "$ref": "#/components/schemas/FlowExpectation" } }, "type": { "type": "string", "const": "VOICEMAIL" }, "happyPath": { "oneOf": [ { "$ref": "#/components/schemas/VoicemailFlowHappyPath" }, { "type": "null" } ], "description": "The way this flow is meant to go. Null when the flow has none, and then every way is an edge case." }, "edgeCases": { "type": "array", "items": { "$ref": "#/components/schemas/VoicemailFlowVariant" }, "description": "Every other way of running this flow." } }, "required": [ "id", "title", "source", "createdAt", "updatedAt", "agents", "agentExpectations", "type", "happyPath", "edgeCases" ], "title": "Voicemail", "description": "A flow that leaves a voicemail. Curated by Roark, read-only." }, "VoicemailFlowVariant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1 }, "systemKey": { "type": [ "string", "null" ] }, "precededByCustomerFlowId": { "type": [ "string", "null" ], "format": "uuid" }, "precededByCustomerFlowVariantId": { "type": [ "string", "null" ], "format": "uuid" }, "isGenerated": { "type": "boolean", "default": false }, "includeFlowExpectations": { "type": "boolean", "description": "Whether this variant is graded on the flow's agentExpectations as well as its additionalExpectations. False grades it on its additionalExpectations only. Always true on the happy path." }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format" }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format" }, "personaOverride": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the persona" }, "name": { "type": "string", "description": "The name the agent will identify as during conversations" }, "displayName": { "type": [ "string", "null" ], "description": "Label shown in place of the name across the dashboard (e.g. a short descriptor like \"Irate Escalator\"). The persona still identifies as `name` on calls. Omit or set null to display the name itself." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of the persona" }, "language": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ], "description": "Primary language ISO 639-1 code for the persona" }, "secondaryLanguage": { "type": [ "string", "null" ], "enum": [ "EN" ], "description": "Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish)" }, "understoodLanguages": { "type": "array", "items": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ] }, "minItems": 1, "description": "Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support." }, "accent": { "type": "string", "enum": [ "US", "US_X_SOUTH", "GB", "ES", "DE", "IN", "FR", "NL", "SA", "GR", "AU", "IT", "ID", "TH", "JP", "NZ", "PH", "SG", "MY", "HK", "TR", "PT", "IL" ], "description": "Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants" }, "age": { "type": "string", "enum": [ "CHILD", "TEENAGER", "ADULT", "ELDERLY" ], "default": "ADULT", "description": "How old the caller sounds and behaves. Only ages the persona's accent has a voice for are accepted; defaults to ADULT, which every accent supports." }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender of the persona" }, "backgroundNoise": { "type": "string", "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "default": "NONE", "description": "Background noise setting" }, "speechPace": { "type": "string", "enum": [ "SUPER_SLOW", "SLOW", "NORMAL", "FAST", "SUPER_FAST" ], "default": "NORMAL", "description": "Speech pace of the persona" }, "speechClarity": { "type": "string", "enum": [ "CLEAR", "VAGUE", "RAMBLING" ], "default": "CLEAR", "description": "Speech clarity of the persona" }, "hasDisfluencies": { "type": "boolean", "default": false, "description": "Whether the persona uses filler words like \"um\" and \"uh\"" }, "baseEmotion": { "type": "string", "enum": [ "NEUTRAL", "CHEERFUL", "CONFUSED", "FRUSTRATED", "SKEPTICAL", "RUSHED", "DISTRACTED", "ANGRY", "ANXIOUS", "SAD" ], "default": "NEUTRAL", "description": "Base emotional state of the persona" }, "intentClarity": { "type": "string", "enum": [ "CLEAR", "INDIRECT", "VAGUE" ], "default": "CLEAR", "description": "How clearly the persona expresses their intentions" }, "confirmationStyle": { "type": "string", "enum": [ "EXPLICIT", "VAGUE" ], "default": "EXPLICIT", "description": "How the persona confirms information" }, "memoryReliability": { "type": "string", "enum": [ "HIGH", "LOW" ], "default": "HIGH", "description": "How reliable the persona's memory is" }, "responseTiming": { "type": "string", "enum": [ "RELAXED", "NORMAL", "QUICK", "BARGE_IN" ], "default": "NORMAL", "description": "Deprecated and inert: it no longer affects the call. It set how long the persona waited once the agent stopped talking, and measured across production simulations it moved the reply gap by less than the noise floor, because model and speech latency dominate it. Every persona now uses one voice-activity profile. Use `interruption` for a caller who talks over the agent. Still accepted and stored so existing clients keep working. BARGE_IN is stored as `responseTiming: QUICK` with `interruption: OCCASIONAL`." }, "interruption": { "type": "string", "enum": [ "OFF", "BACKCHANNEL", "OCCASIONAL", "HEAVY" ], "default": "OFF", "description": "How much the persona talks over the agent while it is still speaking. OFF waits its turn. BACKCHANNEL makes listening noises (\"mm-hm\") over the agent without taking the floor, which tests whether the agent wrongly stops for them. OCCASIONAL adds cutting in on some long agent turns, HEAVY on most of them. Timing is randomised per turn, so two runs of the same persona do not interrupt at identical moments." }, "backstoryPrompt": { "type": [ "string", "null" ], "description": "Background story and behavioral patterns for the persona", "example": "A busy professional calling during lunch break" }, "idleMessages": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Messages the persona will say when the agent goes silent during a call. null = \"Automatic\": language-appropriate defaults are used at call time." }, "idleTimeoutSeconds": { "type": "integer", "minimum": 5, "maximum": 60, "default": 10, "description": "Seconds of silence before the persona sends an idle message" }, "idleMessageMaxSpokenCount": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3, "description": "Maximum number of idle messages the persona will send before giving up" }, "idleMessageResetCountOnUserSpeechEnabled": { "type": "boolean", "default": true, "description": "Whether the idle message counter resets when the agent speaks" }, "properties": { "type": "object", "additionalProperties": {}, "default": {}, "description": "Additional custom properties about the persona", "example": { "age": 35, "zipCode": "94105", "occupation": "Software Engineer" } }, "phoneNumber": { "type": "string", "description": "The E.164 number every call with this persona uses, when Roark has pinned one for your project. Present only when set; read-only.", "example": "+19312830919" }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "description": "Last update timestamp" } }, "required": [ "id", "name", "language", "understoodLanguages", "accent", "age", "gender", "backgroundNoise", "speechPace", "speechClarity", "hasDisfluencies", "baseEmotion", "intentClarity", "confirmationStyle", "memoryReliability", "responseTiming", "interruption", "idleMessages", "idleTimeoutSeconds", "idleMessageMaxSpokenCount", "idleMessageResetCountOnUserSpeechEnabled", "properties", "createdAt", "updatedAt" ], "description": "The persona this runs as instead of the happy path's. Null means it inherits." }, "environment": { "oneOf": [ { "$ref": "#/components/schemas/EnvironmentResponse" }, { "type": "null" } ], "description": "The conditions this runs under. Null means it inherits the happy path's." }, "additionalExpectations": { "type": "array", "items": { "$ref": "#/components/schemas/FlowExpectation" }, "description": "Graded on top of the flow's own expectations, for this variant only." }, "type": { "type": "string", "const": "VOICEMAIL" } }, "required": [ "id", "title", "precededByCustomerFlowId", "precededByCustomerFlowVariantId", "isGenerated", "includeFlowExpectations", "createdAt", "updatedAt", "personaOverride", "environment", "additionalExpectations", "type" ], "title": "Voicemail", "description": "One voicemail greeting." }, "VoicemailFlowHappyPath": { "allOf": [ { "$ref": "#/components/schemas/VoicemailFlowVariant" } ], "title": "Voicemail", "description": "One voicemail greeting." }, "CreateCustomerFlowInput": { "oneOf": [ { "$ref": "#/components/schemas/CreateScriptedCustomerFlowInput" }, { "$ref": "#/components/schemas/CreateImprovCustomerFlowInput" } ], "discriminator": { "propertyName": "type", "mapping": { "SCRIPTED": "#/components/schemas/CreateScriptedCustomerFlowInput", "IMPROV": "#/components/schemas/CreateImprovCustomerFlowInput" } }, "description": "Input for creating a customer flow. SCRIPTED writes the conversation out as a graph of turns; IMPROV gives the simulated customer a brief and lets it improvise." }, "CreateScriptedCustomerFlowInput": { "type": "object", "properties": { "type": { "type": "string", "const": "SCRIPTED" }, "title": { "type": "string", "minLength": 1, "example": "Reschedule an appointment" }, "description": { "type": [ "string", "null" ] }, "agentExpectations": { "type": "array", "items": { "$ref": "#/components/schemas/FlowExpectationInput" } }, "agentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [], "description": "Agents this flow exercises. Optional for scripted flows." }, "scriptAdherence": { "type": "string", "enum": [ "LOOSE", "STRICT" ], "description": "How closely a run follows the script. LOOSE (default) hands the whole script to the simulated customer as one prompt; it keeps the call moving whatever your agent says. STRICT runs the script as a state machine on the agent service: at every agent step the simulated customer waits, silent, until your agent has said the expected line, and only then moves on. Scripted flows only; STRICT needs the agent-service transport and is not available on realtime models. (LOOSE is the default.)" }, "offScriptPolicy": { "oneOf": [ { "$ref": "#/components/schemas/OffScriptPolicy" }, { "type": "null" } ] }, "branchingMode": { "type": "string", "enum": [ "DETERMINISTIC", "ADAPTIVE" ], "description": "How a run walks the graph. DETERMINISTIC (\"Simulate every path\" in the app) places one call per variant, each following its path exactly whatever the agent says. ADAPTIVE (\"Adapt to your agent\") collapses the paths into one call PER PERSONA, on which the simulated customer picks a branch from what the agent actually said. Both modes speak the exact authored lines, and neither changes how metrics or expectations grade. (DETERMINISTIC is the default.)" }, "graph": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStep" }, "minItems": 1, "description": "The conversation, as a graph of steps. At most 100 steps across at most 25 paths. The variants come from the graph: one per path, so they are not sent here. A CUSTOMER_TURN describes what the simulated customer says and the persona phrases it; a CUSTOMER_VERBATIM_TURN is said word for word." } }, "required": [ "type", "title", "graph" ], "title": "Scripted", "example": { "type": "SCRIPTED", "title": "Reschedule an appointment", "agentIds": [ "7c9e6679-7425-40de-944b-e07fc1f90ae7" ], "graph": [ { "type": "CUSTOMER_VERBATIM_TURN", "content": "Hi, I need to move my appointment.", "steps": [ { "type": "AGENT_TURN", "content": "Offers alternative times", "steps": [ { "type": "CUSTOMER_TURN", "content": "Takes the first slot" }, { "type": "CUSTOMER_TURN", "content": "Asks for later in the week" } ] } ] } ] } }, "FlowExpectationInput": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "What the agent under test is graded against.", "example": "The agent confirmed the new appointment time back to the customer" } }, "required": [ "prompt" ] }, "CreateImprovCustomerFlowInput": { "type": "object", "properties": { "type": { "type": "string", "const": "IMPROV" }, "title": { "type": "string", "minLength": 1, "example": "Reschedule an appointment" }, "description": { "type": [ "string", "null" ] }, "agentExpectations": { "type": "array", "items": { "$ref": "#/components/schemas/FlowExpectationInput" } }, "agentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Agents this flow exercises. At least one is required for improv flows." }, "happyPath": { "$ref": "#/components/schemas/FlowHappyPathInput" }, "edgeCases": { "type": "array", "items": { "$ref": "#/components/schemas/FlowEdgeCaseInput" }, "description": "Other ways of running it, each inheriting from the happy path what it does not name." } }, "required": [ "type", "title", "agentIds", "happyPath" ], "title": "Improv", "example": { "type": "IMPROV", "title": "Billing questions", "agentIds": [ "7c9e6679-7425-40de-944b-e07fc1f90ae7" ], "agentExpectations": [ { "prompt": "The agent never states an amount it has not verified" } ], "happyPath": { "title": "Asks about a charge", "personaOverrideId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "environmentId": "d1f5c19d-0000-4000-8000-000000000001", "prompt": "You want to understand a charge on your latest invoice." }, "edgeCases": [ { "title": "Disputes the charge", "prompt": "You are certain the charge is wrong." } ] } }, "FlowHappyPathInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "environmentId": { "type": "string", "format": "uuid", "description": "The conditions this flow runs under. Edge cases inherit them unless they name their own." }, "prompt": { "type": [ "string", "null" ] }, "precededByCustomerFlowId": { "type": [ "string", "null" ], "format": "uuid" }, "precededByCustomerFlowVariantId": { "type": [ "string", "null" ], "format": "uuid" }, "additionalExpectations": { "type": "array", "items": { "$ref": "#/components/schemas/FlowExpectationInput" }, "description": "The expectations graded on this variant only, on top of the flow's own. Sent as the complete set: it replaces whatever the variant had, so omit it to leave the set alone and send [] to clear it. Improv flows only: a scripted variant's expectations come from the agent turns on its path and are rewritten on every graph edit." }, "personaOverrideId": { "type": "string", "format": "uuid", "description": "The persona this flow runs as. Edge cases inherit it unless they name their own." } }, "required": [ "title", "environmentId", "personaOverrideId" ], "description": "The way this flow is meant to go." }, "FlowEdgeCaseInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "environmentId": { "type": [ "string", "null" ], "format": "uuid" }, "prompt": { "type": [ "string", "null" ] }, "precededByCustomerFlowId": { "type": [ "string", "null" ], "format": "uuid" }, "precededByCustomerFlowVariantId": { "type": [ "string", "null" ], "format": "uuid" }, "includeFlowExpectations": { "type": "boolean", "description": "Whether this edge case is graded on the flow's agentExpectations as well as its own additionalExpectations. Defaults to true; false grades it on its additionalExpectations only." }, "additionalExpectations": { "type": "array", "items": { "$ref": "#/components/schemas/FlowExpectationInput" }, "description": "The expectations graded on this variant only, on top of the flow's own. Sent as the complete set: it replaces whatever the variant had, so omit it to leave the set alone and send [] to clear it. Improv flows only: a scripted variant's expectations come from the agent turns on its path and are rewritten on every graph edit." }, "personaOverrideId": { "type": [ "string", "null" ], "format": "uuid", "description": "The persona this runs as. Omit to inherit the happy path's." } }, "required": [ "title" ] }, "UpdateCustomerFlowInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "scriptAdherence": { "type": "string", "enum": [ "LOOSE", "STRICT" ], "description": "Scripted flows only. How closely a run follows the script. LOOSE (default) hands the whole script to the simulated customer as one prompt; it keeps the call moving whatever your agent says. STRICT runs the script as a state machine on the agent service: at every agent step the simulated customer waits, silent, until your agent has said the expected line, and only then moves on. Scripted flows only; STRICT needs the agent-service transport and is not available on realtime models." }, "offScriptPolicy": { "oneOf": [ { "$ref": "#/components/schemas/OffScriptPolicy" }, { "type": "null" } ] }, "branchingMode": { "type": "string", "enum": [ "DETERMINISTIC", "ADAPTIVE" ], "description": "Scripted flows only. How a run walks the graph. DETERMINISTIC (\"Simulate every path\" in the app) places one call per variant, each following its path exactly whatever the agent says. ADAPTIVE (\"Adapt to your agent\") collapses the paths into one call PER PERSONA, on which the simulated customer picks a branch from what the agent actually said. Both modes speak the exact authored lines, and neither changes how metrics or expectations grade." }, "agentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Replaces the linked agents. Omit to leave them unchanged. An improv flow must keep at least one; a scripted flow can be left with none." }, "agentExpectations": { "type": "array", "items": { "$ref": "#/components/schemas/FlowExpectationInput" }, "description": "Replaces the flow-level expectations. Omit to leave them unchanged." } }, "description": "Fields to change on a customer flow. The step graph is edited through PUT /graph instead." }, "ReplaceFlowStepsResponse": { "type": "object", "properties": { "graph": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStep" } }, "variantsReshaped": { "type": "boolean", "description": "True when the write changed the set of paths, so the flow's variants were re-seeded and any variant id you were holding may no longer exist." }, "happyPath": { "oneOf": [ { "$ref": "#/components/schemas/FlowHappyPath" }, { "type": "null" } ], "description": "The happy path after the write." }, "edgeCases": { "type": "array", "items": { "$ref": "#/components/schemas/FlowVariant" }, "description": "The edge cases after the write." }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "graph", "variantsReshaped", "happyPath", "edgeCases", "warnings" ] }, "FlowHappyPath": { "oneOf": [ { "$ref": "#/components/schemas/ScriptedFlowHappyPath" }, { "$ref": "#/components/schemas/ImprovFlowHappyPath" }, { "$ref": "#/components/schemas/VoicemailFlowHappyPath" } ], "discriminator": { "propertyName": "type", "mapping": { "SCRIPTED": "#/components/schemas/ScriptedFlowHappyPath", "IMPROV": "#/components/schemas/ImprovFlowHappyPath", "VOICEMAIL": "#/components/schemas/VoicemailFlowHappyPath" } }, "description": "The way a customer flow is meant to go." }, "FlowVariant": { "oneOf": [ { "$ref": "#/components/schemas/ScriptedFlowVariant" }, { "$ref": "#/components/schemas/ImprovFlowVariant" }, { "$ref": "#/components/schemas/VoicemailFlowVariant" } ], "discriminator": { "propertyName": "type", "mapping": { "SCRIPTED": "#/components/schemas/ScriptedFlowVariant", "IMPROV": "#/components/schemas/ImprovFlowVariant", "VOICEMAIL": "#/components/schemas/VoicemailFlowVariant" } }, "description": "One way of running a customer flow." }, "ReplaceFlowStepsInput": { "type": "object", "properties": { "graph": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStep" }, "minItems": 1, "description": "The complete graph. This replaces the flow's existing steps rather than merging into them." }, "allowUnmerge": { "type": "boolean", "description": "Confirms a write that drops branches which currently rejoin. Only needed when the request omits mergeIntoNodeIds references the flow already had; a faithful round trip never needs it." } }, "required": [ "graph" ] }, "UpdateFlowVariantInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "environmentId": { "type": [ "string", "null" ], "format": "uuid" }, "prompt": { "type": [ "string", "null" ] }, "precededByCustomerFlowId": { "type": [ "string", "null" ], "format": "uuid" }, "precededByCustomerFlowVariantId": { "type": [ "string", "null" ], "format": "uuid" }, "includeFlowExpectations": { "type": "boolean", "description": "Whether this edge case is graded on the flow's agentExpectations as well as its own additionalExpectations. Defaults to true; false grades it on its additionalExpectations only." }, "personaOverrideId": { "type": [ "string", "null" ], "format": "uuid", "description": "The persona this runs as. Null on an edge case inherits the happy path's." }, "additionalExpectations": { "type": "array", "items": { "$ref": "#/components/schemas/FlowExpectationInput" }, "description": "The expectations graded on this variant only, on top of the flow's own. Sent as the complete set: it replaces whatever the variant had, so omit it to leave the set alone and send [] to clear it. Improv flows only: a scripted variant's expectations come from the agent turns on its path and are rewritten on every graph edit." } }, "description": "Fields to change on a variant. Omitted fields are left alone. Making a variant the default is a separate operation, since it also demotes the current default." }, "DuplicateCustomerFlowInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "Title for the copy. Defaults to \"Copy of\" the source flow.", "example": "Reschedule an appointment (v2)" }, "agentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Agents to link on the copy. Omit to carry the source flow's agents over. Required when the source is a Roark-managed flow with no agents of its own." } }, "description": "Options for duplicating a customer flow. Every field is optional." }, "AddFlowEdgeCaseInput": { "$ref": "#/components/schemas/FlowEdgeCaseInput" }, "HttpRequestDefinitionResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "HTTP request definition ID" }, "scope": { "type": "string", "enum": [ "AGENT_OUTBOUND_DIAL" ], "description": "Scope of the HTTP request definition" }, "description": { "type": [ "string", "null" ], "description": "Description of the HTTP request definition" }, "url": { "type": "string", "description": "URL for the HTTP request" }, "method": { "type": "string", "enum": [ "POST", "PUT", "PATCH", "GET" ], "description": "HTTP method: POST, PUT, PATCH, or GET" }, "body": { "type": [ "string", "null" ], "description": "Request body as a string" }, "parsedBody": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "string" }, { "type": "null" } ], "description": "Parsed body as a JSON object if valid JSON, otherwise the raw string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Request headers as key-value pairs" }, "isConfigManaged": { "type": "boolean", "description": "Whether this definition is managed by config-as-code. A managed definition is reconciled from your config: PUT returns 409, and changes belong in the config file (or detach it first)." }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "description": "Last update timestamp" } }, "required": [ "id", "scope", "description", "url", "method", "body", "parsedBody", "headers", "isConfigManaged", "createdAt", "updatedAt" ], "description": "HTTP request definition" }, "HttpRequestDefinitionCreateResponse": { "allOf": [ { "$ref": "#/components/schemas/HttpRequestDefinitionResponse" } ], "properties": { "signingSecret": { "type": "string", "description": "Signing secret (only returned on creation)" } }, "required": [ "signingSecret" ], "description": "HTTP request definition with signing secret (returned on creation)" }, "CreateHttpRequestDefinitionInput": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "AGENT_OUTBOUND_DIAL" ], "description": "Scope: AGENT_OUTBOUND_DIAL" }, "url": { "type": "string", "format": "uri", "description": "URL for the HTTP request" }, "description": { "type": [ "string", "null" ], "description": "Description of the HTTP request definition" }, "method": { "type": "string", "enum": [ "POST", "PUT", "PATCH", "GET" ], "default": "POST", "description": "HTTP method (default: POST)" }, "body": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Request body template. Accepts a JSON object or a string with placeholders like {{phoneNumberToDial}}. Objects are serialized to JSON for storage." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Request headers as key-value pairs" } }, "required": [ "scope", "url" ], "description": "Input for creating an HTTP request definition" }, "UpdateHttpRequestDefinitionInput": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "URL for the HTTP request" }, "description": { "type": [ "string", "null" ], "description": "Description of the HTTP request definition" }, "method": { "type": "string", "enum": [ "POST", "PUT", "PATCH", "GET" ], "description": "HTTP method: POST, PUT, PATCH, or GET" }, "body": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Request body template. Accepts a JSON object or a string with placeholders like {{phoneNumberToDial}}. Objects are serialized to JSON for storage." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Request headers as key-value pairs" } }, "description": "Input for updating an HTTP request definition" }, "WebhookResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Webhook ID" }, "description": { "type": [ "string", "null" ], "description": "Webhook description" }, "url": { "type": "string", "description": "Webhook URL" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Request headers" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "CALL_ANALYSIS_COMPLETED", "CALL_ANALYSIS_FAILED", "CALL_ANALYSIS_CANCELLED", "CALL_EVALUATION_COMPLETED", "CALL_EVALUATION_FAILED", "SIMULATION_RUN_PLAN_JOB_STARTED", "SIMULATION_RUN_PLAN_JOB_COMPLETED", "SIMULATION_RUN_PLAN_JOB_FAILED", "SIMULATION_RUN_PLAN_JOB_CANCELLED", "SIMULATION_JOB_STARTED", "SIMULATION_JOB_COMPLETED", "SIMULATION_JOB_FAILED", "SIMULATION_JOB_CANCELLED", "METRIC_COLLECTION_JOB_COMPLETED", "METRIC_COLLECTION_JOB_FAILED", "CHAT_ANALYSIS_COMPLETED", "CHAT_ANALYSIS_FAILED", "ISSUE_OPENED", "ISSUE_RESOLVED" ] }, "description": "Event types this webhook is subscribed to" }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "description": "Last update timestamp" } }, "required": [ "id", "description", "url", "headers", "events", "createdAt", "updatedAt" ], "description": "Webhook with its subscribed event types" }, "CreateWebhookResponse": { "allOf": [ { "$ref": "#/components/schemas/WebhookResponse" } ], "properties": { "signingSecret": { "type": "string", "description": "Signing secret (only returned on creation)" } }, "required": [ "signingSecret" ], "description": "Webhook response with signing secret (returned on creation)" }, "CreateWebhookInput": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook URL" }, "description": { "type": [ "string", "null" ], "description": "Webhook description" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Request headers (e.g. authorization tokens)" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "CALL_ANALYSIS_COMPLETED", "CALL_ANALYSIS_FAILED", "CALL_ANALYSIS_CANCELLED", "CALL_EVALUATION_COMPLETED", "CALL_EVALUATION_FAILED", "SIMULATION_RUN_PLAN_JOB_STARTED", "SIMULATION_RUN_PLAN_JOB_COMPLETED", "SIMULATION_RUN_PLAN_JOB_FAILED", "SIMULATION_RUN_PLAN_JOB_CANCELLED", "SIMULATION_JOB_STARTED", "SIMULATION_JOB_COMPLETED", "SIMULATION_JOB_FAILED", "SIMULATION_JOB_CANCELLED", "METRIC_COLLECTION_JOB_COMPLETED", "METRIC_COLLECTION_JOB_FAILED", "CHAT_ANALYSIS_COMPLETED", "CHAT_ANALYSIS_FAILED", "ISSUE_OPENED", "ISSUE_RESOLVED" ] }, "minItems": 1, "description": "Event types to subscribe to (at least one required)" } }, "required": [ "url", "events" ], "description": "Input for creating a webhook" }, "Issue": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "alertId": { "type": [ "string", "null" ], "format": "uuid", "description": "Only set when source is an alert" }, "source": { "type": "string", "enum": [ "TREND_ALERT", "SINGLE_CALL_ALERT", "TRACE_FAILURE", "MANUAL", "API", "AGENT" ], "description": "Who opened the issue" }, "title": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "severity": { "type": [ "string", "null" ], "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "Coarse priority — LOW / MEDIUM / HIGH / CRITICAL" }, "status": { "type": "string", "enum": [ "OPEN", "ACKED", "RESOLVED" ], "description": "Lifecycle state" }, "fingerprint": { "type": "string", "description": "Producer-supplied dedup key. Same fingerprint coalesces into the same issue." }, "eventCount": { "type": "integer", "description": "How many times this issue has been observed." }, "lastEventAt": { "type": [ "string", "null" ], "description": "Timestamp of the most recent occurrence, or null if no events yet." }, "openedAt": { "type": "string" }, "resolvedAt": { "type": [ "string", "null" ] }, "assigneeUserId": { "type": [ "string", "null" ], "format": "uuid" }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/IssueEvidence" }, "description": "Calls / chats attached as evidence" }, "createdAt": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "organizationId", "projectId", "alertId", "source", "title", "summary", "severity", "status", "fingerprint", "eventCount", "lastEventAt", "openedAt", "resolvedAt", "assigneeUserId", "evidence", "createdAt", "updatedAt" ], "description": "An issue surfaced on the Roark Issues page" }, "IssueEvidence": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "callId": { "type": [ "string", "null" ], "format": "uuid", "description": "Call attached as evidence, or null" }, "chatId": { "type": [ "string", "null" ], "format": "uuid", "description": "Chat attached as evidence, or null" }, "observedAt": { "type": "string", "description": "When the evidence was observed (ISO-8601)" } }, "required": [ "id", "callId", "chatId", "observedAt" ] }, "CreateIssueInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 280, "description": "Short headline — required, max 280 characters" }, "summary": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2000, "description": "Longer-form context — optional, max 2000 characters" }, "severity": { "type": [ "string", "null" ], "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "Coarse priority. Null when unset." }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/CreateIssueEvidence" }, "maxItems": 50, "default": [], "description": "Calls / chats to attach as evidence. Optional; max 50 entries per issue." } }, "required": [ "title" ] }, "CreateIssueEvidence": { "type": "object", "properties": { "callId": { "type": "string", "format": "uuid" }, "chatId": { "type": "string", "format": "uuid" } }, "description": "A call or chat to attach as evidence (exactly one of `callId` / `chatId`)" }, "AutoimproveJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "agentId": { "type": "string", "format": "uuid" }, "stagingAgentId": { "type": "string", "format": "uuid" }, "stagingKind": { "type": "string", "enum": [ "DESIGNATED", "SHADOW", "CHANNEL" ] }, "customerIntegrationId": { "type": [ "string", "null" ], "format": "uuid" }, "objectiveMetricDefinitionId": { "type": "string", "format": "uuid" }, "objectiveLabel": { "type": "string" }, "targetValue": { "type": "number" }, "baselineValue": { "type": [ "number", "null" ] }, "currentValue": { "type": [ "number", "null" ] }, "trigger": { "type": "string", "enum": [ "ISSUE", "RUN_THRESHOLD_FAILED", "USER", "DEGRADATION" ] }, "issueId": { "type": [ "string", "null" ], "format": "uuid" }, "objectiveId": { "type": [ "string", "null" ], "format": "uuid" }, "validationRunPlanId": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "RUNNING", "NEEDS_INPUT", "PAUSED", "AWAITING_PROMOTE", "PROMOTED", "NO_FIX", "CANCELLED", "FAILED" ] }, "workingMemory": { "type": [ "string", "null" ] }, "finalReport": { "type": [ "string", "null" ] }, "maxIterations": { "type": "integer" }, "maxSimCalls": { "type": "integer" }, "iterationCount": { "type": "integer" }, "simCallsUsed": { "type": "integer" }, "initiatedByUserId": { "type": [ "string", "null" ], "format": "uuid" }, "concludedAt": { "type": [ "string", "null" ], "description": "When the job reached a terminal status (ISO 8601)." }, "createdAt": { "type": "string", "description": "When the job was created (ISO 8601)." }, "updatedAt": { "type": "string", "description": "When the job last changed (ISO 8601)." } }, "required": [ "id", "organizationId", "projectId", "agentId", "stagingAgentId", "stagingKind", "customerIntegrationId", "objectiveMetricDefinitionId", "objectiveLabel", "targetValue", "baselineValue", "currentValue", "trigger", "issueId", "objectiveId", "validationRunPlanId", "status", "workingMemory", "finalReport", "maxIterations", "maxSimCalls", "iterationCount", "simCallsUsed", "initiatedByUserId", "concludedAt", "createdAt", "updatedAt" ], "description": "One Autoimprove job: Roark autonomously improving one agent toward one objective metric. Roark only ever changes the staging agent (a shadow clone by default); production changes exactly once, when verified changes are promoted." }, "AutoimproveJobDetail": { "allOf": [ { "$ref": "#/components/schemas/AutoimproveJob" } ], "properties": { "logEntries": { "type": "array", "items": { "$ref": "#/components/schemas/AutoimproveLogEntry" }, "description": "The full worklog, oldest first." } }, "required": [ "logEntries" ] }, "AutoimproveLogEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderIndex": { "type": "integer" }, "kind": { "type": "string", "enum": [ "STARTED", "REASONING", "CHANGE", "VALIDATION", "VERDICT", "SLEEP", "QUESTION", "GUIDANCE", "STATUS", "SETUP", "SUITE" ] }, "text": { "type": "string" }, "questionOptions": { "type": [ "array", "null" ], "items": { "type": "string" } }, "configPushId": { "type": [ "string", "null" ], "format": "uuid" }, "simulationRunPlanJobId": { "type": [ "string", "null" ], "format": "uuid" }, "trialCount": { "type": [ "integer", "null" ] }, "passRateBefore": { "type": [ "number", "null" ] }, "passRateAfter": { "type": [ "number", "null" ] }, "createdAt": { "type": "string", "description": "When the entry was written (ISO 8601)." } }, "required": [ "id", "orderIndex", "kind", "text", "questionOptions", "configPushId", "simulationRunPlanJobId", "trialCount", "passRateBefore", "passRateAfter", "createdAt" ], "description": "One entry in the job's worklog: what Roark did or observed at that step. VALIDATION entries carry the batch's trial count and pass-rate movement; QUESTION entries carry the quick-reply options Roark is waiting on." }, "CreateAutoimproveJobInput": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid", "description": "The production agent to improve. It is never modified until you promote.", "example": "b3b0c8e2-4c1d-4f6a-9e2b-1a2b3c4d5e6f" }, "objectiveMetricDefinitionId": { "type": "string", "format": "uuid", "description": "The metric that defines success: a pass/fail metric, or a threshold variant of a scale metric (for example \"PII Handling >= 4\"). Roark measures the pass rate of this metric across simulated calls.", "example": "f2f0c8e2-4c1d-4f6a-9e2b-1a2b3c4d5e6f" }, "objectiveLabel": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Human-readable label for the objective, shown everywhere the job appears.", "example": "Consent collection should pass" }, "targetValue": { "type": "number", "minimum": 1, "maximum": 100, "default": 90, "description": "The pass-rate percentage that counts as fixed. Defaults to 90.", "example": 90 }, "stagingAgentId": { "type": "string", "format": "uuid", "description": "An existing agent to stage changes on instead of the default shadow clone. Must be a different agent from agentId, on the same provider." }, "customerIntegrationId": { "type": "string", "format": "uuid", "description": "The provider integration whose credentials Roark uses. Omit to use the project's active integration for the agent's provider. The integration must have agent config writes enabled." }, "validationRunPlanId": { "type": "string", "format": "uuid", "description": "An existing simulation run plan to validate with. Omit to let Roark author its own suite." }, "maxIterations": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Cap on decision turns. Defaults to 50." }, "maxSimCalls": { "type": "integer", "minimum": 1, "maximum": 2000, "description": "Cap on simulated calls dialed. Defaults to 200." } }, "required": [ "agentId", "objectiveMetricDefinitionId", "objectiveLabel" ] }, "AutoimproveTextInput": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "The message for Roark.", "example": "Keep the current voice; focus on the closing confirmation." } }, "required": [ "text" ] }, "ResolveManagedConfigResponse": { "type": "object", "properties": { "key": { "type": "string" }, "channel": { "type": "string", "enum": [ "production", "staging" ], "description": "Which channel this session resolved to." }, "revisionId": { "type": "string", "format": "uuid" }, "document": { "type": "object", "additionalProperties": {}, "description": "The config JSON to apply." }, "simulationJobId": { "type": [ "string", "null" ], "format": "uuid", "description": "Set when this session is a Roark simulation call. Stamp it (and the revisionId) into your session metadata so analysis attributes the call correctly." } }, "required": [ "key", "channel", "revisionId", "document", "simulationJobId" ] }, "ResolveManagedConfigRequest": { "type": "object", "properties": { "defaults": { "type": "object", "additionalProperties": {}, "description": "Your baked-in config. On the first fetch of an unknown key this registers the config and becomes revision 1, so integration is a single call. Ignored once the key exists.", "example": { "systemPrompt": "You are a helpful receptionist.", "model": "gpt-4.1", "temperature": 0.4 } }, "session": { "type": "object", "properties": { "sessionId": { "type": "string", "maxLength": 255, "description": "Your session or room identifier, for correlation." }, "callerNumber": { "type": "string", "maxLength": 32, "description": "The number calling your agent (E.164). Required for simulation recognition.", "example": "+15551230000" }, "calledNumber": { "type": "string", "maxLength": 32, "description": "The number your agent was reached on (E.164).", "example": "+15559870000" } }, "description": "Session context. When the call was originated by a Roark simulation, Roark recognizes it here and serves the staging revision for this session only; real traffic always gets production." } } }, "ManagedAgentConfig": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "description": "The stable handle your code fetches by.", "example": "support-agent" }, "agentId": { "type": [ "string", "null" ], "format": "uuid", "description": "The linked Roark agent, when one exists." }, "productionRevisionId": { "type": [ "string", "null" ], "format": "uuid", "description": "The revision real traffic reads." }, "stagingRevisionId": { "type": [ "string", "null" ], "format": "uuid", "description": "The candidate revision Roark test calls read. Null when nothing is staged." }, "createdAt": { "type": "string", "description": "ISO 8601." }, "updatedAt": { "type": "string", "description": "ISO 8601." } }, "required": [ "id", "key", "agentId", "productionRevisionId", "stagingRevisionId", "createdAt", "updatedAt" ], "description": "A managed config for a code-first agent (LiveKit, Pipecat, or any stack using the SDK): your agent fetches its tunable surface from Roark at session start. Two channels: production for real traffic, staging for candidates under test." }, "ManagedAgentConfigDetail": { "allOf": [ { "$ref": "#/components/schemas/ManagedAgentConfig" } ], "properties": { "revisions": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentConfigRevision" }, "description": "Recent revisions, newest first." } }, "required": [ "revisions" ] }, "ManagedAgentConfigRevision": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "document": { "type": "object", "additionalProperties": {}, "description": "The config JSON, verbatim." }, "parentRevisionId": { "type": [ "string", "null" ], "format": "uuid" }, "createdByType": { "type": "string", "enum": [ "CUSTOMER", "AUTOIMPROVE" ], "description": "Who wrote it: your own pushes, or the Autoimprove loop staging a candidate." }, "summary": { "type": [ "string", "null" ], "description": "One-line story of the change." }, "createdAt": { "type": "string", "description": "ISO 8601." } }, "required": [ "id", "document", "parentRevisionId", "createdByType", "summary", "createdAt" ] }, "WriteManagedConfigRequest": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "production", "staging" ], "description": "Which channel to write." }, "document": { "type": "object", "additionalProperties": {}, "description": "The full config JSON for the new revision." }, "summary": { "type": "string", "maxLength": 500, "description": "One-line story of the change." }, "agentId": { "type": "string", "format": "uuid", "description": "Link this config to a Roark agent (the one your calls report). Required before Autoimprove can run on it: the link is how a fix finds the config channel." } }, "required": [ "channel", "document" ] }, "AnalyticsSchema": { "type": "object", "properties": { "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "outputType": { "type": "string" }, "isThreshold": { "type": "boolean" }, "defaultAggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ] }, "aggregations": { "type": "array", "items": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ] } } }, "required": [ "id", "slug", "name", "outputType", "isThreshold", "defaultAggregation", "aggregations" ] } }, "measureTypes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC", "CONVERSATION", "UPTIME" ] }, "description": { "type": "string" }, "aggregations": { "type": "array", "items": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ] } } }, "required": [ "type", "description", "aggregations" ] } }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ] }, "description": { "type": "string" }, "properties": { "type": "array", "items": { "type": "object", "properties": { "property": { "type": "string" }, "description": { "type": "string" } }, "required": [ "property", "description" ] } } }, "required": [ "type", "description", "properties" ] } }, "breakdowns": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "DATASET" ] }, "description": { "type": "string" } }, "required": [ "type", "description" ] } }, "callProperties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "valueType": { "type": "string" }, "isSystem": { "type": "boolean" } }, "required": [ "name", "valueType", "isSystem" ] } }, "operators": { "type": "array", "items": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ] } }, "intervals": { "type": "array", "items": { "type": "string", "enum": [ "HOUR", "DAY", "WEEK", "MONTH" ] } }, "displayTypes": { "type": "array", "items": { "type": "string", "enum": [ "LINE", "NUMBER", "RADAR", "STACKED_BAR", "TABLE" ] } } }, "required": [ "metrics", "measureTypes", "filters", "breakdowns", "callProperties", "operators", "intervals", "displayTypes" ], "description": "What can be queried in this project: metrics (by slug), measure types, filters, breakdowns." }, "AnalyticsResult": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "interval": { "type": "string", "enum": [ "HOUR", "DAY", "WEEK", "MONTH" ] }, "timezone": { "type": "string" }, "series": { "type": "array", "items": { "type": "object", "properties": { "measureIndex": { "type": "integer" }, "type": { "type": "string", "enum": [ "METRIC", "CONVERSATION", "UPTIME" ] }, "metric": { "type": [ "string", "null" ] }, "aggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ] }, "breakdownValue": { "type": [ "string", "null" ] }, "comparisonGroup": { "type": [ "string", "null" ] }, "value": { "type": "number" }, "sampleSize": { "type": [ "number", "null" ] }, "comparisonValue": { "type": [ "number", "null" ] }, "percentageOfBaseline": { "type": [ "number", "null" ] }, "buckets": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "value": { "type": "number" }, "passed": { "type": "number" }, "sampleSize": { "type": "number" }, "comparisonDate": { "type": "string" }, "comparisonValue": { "type": "number" }, "percentageOfBaseline": { "type": "number" } }, "required": [ "date", "value" ] } } }, "required": [ "measureIndex", "type", "metric", "aggregation", "breakdownValue", "comparisonGroup", "value", "sampleSize", "comparisonValue", "percentageOfBaseline", "buckets" ] } }, "omittedSeries": { "type": "integer" } }, "required": [ "from", "to", "interval", "timezone", "series", "omittedSeries" ], "description": "One series per measure (or per breakdown value / comparison group). `value` is the aggregate over the whole window; `buckets` hold the per-interval values." }, "AnalyticsQuery": { "type": "object", "properties": { "measures": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC", "CONVERSATION", "UPTIME" ], "description": "METRIC (default): a metric's values. CONVERSATION: conversation counts. UPTIME: health-check outcomes." }, "metric": { "type": "string", "minLength": 1, "description": "The metric's slug (e.g. `task_completion`) or id. Required for METRIC." }, "aggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ], "description": "Defaults by output type: AVG for numeric metrics, COUNT (split by value) for classification and text, PASS_RATE for thresholds and uptime, COUNT for conversations." }, "percentile": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Required with PERCENTILE, e.g. 95." }, "distinctBy": { "type": "string", "enum": [ "NONE", "CALL" ], "description": "CALL (default for metrics) folds each conversation to one value first, so a long call does not outweigh a short one. NONE aggregates every value." }, "nestedAggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ], "description": "How each conversation is folded when distinctBy is CALL. Defaults to SUM under SUM, else AVG." }, "nestedAggregationPercentile": { "type": "integer", "minimum": 0, "maximum": 100 }, "passOperator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "PASS_RATE condition operator. Omit for a threshold metric: its own condition is used." }, "passValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "PASS_RATE condition value, e.g. 4 or \"resolved\"." }, "breakdown": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "DATASET" ] }, "property": { "type": "string", "description": "The property to split by. Required for CALL_PROPERTY and METRIC_PROPERTY." } }, "required": [ "type" ], "description": "Split the measure into one series per value of this dimension (the largest 50 are returned). Ignored while comparisonGroups are set: each group is then one series." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "maxItems": 20, "description": "Filters for this measure only, on top of the query's filters." }, "isBaseline": { "type": "boolean", "description": "Mark one measure as the baseline: every series also reports its value as a percentage of it." }, "color": { "type": "string", "enum": [ "GREEN", "RED", "ORANGE", "PURPLE", "GREY", "BLUE", "PEACH", "TEAL", "INDIGO", "AMBER", "ROSE", "CYAN" ], "description": "Chart color on a dashboard." } } }, "minItems": 1, "maxItems": 10, "description": "What to aggregate: 1 to 10 measures." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "maxItems": 20, "description": "Applied to every measure, on top of each measure's own filters." }, "interval": { "type": "string", "enum": [ "HOUR", "DAY", "WEEK", "MONTH" ], "description": "Bucket size. Defaults from the window's length and steps coarser when the window would exceed 500 buckets." }, "comparisonMode": { "type": "string", "enum": [ "NONE", "PREVIOUS_PERIOD" ], "description": "PREVIOUS_PERIOD adds the preceding window of the same length to every series." }, "comparisonGroups": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The series label; unique within the query." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "minItems": 1, "maxItems": 20 }, "color": { "type": "string", "enum": [ "GREEN", "RED", "ORANGE", "PURPLE", "GREY", "BLUE", "PEACH", "TEAL", "INDIGO", "AMBER", "ROSE", "CYAN" ] } }, "required": [ "name", "filters" ] }, "minItems": 2, "maxItems": 5, "description": "Run every measure once per named filter set, e.g. one group per agent." }, "timeRange": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "LAST" }, "value": { "type": "integer", "minimum": 1, "maximum": 1000 }, "unit": { "type": "string", "enum": [ "DAYS", "WEEKS", "MONTHS" ] } }, "required": [ "type", "value", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "CALENDAR_ALIGNED" }, "period": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "THIS_WEEK", "LAST_WEEK", "THIS_MONTH", "LAST_MONTH", "THIS_YEAR", "LAST_YEAR" ] } }, "required": [ "type", "period" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "FIXED" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "type", "from", "to" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "SINCE" }, "from": { "type": "string", "format": "date-time" } }, "required": [ "type", "from" ] } ], "description": "Defaults to the last 30 days." }, "timezone": { "type": "string", "minLength": 1, "description": "IANA zone that buckets and calendar periods align to, e.g. America/New_York. Defaults to UTC." }, "includeBuckets": { "type": "boolean", "description": "Set false to return only the window totals." } }, "required": [ "measures" ], "description": "An aggregate query: one or more measures over a time window, optionally filtered, broken down and compared. GET /v1/analytics/schema lists the metrics, filters and breakdowns available.", "example": { "measures": [ { "metric": "sentiment_score", "aggregation": "AVG" }, { "type": "CONVERSATION", "aggregation": "COUNT" } ], "timeRange": { "type": "LAST", "value": 7, "unit": "DAYS" }, "interval": "DAY", "timezone": "Europe/London", "filters": [ { "type": "MODALITY", "value": "call" } ] } }, "DashboardSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "isDefault": { "type": "boolean" }, "configManaged": { "type": "boolean", "description": "Managed by config as code (`kind: dashboard`). A managed dashboard is read-only here: edits return 409; change it in the config file." }, "timeRange": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "LAST" }, "value": { "type": "integer", "minimum": 1, "maximum": 1000 }, "unit": { "type": "string", "enum": [ "DAYS", "WEEKS", "MONTHS" ] } }, "required": [ "type", "value", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "CALENDAR_ALIGNED" }, "period": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "THIS_WEEK", "LAST_WEEK", "THIS_MONTH", "LAST_MONTH", "THIS_YEAR", "LAST_YEAR" ] } }, "required": [ "type", "period" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "FIXED" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "type", "from", "to" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "SINCE" }, "from": { "type": "string", "format": "date-time" } }, "required": [ "type", "from" ] }, { "type": "null" } ], "description": "The window: LAST n DAYS/WEEKS/MONTHS up to now, a CALENDAR_ALIGNED period (TODAY, YESTERDAY, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, THIS_YEAR, LAST_YEAR), FIXED from/to, or SINCE a date. At most 731 days (two years)." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "isDefault", "configManaged", "timeRange", "createdAt", "updatedAt" ] }, "Dashboard": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "isDefault": { "type": "boolean" }, "configManaged": { "type": "boolean", "description": "Managed by config as code (`kind: dashboard`). A managed dashboard is read-only here: edits return 409; change it in the config file." }, "timeRange": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "LAST" }, "value": { "type": "integer", "minimum": 1, "maximum": 1000 }, "unit": { "type": "string", "enum": [ "DAYS", "WEEKS", "MONTHS" ] } }, "required": [ "type", "value", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "CALENDAR_ALIGNED" }, "period": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "THIS_WEEK", "LAST_WEEK", "THIS_MONTH", "LAST_MONTH", "THIS_YEAR", "LAST_YEAR" ] } }, "required": [ "type", "period" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "FIXED" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "type", "from", "to" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "SINCE" }, "from": { "type": "string", "format": "date-time" } }, "required": [ "type", "from" ] }, { "type": "null" } ], "description": "The window: LAST n DAYS/WEEKS/MONTHS up to now, a CALENDAR_ALIGNED period (TODAY, YESTERDAY, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, THIS_YEAR, LAST_YEAR), FIXED from/to, or SINCE a date. At most 731 days (two years)." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] } }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "measures": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC", "CONVERSATION", "UPTIME" ], "description": "METRIC (default): a metric's values. CONVERSATION: conversation counts. UPTIME: health-check outcomes." }, "metric": { "type": "string", "minLength": 1, "description": "The metric's slug (e.g. `task_completion`) or id. Required for METRIC." }, "aggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ], "description": "Defaults by output type: AVG for numeric metrics, COUNT (split by value) for classification and text, PASS_RATE for thresholds and uptime, COUNT for conversations." }, "percentile": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Required with PERCENTILE, e.g. 95." }, "distinctBy": { "type": "string", "enum": [ "NONE", "CALL" ], "description": "CALL (default for metrics) folds each conversation to one value first, so a long call does not outweigh a short one. NONE aggregates every value." }, "nestedAggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ], "description": "How each conversation is folded when distinctBy is CALL. Defaults to SUM under SUM, else AVG." }, "nestedAggregationPercentile": { "type": "integer", "minimum": 0, "maximum": 100 }, "passOperator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "PASS_RATE condition operator. Omit for a threshold metric: its own condition is used." }, "passValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "PASS_RATE condition value, e.g. 4 or \"resolved\"." }, "breakdown": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "DATASET" ] }, "property": { "type": "string", "description": "The property to split by. Required for CALL_PROPERTY and METRIC_PROPERTY." } }, "required": [ "type" ], "description": "Split the measure into one series per value of this dimension (the largest 50 are returned). Ignored while comparisonGroups are set: each group is then one series." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "maxItems": 20, "description": "Filters for this measure only, on top of the query's filters." }, "isBaseline": { "type": "boolean", "description": "Mark one measure as the baseline: every series also reports its value as a percentage of it." }, "color": { "type": "string", "enum": [ "GREEN", "RED", "ORANGE", "PURPLE", "GREY", "BLUE", "PEACH", "TEAL", "INDIGO", "AMBER", "ROSE", "CYAN" ], "description": "Chart color on a dashboard." } } }, "minItems": 1, "maxItems": 10, "description": "What to aggregate: 1 to 10 measures." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "maxItems": 20, "description": "Applied to every measure, on top of each measure's own filters." }, "interval": { "type": "string", "enum": [ "HOUR", "DAY", "WEEK", "MONTH" ], "description": "Bucket size. Defaults from the window's length and steps coarser when the window would exceed 500 buckets." }, "comparisonMode": { "type": "string", "enum": [ "NONE", "PREVIOUS_PERIOD" ], "description": "PREVIOUS_PERIOD adds the preceding window of the same length to every series." }, "comparisonGroups": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The series label; unique within the query." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "minItems": 1, "maxItems": 20 }, "color": { "type": "string", "enum": [ "GREEN", "RED", "ORANGE", "PURPLE", "GREY", "BLUE", "PEACH", "TEAL", "INDIGO", "AMBER", "ROSE", "CYAN" ] } }, "required": [ "name", "filters" ] }, "minItems": 2, "maxItems": 5, "description": "Run every measure once per named filter set, e.g. one group per agent." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Unique on the dashboard: how the widget is matched on update." }, "description": { "type": "string", "maxLength": 2000 }, "display": { "type": "string", "enum": [ "LINE", "NUMBER", "RADAR", "STACKED_BAR", "TABLE" ], "description": "Chart type. Defaults to LINE." }, "size": { "type": "string", "enum": [ "SMALL", "MEDIUM", "LARGE", "EXTRA_LARGE" ], "description": "Grid width. Defaults to MEDIUM." }, "id": { "type": "string", "format": "uuid" } }, "required": [ "measures", "name", "id" ] } } }, "required": [ "id", "name", "description", "isDefault", "configManaged", "timeRange", "createdAt", "updatedAt", "filters", "widgets" ] }, "DashboardInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "timeRange": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "LAST" }, "value": { "type": "integer", "minimum": 1, "maximum": 1000 }, "unit": { "type": "string", "enum": [ "DAYS", "WEEKS", "MONTHS" ] } }, "required": [ "type", "value", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "CALENDAR_ALIGNED" }, "period": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "THIS_WEEK", "LAST_WEEK", "THIS_MONTH", "LAST_MONTH", "THIS_YEAR", "LAST_YEAR" ] } }, "required": [ "type", "period" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "FIXED" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "type", "from", "to" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "SINCE" }, "from": { "type": "string", "format": "date-time" } }, "required": [ "type", "from" ] } ], "description": "The window: LAST n DAYS/WEEKS/MONTHS up to now, a CALENDAR_ALIGNED period (TODAY, YESTERDAY, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, THIS_YEAR, LAST_YEAR), FIXED from/to, or SINCE a date. At most 731 days (two years)." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "maxItems": 20 }, "isDefault": { "type": "boolean" }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "measures": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC", "CONVERSATION", "UPTIME" ], "description": "METRIC (default): a metric's values. CONVERSATION: conversation counts. UPTIME: health-check outcomes." }, "metric": { "type": "string", "minLength": 1, "description": "The metric's slug (e.g. `task_completion`) or id. Required for METRIC." }, "aggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ], "description": "Defaults by output type: AVG for numeric metrics, COUNT (split by value) for classification and text, PASS_RATE for thresholds and uptime, COUNT for conversations." }, "percentile": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Required with PERCENTILE, e.g. 95." }, "distinctBy": { "type": "string", "enum": [ "NONE", "CALL" ], "description": "CALL (default for metrics) folds each conversation to one value first, so a long call does not outweigh a short one. NONE aggregates every value." }, "nestedAggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ], "description": "How each conversation is folded when distinctBy is CALL. Defaults to SUM under SUM, else AVG." }, "nestedAggregationPercentile": { "type": "integer", "minimum": 0, "maximum": 100 }, "passOperator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "PASS_RATE condition operator. Omit for a threshold metric: its own condition is used." }, "passValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "PASS_RATE condition value, e.g. 4 or \"resolved\"." }, "breakdown": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "DATASET" ] }, "property": { "type": "string", "description": "The property to split by. Required for CALL_PROPERTY and METRIC_PROPERTY." } }, "required": [ "type" ], "description": "Split the measure into one series per value of this dimension (the largest 50 are returned). Ignored while comparisonGroups are set: each group is then one series." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "maxItems": 20, "description": "Filters for this measure only, on top of the query's filters." }, "isBaseline": { "type": "boolean", "description": "Mark one measure as the baseline: every series also reports its value as a percentage of it." }, "color": { "type": "string", "enum": [ "GREEN", "RED", "ORANGE", "PURPLE", "GREY", "BLUE", "PEACH", "TEAL", "INDIGO", "AMBER", "ROSE", "CYAN" ], "description": "Chart color on a dashboard." } } }, "minItems": 1, "maxItems": 10, "description": "What to aggregate: 1 to 10 measures." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "maxItems": 20, "description": "Applied to every measure, on top of each measure's own filters." }, "interval": { "type": "string", "enum": [ "HOUR", "DAY", "WEEK", "MONTH" ], "description": "Bucket size. Defaults from the window's length and steps coarser when the window would exceed 500 buckets." }, "comparisonMode": { "type": "string", "enum": [ "NONE", "PREVIOUS_PERIOD" ], "description": "PREVIOUS_PERIOD adds the preceding window of the same length to every series." }, "comparisonGroups": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The series label; unique within the query." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "minItems": 1, "maxItems": 20 }, "color": { "type": "string", "enum": [ "GREEN", "RED", "ORANGE", "PURPLE", "GREY", "BLUE", "PEACH", "TEAL", "INDIGO", "AMBER", "ROSE", "CYAN" ] } }, "required": [ "name", "filters" ] }, "minItems": 2, "maxItems": 5, "description": "Run every measure once per named filter set, e.g. one group per agent." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Unique on the dashboard: how the widget is matched on update." }, "description": { "type": "string", "maxLength": 2000 }, "display": { "type": "string", "enum": [ "LINE", "NUMBER", "RADAR", "STACKED_BAR", "TABLE" ], "description": "Chart type. Defaults to LINE." }, "size": { "type": "string", "enum": [ "SMALL", "MEDIUM", "LARGE", "EXTRA_LARGE" ], "description": "Grid width. Defaults to MEDIUM." } }, "required": [ "measures", "name" ] }, "maxItems": 50 } }, "required": [ "name" ], "description": "A dashboard: a name, the window and filters every widget reads, and its widgets top to bottom. Each widget is an analytics query (the shape POST /v1/analytics/query takes) plus a name, chart type and size.", "example": { "name": "Support agent health", "timeRange": { "type": "LAST", "value": 30, "unit": "DAYS" }, "filters": [ { "type": "MODALITY", "value": "call" } ], "widgets": [ { "name": "Sentiment", "display": "LINE", "size": "LARGE", "interval": "DAY", "measures": [ { "metric": "sentiment_score", "aggregation": "AVG" } ] }, { "name": "Calls", "display": "NUMBER", "measures": [ { "type": "CONVERSATION" } ] } ] } }, "UpdateDashboardInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "timeRange": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "LAST" }, "value": { "type": "integer", "minimum": 1, "maximum": 1000 }, "unit": { "type": "string", "enum": [ "DAYS", "WEEKS", "MONTHS" ] } }, "required": [ "type", "value", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "CALENDAR_ALIGNED" }, "period": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "THIS_WEEK", "LAST_WEEK", "THIS_MONTH", "LAST_MONTH", "THIS_YEAR", "LAST_YEAR" ] } }, "required": [ "type", "period" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "FIXED" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "type", "from", "to" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "SINCE" }, "from": { "type": "string", "format": "date-time" } }, "required": [ "type", "from" ] } ], "description": "The window: LAST n DAYS/WEEKS/MONTHS up to now, a CALENDAR_ALIGNED period (TODAY, YESTERDAY, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, THIS_YEAR, LAST_YEAR), FIXED from/to, or SINCE a date. At most 731 days (two years)." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "maxItems": 20 }, "isDefault": { "type": "boolean" }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "measures": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC", "CONVERSATION", "UPTIME" ], "description": "METRIC (default): a metric's values. CONVERSATION: conversation counts. UPTIME: health-check outcomes." }, "metric": { "type": "string", "minLength": 1, "description": "The metric's slug (e.g. `task_completion`) or id. Required for METRIC." }, "aggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ], "description": "Defaults by output type: AVG for numeric metrics, COUNT (split by value) for classification and text, PASS_RATE for thresholds and uptime, COUNT for conversations." }, "percentile": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Required with PERCENTILE, e.g. 95." }, "distinctBy": { "type": "string", "enum": [ "NONE", "CALL" ], "description": "CALL (default for metrics) folds each conversation to one value first, so a long call does not outweigh a short one. NONE aggregates every value." }, "nestedAggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ], "description": "How each conversation is folded when distinctBy is CALL. Defaults to SUM under SUM, else AVG." }, "nestedAggregationPercentile": { "type": "integer", "minimum": 0, "maximum": 100 }, "passOperator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "PASS_RATE condition operator. Omit for a threshold metric: its own condition is used." }, "passValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "PASS_RATE condition value, e.g. 4 or \"resolved\"." }, "breakdown": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "DATASET" ] }, "property": { "type": "string", "description": "The property to split by. Required for CALL_PROPERTY and METRIC_PROPERTY." } }, "required": [ "type" ], "description": "Split the measure into one series per value of this dimension (the largest 50 are returned). Ignored while comparisonGroups are set: each group is then one series." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "maxItems": 20, "description": "Filters for this measure only, on top of the query's filters." }, "isBaseline": { "type": "boolean", "description": "Mark one measure as the baseline: every series also reports its value as a percentage of it." }, "color": { "type": "string", "enum": [ "GREEN", "RED", "ORANGE", "PURPLE", "GREY", "BLUE", "PEACH", "TEAL", "INDIGO", "AMBER", "ROSE", "CYAN" ], "description": "Chart color on a dashboard." } } }, "minItems": 1, "maxItems": 10, "description": "What to aggregate: 1 to 10 measures." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "maxItems": 20, "description": "Applied to every measure, on top of each measure's own filters." }, "interval": { "type": "string", "enum": [ "HOUR", "DAY", "WEEK", "MONTH" ], "description": "Bucket size. Defaults from the window's length and steps coarser when the window would exceed 500 buckets." }, "comparisonMode": { "type": "string", "enum": [ "NONE", "PREVIOUS_PERIOD" ], "description": "PREVIOUS_PERIOD adds the preceding window of the same length to every series." }, "comparisonGroups": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The series label; unique within the query." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "minItems": 1, "maxItems": 20 }, "color": { "type": "string", "enum": [ "GREEN", "RED", "ORANGE", "PURPLE", "GREY", "BLUE", "PEACH", "TEAL", "INDIGO", "AMBER", "ROSE", "CYAN" ] } }, "required": [ "name", "filters" ] }, "minItems": 2, "maxItems": 5, "description": "Run every measure once per named filter set, e.g. one group per agent." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Unique on the dashboard: how the widget is matched on update." }, "description": { "type": "string", "maxLength": 2000 }, "display": { "type": "string", "enum": [ "LINE", "NUMBER", "RADAR", "STACKED_BAR", "TABLE" ], "description": "Chart type. Defaults to LINE." }, "size": { "type": "string", "enum": [ "SMALL", "MEDIUM", "LARGE", "EXTRA_LARGE" ], "description": "Grid width. Defaults to MEDIUM." } }, "required": [ "measures", "name" ] }, "maxItems": 50 } }, "description": "Omitted fields keep their current value. `widgets`, when sent, replaces the list: widgets are matched by name, so one that keeps its name keeps its id; a new name adds a widget and a missing one removes it.", "example": { "timeRange": { "type": "CALENDAR_ALIGNED", "period": "THIS_MONTH" } } }, "DashboardData": { "type": "object", "properties": { "dashboardId": { "type": "string", "format": "uuid" }, "from": { "type": "string" }, "to": { "type": "string" }, "timezone": { "type": "string" }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "widgetId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "interval": { "type": "string", "enum": [ "HOUR", "DAY", "WEEK", "MONTH" ] }, "blocked": { "type": "boolean" }, "error": { "type": [ "string", "null" ] }, "series": { "type": "array", "items": { "type": "object", "properties": { "measureIndex": { "type": "integer" }, "type": { "type": "string", "enum": [ "METRIC", "CONVERSATION", "UPTIME" ] }, "metric": { "type": [ "string", "null" ] }, "aggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ] }, "breakdownValue": { "type": [ "string", "null" ] }, "comparisonGroup": { "type": [ "string", "null" ] }, "value": { "type": "number" }, "sampleSize": { "type": [ "number", "null" ] }, "comparisonValue": { "type": [ "number", "null" ] }, "percentageOfBaseline": { "type": [ "number", "null" ] }, "buckets": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "value": { "type": "number" }, "passed": { "type": "number" }, "sampleSize": { "type": "number" }, "comparisonDate": { "type": "string" }, "comparisonValue": { "type": "number" }, "percentageOfBaseline": { "type": "number" } }, "required": [ "date", "value" ] } } }, "required": [ "measureIndex", "type", "metric", "aggregation", "breakdownValue", "comparisonGroup", "value", "sampleSize", "comparisonValue", "percentageOfBaseline", "buckets" ] } }, "omittedSeries": { "type": "integer" } }, "required": [ "widgetId", "name", "interval", "blocked", "error", "series", "omittedSeries" ] } } }, "required": [ "dashboardId", "from", "to", "timezone", "widgets" ], "description": "Every widget's series over the window, top to bottom. A widget that fails on its own (say its metric was deleted) carries `error` and no series; the others still return." }, "DashboardWidget": { "type": "object", "properties": { "measures": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC", "CONVERSATION", "UPTIME" ], "description": "METRIC (default): a metric's values. CONVERSATION: conversation counts. UPTIME: health-check outcomes." }, "metric": { "type": "string", "minLength": 1, "description": "The metric's slug (e.g. `task_completion`) or id. Required for METRIC." }, "aggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ], "description": "Defaults by output type: AVG for numeric metrics, COUNT (split by value) for classification and text, PASS_RATE for thresholds and uptime, COUNT for conversations." }, "percentile": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Required with PERCENTILE, e.g. 95." }, "distinctBy": { "type": "string", "enum": [ "NONE", "CALL" ], "description": "CALL (default for metrics) folds each conversation to one value first, so a long call does not outweigh a short one. NONE aggregates every value." }, "nestedAggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ], "description": "How each conversation is folded when distinctBy is CALL. Defaults to SUM under SUM, else AVG." }, "nestedAggregationPercentile": { "type": "integer", "minimum": 0, "maximum": 100 }, "passOperator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "PASS_RATE condition operator. Omit for a threshold metric: its own condition is used." }, "passValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "PASS_RATE condition value, e.g. 4 or \"resolved\"." }, "breakdown": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "DATASET" ] }, "property": { "type": "string", "description": "The property to split by. Required for CALL_PROPERTY and METRIC_PROPERTY." } }, "required": [ "type" ], "description": "Split the measure into one series per value of this dimension (the largest 50 are returned). Ignored while comparisonGroups are set: each group is then one series." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "maxItems": 20, "description": "Filters for this measure only, on top of the query's filters." }, "isBaseline": { "type": "boolean", "description": "Mark one measure as the baseline: every series also reports its value as a percentage of it." }, "color": { "type": "string", "enum": [ "GREEN", "RED", "ORANGE", "PURPLE", "GREY", "BLUE", "PEACH", "TEAL", "INDIGO", "AMBER", "ROSE", "CYAN" ], "description": "Chart color on a dashboard." } } }, "minItems": 1, "maxItems": 10, "description": "What to aggregate: 1 to 10 measures." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "maxItems": 20, "description": "Applied to every measure, on top of each measure's own filters." }, "interval": { "type": "string", "enum": [ "HOUR", "DAY", "WEEK", "MONTH" ], "description": "Bucket size. Defaults from the window's length and steps coarser when the window would exceed 500 buckets." }, "comparisonMode": { "type": "string", "enum": [ "NONE", "PREVIOUS_PERIOD" ], "description": "PREVIOUS_PERIOD adds the preceding window of the same length to every series." }, "comparisonGroups": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The series label; unique within the query." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "minItems": 1, "maxItems": 20 }, "color": { "type": "string", "enum": [ "GREEN", "RED", "ORANGE", "PURPLE", "GREY", "BLUE", "PEACH", "TEAL", "INDIGO", "AMBER", "ROSE", "CYAN" ] } }, "required": [ "name", "filters" ] }, "minItems": 2, "maxItems": 5, "description": "Run every measure once per named filter set, e.g. one group per agent." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Unique on the dashboard: how the widget is matched on update." }, "description": { "type": "string", "maxLength": 2000 }, "display": { "type": "string", "enum": [ "LINE", "NUMBER", "RADAR", "STACKED_BAR", "TABLE" ], "description": "Chart type. Defaults to LINE." }, "size": { "type": "string", "enum": [ "SMALL", "MEDIUM", "LARGE", "EXTRA_LARGE" ], "description": "Grid width. Defaults to MEDIUM." }, "id": { "type": "string", "format": "uuid" } }, "required": [ "measures", "name", "id" ] }, "DashboardWidgetInput": { "type": "object", "properties": { "measures": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC", "CONVERSATION", "UPTIME" ], "description": "METRIC (default): a metric's values. CONVERSATION: conversation counts. UPTIME: health-check outcomes." }, "metric": { "type": "string", "minLength": 1, "description": "The metric's slug (e.g. `task_completion`) or id. Required for METRIC." }, "aggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ], "description": "Defaults by output type: AVG for numeric metrics, COUNT (split by value) for classification and text, PASS_RATE for thresholds and uptime, COUNT for conversations." }, "percentile": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Required with PERCENTILE, e.g. 95." }, "distinctBy": { "type": "string", "enum": [ "NONE", "CALL" ], "description": "CALL (default for metrics) folds each conversation to one value first, so a long call does not outweigh a short one. NONE aggregates every value." }, "nestedAggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ], "description": "How each conversation is folded when distinctBy is CALL. Defaults to SUM under SUM, else AVG." }, "nestedAggregationPercentile": { "type": "integer", "minimum": 0, "maximum": 100 }, "passOperator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "PASS_RATE condition operator. Omit for a threshold metric: its own condition is used." }, "passValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "PASS_RATE condition value, e.g. 4 or \"resolved\"." }, "breakdown": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "DATASET" ] }, "property": { "type": "string", "description": "The property to split by. Required for CALL_PROPERTY and METRIC_PROPERTY." } }, "required": [ "type" ], "description": "Split the measure into one series per value of this dimension (the largest 50 are returned). Ignored while comparisonGroups are set: each group is then one series." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "maxItems": 20, "description": "Filters for this measure only, on top of the query's filters." }, "isBaseline": { "type": "boolean", "description": "Mark one measure as the baseline: every series also reports its value as a percentage of it." }, "color": { "type": "string", "enum": [ "GREEN", "RED", "ORANGE", "PURPLE", "GREY", "BLUE", "PEACH", "TEAL", "INDIGO", "AMBER", "ROSE", "CYAN" ], "description": "Chart color on a dashboard." } } }, "minItems": 1, "maxItems": 10, "description": "What to aggregate: 1 to 10 measures." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "maxItems": 20, "description": "Applied to every measure, on top of each measure's own filters." }, "interval": { "type": "string", "enum": [ "HOUR", "DAY", "WEEK", "MONTH" ], "description": "Bucket size. Defaults from the window's length and steps coarser when the window would exceed 500 buckets." }, "comparisonMode": { "type": "string", "enum": [ "NONE", "PREVIOUS_PERIOD" ], "description": "PREVIOUS_PERIOD adds the preceding window of the same length to every series." }, "comparisonGroups": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The series label; unique within the query." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ], "description": "What the filter narrows on. GET /v1/analytics/schema lists each type." }, "property": { "type": "string", "description": "The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID." }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ], "description": "Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against (an agent id, \"call\" / \"chat\", a property value). Required except with IS_SET / IS_NOT_SET." } }, "required": [ "type" ] }, "minItems": 1, "maxItems": 20 }, "color": { "type": "string", "enum": [ "GREEN", "RED", "ORANGE", "PURPLE", "GREY", "BLUE", "PEACH", "TEAL", "INDIGO", "AMBER", "ROSE", "CYAN" ] } }, "required": [ "name", "filters" ] }, "minItems": 2, "maxItems": 5, "description": "Run every measure once per named filter set, e.g. one group per agent." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Unique on the dashboard: how the widget is matched on update." }, "description": { "type": "string", "maxLength": 2000 }, "display": { "type": "string", "enum": [ "LINE", "NUMBER", "RADAR", "STACKED_BAR", "TABLE" ], "description": "Chart type. Defaults to LINE." }, "size": { "type": "string", "enum": [ "SMALL", "MEDIUM", "LARGE", "EXTRA_LARGE" ], "description": "Grid width. Defaults to MEDIUM." } }, "required": [ "measures", "name" ], "description": "One widget: an analytics query plus its name (unique on the dashboard), chart type and size.", "example": { "name": "Sentiment", "display": "LINE", "size": "LARGE", "interval": "DAY", "measures": [ { "metric": "sentiment_score", "aggregation": "AVG" } ] } }, "DashboardWidgetData": { "type": "object", "properties": { "widgetId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "interval": { "type": "string", "enum": [ "HOUR", "DAY", "WEEK", "MONTH" ] }, "blocked": { "type": "boolean" }, "error": { "type": [ "string", "null" ] }, "series": { "type": "array", "items": { "type": "object", "properties": { "measureIndex": { "type": "integer" }, "type": { "type": "string", "enum": [ "METRIC", "CONVERSATION", "UPTIME" ] }, "metric": { "type": [ "string", "null" ] }, "aggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ] }, "breakdownValue": { "type": [ "string", "null" ] }, "comparisonGroup": { "type": [ "string", "null" ] }, "value": { "type": "number" }, "sampleSize": { "type": [ "number", "null" ] }, "comparisonValue": { "type": [ "number", "null" ] }, "percentageOfBaseline": { "type": [ "number", "null" ] }, "buckets": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "value": { "type": "number" }, "passed": { "type": "number" }, "sampleSize": { "type": "number" }, "comparisonDate": { "type": "string" }, "comparisonValue": { "type": "number" }, "percentageOfBaseline": { "type": "number" } }, "required": [ "date", "value" ] } } }, "required": [ "measureIndex", "type", "metric", "aggregation", "breakdownValue", "comparisonGroup", "value", "sampleSize", "comparisonValue", "percentageOfBaseline", "buckets" ] } }, "omittedSeries": { "type": "integer" }, "from": { "type": "string" }, "to": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "widgetId", "name", "interval", "blocked", "error", "series", "omittedSeries", "from", "to", "timezone" ] }, "ConfigDiffResponse": { "type": "object", "properties": { "changes": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigDiffChange" } }, "summary": { "$ref": "#/components/schemas/ConfigDiffSummary" } }, "required": [ "changes", "summary" ] }, "ConfigDiffChange": { "type": "object", "properties": { "configKey": { "type": "string" }, "kind": { "type": "string", "enum": [ "agent", "persona", "httpRequestDefinition", "flow", "collector", "metric", "simulationPlan", "simulationGroup", "alert", "tool", "dashboard", "project", "member" ] }, "name": { "type": "string" }, "op": { "type": "string", "enum": [ "create", "update", "delete", "noop" ] }, "project": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "configKey", "kind", "name", "op" ] }, "ConfigDiffSummary": { "type": "object", "properties": { "create": { "type": "integer" }, "update": { "type": "integer" }, "delete": { "type": "integer" }, "noop": { "type": "integer" } }, "required": [ "create", "update", "delete", "noop" ] }, "ConfigBundle": { "type": "object", "properties": { "resources": { "type": "array", "items": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/AgentConfig" }, { "$ref": "#/components/schemas/HttpRequestDefinitionConfig" }, { "$ref": "#/components/schemas/PersonaConfig" }, { "$ref": "#/components/schemas/ImprovFlowConfig" }, { "$ref": "#/components/schemas/ScriptedFlowConfig" }, { "$ref": "#/components/schemas/CollectorConfig" }, { "$ref": "#/components/schemas/MetricConfig" }, { "$ref": "#/components/schemas/ApiCheckMetricConfig" }, { "$ref": "#/components/schemas/ThresholdMetricConfig" }, { "$ref": "#/components/schemas/SimulationPlanConfig" }, { "$ref": "#/components/schemas/QaSimulationPlanConfig" }, { "$ref": "#/components/schemas/SimulationGroupConfig" }, { "$ref": "#/components/schemas/AlertConfig" }, { "$ref": "#/components/schemas/ToolConfig" }, { "$ref": "#/components/schemas/DashboardConfig" } ] }, { "$ref": "#/components/schemas/ProjectConfig" } ] } }, "prune": { "type": "boolean", "default": true } }, "required": [ "resources" ] }, "AgentConfig": { "type": "object", "properties": { "kind": { "type": "string", "const": "agent" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "displayName": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "customId": { "type": [ "string", "null" ] }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "PHONE", "WEBSOCKET" ], "default": "PHONE" }, "direction": { "type": "string", "enum": [ "INCOMING", "OUTGOING", "INCOMING_AND_OUTGOING" ], "default": "INCOMING" }, "environment": { "type": "string" }, "outboundDialType": { "type": "string", "enum": [ "NONE", "HTTP_REQUEST" ], "default": "NONE" }, "outboundDialHttpRequestDefinition": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 } }, "required": [ "value" ] } }, "prompt": { "type": [ "string", "null" ] } }, "required": [ "kind", "name" ] }, "HttpRequestDefinitionConfig": { "type": "object", "properties": { "kind": { "type": "string", "const": "httpRequestDefinition" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "method": { "type": "string", "enum": [ "POST", "PUT", "PATCH", "GET" ], "default": "POST" }, "body": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "kind", "name", "url" ] }, "PersonaConfig": { "type": "object", "properties": { "kind": { "type": "string", "const": "persona" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "displayName": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "language": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ] }, "secondaryLanguage": { "type": [ "string", "null" ], "const": "EN" }, "understoodLanguages": { "type": "array", "items": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ] }, "minItems": 1 }, "accent": { "type": "string", "enum": [ "US", "US_X_SOUTH", "GB", "ES", "DE", "IN", "FR", "NL", "SA", "GR", "AU", "IT", "ID", "TH", "JP", "NZ", "PH", "SG", "MY", "HK", "TR", "PT", "IL" ] }, "age": { "type": "string", "enum": [ "CHILD", "TEENAGER", "ADULT", "ELDERLY" ], "default": "ADULT" }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ] }, "backgroundNoise": { "type": "string", "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "default": "NONE" }, "speechPace": { "type": "string", "enum": [ "SUPER_SLOW", "SLOW", "NORMAL", "FAST", "SUPER_FAST" ], "default": "NORMAL" }, "speechClarity": { "type": "string", "enum": [ "CLEAR", "VAGUE", "RAMBLING" ], "default": "CLEAR" }, "hasDisfluencies": { "type": "boolean", "default": false }, "baseEmotion": { "type": "string", "enum": [ "NEUTRAL", "CHEERFUL", "CONFUSED", "FRUSTRATED", "SKEPTICAL", "RUSHED", "DISTRACTED", "ANGRY", "ANXIOUS", "SAD" ], "default": "NEUTRAL" }, "intentClarity": { "type": "string", "enum": [ "CLEAR", "INDIRECT", "VAGUE" ], "default": "CLEAR" }, "confirmationStyle": { "type": "string", "enum": [ "EXPLICIT", "VAGUE" ], "default": "EXPLICIT" }, "memoryReliability": { "type": "string", "enum": [ "HIGH", "LOW" ], "default": "HIGH" }, "responseTiming": { "type": "string", "enum": [ "RELAXED", "NORMAL", "QUICK", "BARGE_IN" ], "default": "NORMAL" }, "interruption": { "type": "string", "enum": [ "OFF", "BACKCHANNEL", "OCCASIONAL", "HEAVY" ] }, "backstoryPrompt": { "type": [ "string", "null" ] }, "idleMessages": { "type": [ "array", "null" ], "items": { "type": "string" } }, "idleTimeoutSeconds": { "type": "integer", "minimum": 5, "maximum": 60, "default": 10 }, "idleMessageMaxSpokenCount": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3 }, "idleMessageResetCountOnUserSpeechEnabled": { "type": "boolean", "default": true }, "properties": { "type": "object", "additionalProperties": {} } }, "required": [ "kind", "name", "language", "accent", "gender" ] }, "ImprovFlowConfig": { "type": "object", "properties": { "kind": { "type": "string", "const": "flow" }, "type": { "type": "string", "const": "improv" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "agents": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "minItems": 1 }, "expectations": { "type": "array", "items": { "type": "string" } }, "happyPath": { "type": "object", "properties": { "persona": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "environment": { "type": "string" }, "prompt": { "type": "string" }, "expectations": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string" } }, "required": [ "persona", "environment" ] }, "edgeCases": { "type": "array", "items": { "type": "object", "properties": { "persona": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "environment": { "type": "string" }, "prompt": { "type": "string" }, "expectations": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "title": { "type": "string" }, "includeFlowExpectations": { "type": "boolean" } }, "required": [ "name" ] } } }, "required": [ "kind", "type", "name", "agents", "happyPath" ] }, "ScriptedFlowConfig": { "type": "object", "properties": { "kind": { "type": "string", "const": "flow" }, "type": { "type": "string", "const": "scripted" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "agents": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 } }, "branchingMode": { "type": "string", "enum": [ "DETERMINISTIC", "ADAPTIVE" ] }, "adherence": { "type": "string", "enum": [ "LOOSE", "STRICT" ] }, "offScript": { "$ref": "#/components/schemas/ConfigOffScript" }, "expectations": { "type": "array", "items": { "type": "string" } }, "graph": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigFlowStep" }, "minItems": 1 } }, "required": [ "kind", "type", "name", "graph" ] }, "ConfigOffScript": { "type": "object", "properties": { "reaction": { "type": "string", "enum": [ "STAY_SILENT", "REPEAT", "RESPOND", "SAY" ] }, "sayLine": { "type": "string", "minLength": 1, "maxLength": 2000 }, "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 20 }, "then": { "type": "string", "enum": [ "HANG_UP", "MOVE_ON", "ADAPT", "HANG_UP_INVALIDATE" ] }, "waitSeconds": { "type": "integer", "minimum": 1, "maximum": 600 } } }, "ConfigFlowStep": { "type": "object", "properties": { "ref": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "AGENT_TURN", "CUSTOMER_TURN", "CUSTOMER_FIRST_MESSAGE", "CUSTOMER_VERBATIM_TURN", "CUSTOMER_SILENCE", "CUSTOMER_DTMF", "AGENT_DTMF", "VOICEMAIL", "SCENARIO_LINK", "CUSTOMER_HANDOFF" ] }, "content": { "type": "string" }, "offScript": { "$ref": "#/components/schemas/ConfigOffScript" }, "silenceDurationSeconds": { "type": "integer", "exclusiveMinimum": 0 }, "dtmfDigits": { "type": "string" }, "flow": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "handoffPersona": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "stage": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": { "type": "boolean" }, "analyze": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } ] }, "requiredForValidRun": { "type": "boolean", "description": "Removed. Use `stage` with `required: true`." }, "mergeInto": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigFlowStep" } } }, "required": [ "type" ] }, "CollectorConfig": { "type": "object", "properties": { "kind": { "type": "string", "const": "collector" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "displayName": { "type": "string" }, "modality": { "type": "string", "enum": [ "call", "chat" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "default": "ACTIVE" }, "metrics": { "type": "array", "items": { "anyOf": [ { "type": "string", "minLength": 1 }, { "$ref": "#/components/schemas/CollectorMetricConfig" } ] }, "minItems": 1 }, "filters": { "type": "array", "items": { "type": "object", "properties": { "conditions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "AGENT", "CALL_SOURCE", "CALL_PROPERTY", "INTEGRATION" ] }, "key": { "type": "string", "minLength": 1 }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "CONTAINS", "STARTS_WITH", "GREATER_THAN", "LESS_THAN", "GREATER_THAN_OR_EQUALS", "LESS_THAN_OR_EQUALS" ] }, "value": { "type": "string" } }, "required": [ "type", "key" ] }, "minItems": 1 } }, "required": [ "conditions" ] } } }, "required": [ "kind", "name", "modality", "metrics" ] }, "CollectorMetricConfig": { "type": "object", "properties": { "metric": { "type": "string", "minLength": 1 }, "verifiedProperties": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 50 }, "excludedPhrases": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 50 }, "voicemailScript": { "type": "string", "minLength": 1, "maxLength": 4000 }, "screeningBrief": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "metric" ], "additionalProperties": false }, "MetricConfig": { "type": "object", "properties": { "kind": { "type": "string", "const": "metric" }, "calculationType": { "type": "string", "const": "LLM_JUDGE" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "enum": [ "BOOLEAN", "SCALE", "NUMERIC", "TEXT", "CLASSIFICATION" ] }, "prompt": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "GLOBAL", "PER_PARTICIPANT" ], "default": "GLOBAL" }, "participantRole": { "type": "string", "enum": [ "AGENT", "CUSTOMER" ] }, "contexts": { "type": "array", "items": { "type": "string", "enum": [ "CALL", "SEGMENT", "TURN" ] }, "minItems": 1, "default": [ "CALL" ] }, "trueLabel": { "type": "string" }, "falseLabel": { "type": "string" }, "scaleMin": { "type": "integer" }, "scaleMax": { "type": "integer" }, "scaleLabels": { "type": "array", "items": { "type": "object", "properties": { "rangeMin": { "type": "number" }, "rangeMax": { "type": "number" }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "displayOrder": { "type": "integer" }, "colorHex": { "type": "string" } }, "required": [ "rangeMin", "rangeMax", "label", "displayOrder" ] } }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "displayOrder": { "type": "integer" } }, "required": [ "label", "displayOrder" ] }, "minItems": 1 }, "maxSelections": { "type": "integer", "minimum": 1 } }, "required": [ "kind", "name", "type", "prompt" ] }, "ApiCheckMetricConfig": { "type": "object", "properties": { "kind": { "type": "string", "const": "metric" }, "calculationType": { "type": "string", "const": "HTTP_REQUEST" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 100 }, "httpRequest": { "$ref": "#/components/schemas/ApiCheckRequestConfig" }, "trueLabel": { "type": "string" }, "falseLabel": { "type": "string" } }, "required": [ "kind", "calculationType", "name", "httpRequest" ] }, "ApiCheckRequestConfig": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "method": { "type": "string", "enum": [ "GET", "POST" ], "default": "POST" }, "headers": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 200 }, "additionalProperties": { "type": "string", "maxLength": 4000 } }, "body": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "url" ] }, "ThresholdMetricConfig": { "type": "object", "properties": { "kind": { "type": "string", "const": "metric" }, "calculationType": { "type": "string", "const": "THRESHOLD" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "sourceMetric": { "type": "string", "minLength": 1 }, "sourceVariant": { "type": "string", "minLength": 1 }, "operator": { "type": "string", "enum": [ "GREATER_THAN", "GREATER_THAN_OR_EQUALS", "LESS_THAN", "LESS_THAN_OR_EQUALS", "EQUALS", "NOT_EQUALS" ] }, "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" }, { "type": "boolean" } ] }, "aggregationMode": { "type": "string", "enum": [ "EACH", "COUNT", "AVERAGE", "MIN", "MAX", "MEDIAN", "P95", "P99", "SUM" ], "default": "EACH" }, "countThreshold": { "type": "integer", "minimum": 0 }, "sourceParticipantRole": { "type": "string", "enum": [ "AGENT", "CUSTOMER" ] }, "trueLabel": { "type": "string" }, "falseLabel": { "type": "string" } }, "required": [ "kind", "calculationType", "name", "sourceMetric", "operator", "value" ] }, "SimulationPlanConfig": { "type": "object", "properties": { "kind": { "type": "string", "const": "simulationPlan" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "agentEndpoints": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationPlanAgentEndpointConfig" }, "minItems": 1 }, "maxDurationSeconds": { "type": "integer", "minimum": 1 }, "iterations": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 }, "maxConcurrentJobs": { "type": "integer", "minimum": 1, "default": 1 }, "executionMode": { "type": "string", "enum": [ "PARALLEL", "SEQUENTIAL_SAME_RUN_PLAN", "SEQUENTIAL_PROJECT" ], "default": "PARALLEL" }, "silenceTimeoutSeconds": { "type": "integer", "minimum": 1, "default": 30 }, "maxNoResponseRetries": { "type": "integer", "minimum": 0, "maximum": 10, "default": 0 }, "noResponseRetryBackoffSeconds": { "type": "integer", "minimum": 30, "maximum": 600, "default": 90 }, "endCallPhrases": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 10, "default": [ "goodbye" ] }, "endCallReasons": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 10, "default": [] }, "includeFlowMetrics": { "type": "boolean", "default": true }, "includeAutomaticMetrics": { "type": "boolean", "default": true }, "enrichWithLiveConversation": { "type": "boolean", "default": false }, "schedule": { "$ref": "#/components/schemas/SimulationPlanScheduleConfig" }, "notify": { "$ref": "#/components/schemas/SimulationNotifyConfig" }, "template": { "type": "string", "const": "manual", "default": "manual" }, "metrics": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }, "flows": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationPlanFlowConfig" }, "minItems": 1 } }, "required": [ "kind", "name", "direction", "agentEndpoints", "maxDurationSeconds", "metrics", "flows" ] }, "SimulationPlanAgentEndpointConfig": { "type": "object", "properties": { "agent": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "direction": { "type": "string", "enum": [ "INCOMING", "OUTGOING", "INCOMING_AND_OUTGOING" ] } }, "required": [ "agent" ] }, "SimulationPlanScheduleConfig": { "oneOf": [ { "type": "object", "properties": { "timezone": { "type": "string", "default": "UTC" }, "enabled": { "type": "boolean", "default": true }, "endDate": { "type": "string", "format": "date-time" }, "maxRuns": { "type": "integer", "minimum": 1 }, "type": { "type": "string", "const": "hourly" }, "minute": { "type": "integer", "minimum": 0, "maximum": 59, "default": 0 } }, "required": [ "type" ] }, { "type": "object", "properties": { "timezone": { "type": "string", "default": "UTC" }, "enabled": { "type": "boolean", "default": true }, "endDate": { "type": "string", "format": "date-time" }, "maxRuns": { "type": "integer", "minimum": 1 }, "type": { "type": "string", "const": "interval" }, "everyMinutes": { "type": "integer", "minimum": 15, "maximum": 59 } }, "required": [ "type", "everyMinutes" ] }, { "type": "object", "properties": { "timezone": { "type": "string", "default": "UTC" }, "enabled": { "type": "boolean", "default": true }, "endDate": { "type": "string", "format": "date-time" }, "maxRuns": { "type": "integer", "minimum": 1 }, "type": { "type": "string", "const": "daily" }, "time": { "type": "string", "pattern": "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$" } }, "required": [ "type", "time" ] }, { "type": "object", "properties": { "timezone": { "type": "string", "default": "UTC" }, "enabled": { "type": "boolean", "default": true }, "endDate": { "type": "string", "format": "date-time" }, "maxRuns": { "type": "integer", "minimum": 1 }, "type": { "type": "string", "const": "weekly" }, "days": { "type": "array", "items": { "type": "string", "enum": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ] }, "minItems": 1, "maxItems": 7 }, "time": { "type": "string", "pattern": "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$" } }, "required": [ "type", "days", "time" ] }, { "type": "object", "properties": { "timezone": { "type": "string", "default": "UTC" }, "enabled": { "type": "boolean", "default": true }, "endDate": { "type": "string", "format": "date-time" }, "maxRuns": { "type": "integer", "minimum": 1 }, "type": { "type": "string", "const": "monthly" }, "dayOfMonth": { "type": "integer", "minimum": 1, "maximum": 31 }, "time": { "type": "string", "pattern": "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$" } }, "required": [ "type", "dayOfMonth", "time" ] }, { "type": "object", "properties": { "timezone": { "type": "string", "default": "UTC" }, "enabled": { "type": "boolean", "default": true }, "type": { "type": "string", "const": "once" }, "at": { "type": "string", "format": "date-time" } }, "required": [ "type", "at" ] } ] }, "SimulationNotifyConfig": { "type": "object", "properties": { "email": { "anyOf": [ { "type": "boolean" }, { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "maxItems": 50 } ], "default": true }, "slack": { "type": "array", "items": { "$ref": "#/components/schemas/AlertSlackChannel" }, "maxItems": 10, "default": [] } } }, "AlertSlackChannel": { "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "channelName": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "channelName" ] }, "SimulationPlanFlowConfig": { "type": "object", "properties": { "flow": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "system": { "type": "string", "minLength": 1 }, "happyPath": { "type": "boolean" }, "edgeCases": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "personaOverride": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 } } }, "QaSimulationPlanConfig": { "type": "object", "properties": { "kind": { "type": "string", "const": "simulationPlan" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "agentEndpoints": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationPlanAgentEndpointConfig" }, "minItems": 1 }, "maxDurationSeconds": { "type": "integer", "minimum": 1 }, "iterations": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 }, "maxConcurrentJobs": { "type": "integer", "minimum": 1, "default": 1 }, "executionMode": { "type": "string", "enum": [ "PARALLEL", "SEQUENTIAL_SAME_RUN_PLAN", "SEQUENTIAL_PROJECT" ], "default": "PARALLEL" }, "silenceTimeoutSeconds": { "type": "integer", "minimum": 1, "default": 30 }, "maxNoResponseRetries": { "type": "integer", "minimum": 0, "maximum": 10, "default": 0 }, "noResponseRetryBackoffSeconds": { "type": "integer", "minimum": 30, "maximum": 600, "default": 90 }, "endCallPhrases": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 10, "default": [ "goodbye" ] }, "endCallReasons": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 10, "default": [] }, "includeFlowMetrics": { "type": "boolean", "default": true }, "includeAutomaticMetrics": { "type": "boolean", "default": true }, "enrichWithLiveConversation": { "type": "boolean", "default": false }, "schedule": { "$ref": "#/components/schemas/SimulationPlanScheduleConfig" }, "notify": { "$ref": "#/components/schemas/SimulationNotifyConfig" }, "template": { "type": "string", "const": "question-answer-check" }, "persona": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "environment": { "type": "string" }, "gradeWithKnowledgeBase": { "type": "boolean", "default": false }, "metrics": { "type": "array", "items": { "type": "string", "minLength": 1 }, "default": [] }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationPlanQaQuestion" }, "minItems": 1 } }, "required": [ "kind", "name", "direction", "agentEndpoints", "maxDurationSeconds", "template", "persona", "environment", "questions" ] }, "SimulationPlanQaQuestion": { "type": "object", "properties": { "ask": { "type": "string", "minLength": 1 }, "expect": { "type": "string", "minLength": 1 }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 } }, "required": [ "ask" ] }, "SimulationGroupConfig": { "type": "object", "properties": { "kind": { "type": "string", "const": "simulationGroup" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ] }, "plans": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 2, "maxItems": 20 }, "schedule": { "$ref": "#/components/schemas/SimulationPlanScheduleConfig" }, "notify": { "allOf": [ { "$ref": "#/components/schemas/SimulationNotifyConfig" } ], "default": {} } }, "required": [ "kind", "name", "plans" ] }, "AlertConfig": { "type": "object", "properties": { "kind": { "type": "string", "const": "alert" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "displayName": { "type": "string" }, "enabled": { "type": "boolean", "default": true }, "trigger": { "oneOf": [ { "$ref": "#/components/schemas/AlertThresholdTrigger" }, { "$ref": "#/components/schemas/AlertEventTrigger" }, { "$ref": "#/components/schemas/AlertSimulationTrigger" } ], "discriminator": { "propertyName": "type", "mapping": { "threshold": "#/components/schemas/AlertThresholdTrigger", "event": "#/components/schemas/AlertEventTrigger", "simulation": "#/components/schemas/AlertSimulationTrigger" } } }, "actions": { "$ref": "#/components/schemas/AlertActions" } }, "required": [ "kind", "name", "trigger" ] }, "AlertThresholdTrigger": { "type": "object", "properties": { "type": { "type": "string", "const": "threshold" }, "metric": { "type": "string", "minLength": 1 }, "metricVariant": { "type": "string", "minLength": 1 }, "aggregation": { "type": "string", "enum": [ "COUNT", "RATE_PER_MINUTE", "MEAN" ] }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0 }, "operator": { "type": "string", "enum": [ "GT", "GTE", "LT", "LTE" ] }, "thresholdValue": { "type": "number" }, "grouping": { "type": "string", "enum": [ "NONE", "BY_AGENT" ], "default": "NONE" }, "minSampleSize": { "type": "integer", "minimum": 1, "default": 1 }, "consecutiveOpen": { "type": "integer", "minimum": 1, "default": 2 }, "consecutiveResolve": { "type": "integer", "minimum": 1, "default": 3 } }, "required": [ "type", "metric", "aggregation", "windowMinutes", "operator", "thresholdValue" ] }, "AlertEventTrigger": { "type": "object", "properties": { "type": { "type": "string", "const": "event" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "CALL_ANALYSIS_COMPLETED", "CALL_ANALYSIS_FAILED", "CALL_ANALYSIS_CANCELLED", "SIMULATION_RUN_PLAN_JOB_STARTED", "SIMULATION_RUN_PLAN_JOB_COMPLETED", "SIMULATION_RUN_PLAN_JOB_FAILED", "SIMULATION_RUN_PLAN_JOB_CANCELLED", "SIMULATION_JOB_STARTED", "SIMULATION_JOB_COMPLETED", "SIMULATION_JOB_FAILED", "SIMULATION_JOB_CANCELLED", "METRIC_COLLECTION_JOB_COMPLETED", "METRIC_COLLECTION_JOB_FAILED", "CHAT_ANALYSIS_COMPLETED", "CHAT_ANALYSIS_FAILED", "ISSUE_OPENED", "ISSUE_RESOLVED" ] }, "minItems": 1 } }, "required": [ "type", "events" ] }, "AlertSimulationTrigger": { "type": "object", "properties": { "type": { "type": "string", "const": "simulation" }, "conditions": { "type": "array", "items": { "type": "string", "enum": [ "SUCCESS", "FAILURE", "THRESHOLD_FAILED" ] }, "minItems": 1 }, "plan": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "deliveryFormat": { "type": "string", "enum": [ "MESSAGE", "PDF" ], "default": "MESSAGE" } }, "required": [ "type", "conditions" ] }, "AlertActions": { "type": "object", "properties": { "slack": { "type": "array", "items": { "$ref": "#/components/schemas/AlertSlackChannel" } }, "webhooks": { "type": "array", "items": { "type": "string", "format": "uri" } } } }, "ToolConfig": { "type": "object", "properties": { "kind": { "type": "string", "const": "tool" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "parameters": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "string", "number", "boolean" ] } }, "invocationCriteria": { "type": [ "string", "null" ] }, "expectedResult": { "type": [ "string", "null" ] }, "agent": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "handler": { "$ref": "#/components/schemas/ToolHandler" } }, "required": [ "kind", "name" ] }, "ToolHandler": { "type": "object", "properties": { "type": { "type": "string", "const": "http" }, "url": { "type": "string", "format": "uri" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] } }, "required": [ "type", "url" ] }, "DashboardConfig": { "type": "object", "properties": { "kind": { "type": "string", "const": "dashboard" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "isDefault": { "type": "boolean" }, "timeRange": { "$ref": "#/components/schemas/DashboardTimeRangeConfig" }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardFilterConfig" }, "maxItems": 20 }, "widgets": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardWidgetConfig" }, "maxItems": 50, "default": [] } }, "required": [ "kind", "name" ] }, "DashboardTimeRangeConfig": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "LAST" }, "value": { "type": "integer", "minimum": 1, "maximum": 1000 }, "unit": { "type": "string", "enum": [ "DAYS", "WEEKS", "MONTHS" ] } }, "required": [ "type", "value", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "CALENDAR_ALIGNED" }, "period": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "THIS_WEEK", "LAST_WEEK", "THIS_MONTH", "LAST_MONTH", "THIS_YEAR", "LAST_YEAR" ] } }, "required": [ "type", "period" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "FIXED" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "type", "from", "to" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "SINCE" }, "from": { "type": "string", "format": "date-time" } }, "required": [ "type", "from" ] } ] }, "DashboardFilterConfig": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "CALL_ID", "MODALITY", "DATASET", "METRIC_VALUE" ] }, "property": { "type": "string" }, "operator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH", "IS_SET", "IS_NOT_SET" ] }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "type" ] }, "DashboardWidgetConfig": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "display": { "type": "string", "enum": [ "LINE", "NUMBER", "RADAR", "STACKED_BAR", "TABLE" ] }, "size": { "type": "string", "enum": [ "SMALL", "MEDIUM", "LARGE", "EXTRA_LARGE" ] }, "measures": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardMeasureConfig" }, "minItems": 1, "maxItems": 10 }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardFilterConfig" }, "maxItems": 20 }, "interval": { "type": "string", "enum": [ "HOUR", "DAY", "WEEK", "MONTH" ] }, "comparisonMode": { "type": "string", "enum": [ "NONE", "PREVIOUS_PERIOD" ] }, "comparisonGroups": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardFilterConfig" }, "minItems": 1, "maxItems": 20 }, "color": { "type": "string", "enum": [ "GREEN", "RED", "ORANGE", "PURPLE", "GREY", "BLUE", "PEACH", "TEAL", "INDIGO", "AMBER", "ROSE", "CYAN" ] } }, "required": [ "name", "filters" ] }, "minItems": 2, "maxItems": 5 } }, "required": [ "name", "measures" ] }, "DashboardMeasureConfig": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC", "CONVERSATION", "UPTIME" ] }, "metric": { "type": "string", "minLength": 1 }, "aggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ] }, "percentile": { "type": "integer", "minimum": 0, "maximum": 100 }, "distinctBy": { "type": "string", "enum": [ "NONE", "CALL" ] }, "nestedAggregation": { "type": "string", "enum": [ "COUNT", "AVG", "MIN", "MAX", "SUM", "MEDIAN", "PERCENTILE", "PASS_RATE" ] }, "nestedAggregationPercentile": { "type": "integer", "minimum": 0, "maximum": 100 }, "passOperator": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL_TO", "LESS_THAN", "LESS_THAN_OR_EQUAL_TO", "CONTAINS", "STARTS_WITH" ] }, "passValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "breakdown": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "METRIC_PROPERTY", "CALL_PROPERTY", "AGENT_PROPERTY", "DATASET" ] }, "property": { "type": "string" } }, "required": [ "type" ] }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardFilterConfig" }, "maxItems": 20 }, "isBaseline": { "type": "boolean" }, "color": { "type": "string", "enum": [ "GREEN", "RED", "ORANGE", "PURPLE", "GREY", "BLUE", "PEACH", "TEAL", "INDIGO", "AMBER", "ROSE", "CYAN" ] } } }, "ProjectConfig": { "type": "object", "properties": { "kind": { "type": "string", "const": "project" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_.]*$", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 2000 }, "category": { "type": "string", "enum": [ "HEALTHCARE", "FINANCIAL", "RETAIL", "HOSPITALITY", "AUTOMOTIVE", "GOVERNMENT", "EDUCATION", "REAL_ESTATE", "OTHER" ] }, "dataStorageRegion": { "type": "string", "enum": [ "US_EAST_1", "EU_WEST_1" ] }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/OrgProjectMemberConfig" } }, "resources": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/AgentConfig" }, { "$ref": "#/components/schemas/HttpRequestDefinitionConfig" }, { "$ref": "#/components/schemas/PersonaConfig" }, { "$ref": "#/components/schemas/ImprovFlowConfig" }, { "$ref": "#/components/schemas/ScriptedFlowConfig" }, { "$ref": "#/components/schemas/CollectorConfig" }, { "$ref": "#/components/schemas/MetricConfig" }, { "$ref": "#/components/schemas/ApiCheckMetricConfig" }, { "$ref": "#/components/schemas/ThresholdMetricConfig" }, { "$ref": "#/components/schemas/SimulationPlanConfig" }, { "$ref": "#/components/schemas/QaSimulationPlanConfig" }, { "$ref": "#/components/schemas/SimulationGroupConfig" }, { "$ref": "#/components/schemas/AlertConfig" }, { "$ref": "#/components/schemas/ToolConfig" }, { "$ref": "#/components/schemas/DashboardConfig" } ] } } }, "required": [ "kind", "name" ] }, "OrgProjectMemberConfig": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER", "VIEWER" ] } }, "required": [ "email", "role" ] }, "ConfigApplyResponse": { "type": "object", "properties": { "changes": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigApplyChange" } }, "summary": { "$ref": "#/components/schemas/ConfigApplySummary" } }, "required": [ "changes", "summary" ] }, "ConfigApplyChange": { "allOf": [ { "$ref": "#/components/schemas/ConfigDiffChange" } ], "properties": { "status": { "type": "string", "enum": [ "applied", "skipped", "failed" ] }, "id": { "type": "string" }, "signingSecret": { "type": "string" }, "error": { "type": "string" } }, "required": [ "status" ] }, "ConfigApplySummary": { "allOf": [ { "$ref": "#/components/schemas/ConfigDiffSummary" } ], "properties": { "failed": { "type": "integer" } }, "required": [ "failed" ] }, "ListOrgProjectsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgProject" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "count": { "type": "integer" } }, "required": [ "page", "limit", "count" ] } }, "required": [ "data", "pagination" ] }, "OrgProject": { "type": "object", "properties": { "id": { "type": "string", "description": "Project id" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string", "description": "URL-safe slug, generated from the name at create time" }, "description": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ], "enum": [ "HEALTHCARE", "FINANCIAL", "RETAIL", "HOSPITALITY", "AUTOMOTIVE", "GOVERNMENT", "EDUCATION", "REAL_ESTATE", "OTHER" ] }, "dataStorageRegion": { "type": "string", "enum": [ "US_EAST_1", "EU_WEST_1" ] }, "retentionDays": { "type": [ "integer", "null" ] }, "retentionMode": { "type": "string", "enum": [ "SOFT_DELETE", "HARD_DELETE" ] }, "configKey": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp" } }, "required": [ "id", "organizationId", "name", "slug", "description", "category", "dataStorageRegion", "retentionDays", "retentionMode", "configKey", "createdAt", "updatedAt" ] }, "CreateOrgProjectInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Human-readable project name", "example": "Voice VA - prod" }, "description": { "type": "string", "maxLength": 2000 }, "category": { "type": "string", "enum": [ "HEALTHCARE", "FINANCIAL", "RETAIL", "HOSPITALITY", "AUTOMOTIVE", "GOVERNMENT", "EDUCATION", "REAL_ESTATE", "OTHER" ], "description": "Defaults to OTHER" }, "dataStorageRegion": { "type": "string", "enum": [ "US_EAST_1", "EU_WEST_1" ], "description": "Defaults to US_EAST_1" } }, "required": [ "name" ] }, "UpdateOrgProjectInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "category": { "type": "string", "enum": [ "HEALTHCARE", "FINANCIAL", "RETAIL", "HOSPITALITY", "AUTOMOTIVE", "GOVERNMENT", "EDUCATION", "REAL_ESTATE", "OTHER" ] } } }, "DeleteOrgResourceResponse": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ] }, "ListOrgProjectMembersResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgProjectMember" } } }, "required": [ "data" ] }, "OrgProjectMember": { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "userId": { "type": [ "string", "null" ] }, "inviteeEmail": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER", "VIEWER" ] }, "status": { "type": "string" }, "configManaged": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "userId", "inviteeEmail", "role", "status", "configManaged", "createdAt", "updatedAt" ] }, "InviteOrgProjectMemberInput": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email address to invite", "example": "jane@seek.com" }, "role": { "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER", "VIEWER" ], "description": "Project role to grant" } }, "required": [ "email", "role" ] }, "UpdateOrgProjectMemberInput": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER", "VIEWER" ] } }, "required": [ "role" ] }, "ListOrgProjectApiKeysResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgProjectApiKey" } } }, "required": [ "data" ] }, "OrgProjectApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "suffix": { "type": "string" }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "status": { "type": [ "string", "null" ] }, "lastUsedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "prefix", "suffix", "scopes", "permissions", "status", "lastUsedAt", "createdAt", "updatedAt" ] }, "CreateOrgProjectApiKeyResponse": { "allOf": [ { "$ref": "#/components/schemas/OrgProjectApiKey" } ], "properties": { "key": { "type": "string", "description": "The API key value, returned only once at creation" } }, "required": [ "key" ] }, "CreateOrgProjectApiKeyInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Human label for the key", "example": "prod-runtime" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "READ", "WRITE" ] }, "minItems": 1 }, "permissions": { "type": "array", "items": { "type": "string" } } }, "required": [ "name" ] }, "UsageReport": { "type": "object", "properties": { "from": { "type": "string", "description": "The resolved window start, echoed back as ISO 8601." }, "to": { "type": "string", "description": "The resolved window end, echoed back as ISO 8601." }, "currency": { "type": "string", "const": "usd" }, "totalUsdMicros": { "type": "integer", "description": "Total billable spend across the organization (or the single project) in micro-dollars." }, "totalUsd": { "type": "number", "description": "The same total in US dollars." }, "projects": { "type": "array", "items": { "$ref": "#/components/schemas/UsageProjectCost" }, "description": "Per-project billable spend, highest first. Only projects with spend in the window appear." } }, "required": [ "from", "to", "currency", "totalUsdMicros", "totalUsd", "projects" ] }, "UsageProjectCost": { "type": "object", "properties": { "projectId": { "type": "string", "format": "uuid" }, "projectName": { "type": [ "string", "null" ], "description": "Null only if the project no longer exists in this organization." }, "amountUsdMicros": { "type": "integer", "description": "Billable spend in integer micro-dollars (1,000,000 = $1). The exact value." }, "amountUsd": { "type": "number", "description": "The same billable spend in US dollars. For display; use amountUsdMicros to reconcile." }, "breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/UsageCostType" }, "description": "This project's spend split by cost type, highest first. Sums to amountUsdMicros." } }, "required": [ "projectId", "projectName", "amountUsdMicros", "amountUsd", "breakdown" ] }, "UsageCostType": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "SIM_PLATFORM_FEE", "SIM_TTS", "SIM_STT", "SIM_LLM", "SIM_TELEPHONY", "METRIC", "TRANSCRIPTION", "INTERNAL_LLM", "INTERNAL_STT", "PHONE_NUMBER" ], "description": "The cost source, e.g. SIM_PLATFORM_FEE, SIM_LLM, SIM_TTS, SIM_STT, SIM_TELEPHONY, METRIC, or TRANSCRIPTION. These are the granular sources behind the Billing screen categories (SIM_* roll up into \"Simulation\")." }, "surface": { "type": "string", "enum": [ "SIMULATION", "POST_CALL" ], "description": "Whether this cost came from a SIMULATION or a production call (POST_CALL)." }, "amountUsdMicros": { "type": "integer", "description": "Billable spend for this type, in micro-dollars." }, "amountUsd": { "type": "number", "description": "The same figure in US dollars." } }, "required": [ "source", "surface", "amountUsdMicros", "amountUsd" ] }, "BenchmarkSuite": { "type": "object", "properties": { "suite": { "type": "string" }, "latestSuiteVersion": { "type": "string", "description": "The version every endpoint defaults to for this suite." }, "latestPublishedAt": { "type": "string" }, "targetCount": { "type": "integer", "description": "Targets currently published under the latest version." } }, "required": [ "suite", "latestSuiteVersion", "latestPublishedAt", "targetCount" ], "description": "A benchmark suite with published results" }, "BenchmarkMetric": { "type": "object", "properties": { "metricKey": { "type": "string" }, "metricName": { "type": "string" }, "metricKind": { "type": "string", "enum": [ "NUMERIC", "BOOLEAN" ], "description": "Which statistics are populated on a result. NUMERIC fills p50/p95/mean/ci; BOOLEAN fills passRate and its interval." }, "unitSymbol": { "type": [ "string", "null" ] }, "goal": { "type": "string", "enum": [ "higher", "lower", "neutral" ], "description": "Which end of the scale is better. `higher` and `lower` can be ranked; `neutral` is an observational metric that describes a conversation rather than grading it, so sorting on it names no winner." } }, "required": [ "metricKey", "metricName", "metricKind", "unitSymbol", "goal" ], "description": "A metric a suite version published, and the direction that counts as better" }, "BenchmarkLeaderboardRow": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/BenchmarkTarget" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkResult" }, "description": "The projected cells for this row, measured under the requested condition." } }, "required": [ "target", "metrics" ] }, "BenchmarkTarget": { "type": "object", "properties": { "targetKey": { "type": "string", "description": "Stable identity of the model/stack across sweeps. Cite this, and pass it to the target endpoints." }, "targetName": { "type": "string", "description": "Human-readable name of the model/stack." }, "suite": { "type": "string" }, "suiteVersion": { "type": "string" }, "publicationId": { "type": "string", "format": "uuid", "description": "Id of this one sweep. Changes every time the target is re-published, so it is a render key, not an identity." }, "iterations": { "type": "integer", "description": "Calls the sweep requested per condition." }, "sampleCallCount": { "type": "integer", "description": "Executed calls that contributed at least one score to these numbers." }, "publishedAt": { "type": "string", "description": "When this sweep was published (ISO-8601), i.e. data freshness." }, "supersededAt": { "type": [ "string", "null" ], "description": "When a later sweep replaced this one. Null means it is the current generation." }, "isCurrent": { "type": "boolean", "description": "Whether these are the numbers Roark publishes for this target today." } }, "required": [ "targetKey", "targetName", "suite", "suiteVersion", "publicationId", "iterations", "sampleCallCount", "publishedAt", "supersededAt", "isCurrent" ], "description": "A model or stack with a published result on a benchmark suite" }, "BenchmarkResult": { "type": "object", "properties": { "conditionKey": { "type": "string", "description": "What these numbers were measured under: from suite v1.3 an industry scenario (`healthcare`, `home-services`, `insurance`, `customer-support`), before that a flow variant. The empty string is the overall rollup across all conditions." }, "conditionLabel": { "type": "string" }, "metricKey": { "type": "string", "description": "Stable metric id, e.g. `response_time`." }, "metricName": { "type": "string" }, "metricKind": { "type": "string", "enum": [ "NUMERIC", "BOOLEAN" ], "description": "Which statistics are populated on a result. NUMERIC fills p50/p95/mean/ci; BOOLEAN fills passRate and its interval." }, "unitSymbol": { "type": [ "string", "null" ], "description": "Display unit for numeric metrics, e.g. `ms`." }, "n": { "type": "integer", "description": "Scored samples behind this aggregate." }, "p50": { "type": [ "number", "null" ] }, "p95": { "type": [ "number", "null" ] }, "mean": { "type": [ "number", "null" ] }, "ciLow": { "type": [ "number", "null" ], "description": "Low bound of the 95% CI of the mean (NUMERIC metrics)." }, "ciHigh": { "type": [ "number", "null" ] }, "passRate": { "type": [ "number", "null" ], "description": "Fraction passed, 0..1 (BOOLEAN metrics)." }, "passRateCiLow": { "type": [ "number", "null" ], "description": "Low bound of the 95% Wilson interval on the pass rate." }, "passRateCiHigh": { "type": [ "number", "null" ] } }, "required": [ "conditionKey", "conditionLabel", "metricKey", "metricName", "metricKind", "unitSymbol", "n", "p50", "p95", "mean", "ciLow", "ciHigh", "passRate", "passRateCiLow", "passRateCiHigh" ], "description": "One aggregate cell: a metric measured for one target under one condition" }, "BenchmarkSortDescriptor": { "type": "object", "properties": { "metricKey": { "type": "string" }, "order": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "metricKey", "order" ], "description": "The ranking this page was produced under" }, "BenchmarkPagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer", "description": "Total matching records, ignoring this page." }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "offset", "total", "hasMore" ] }, "BenchmarkScoreSample": { "type": "object", "properties": { "conditionKey": { "type": "string" }, "metricKey": { "type": "string" }, "sourceCallId": { "type": "string", "description": "Opaque id of the call this single score came from. Groups samples that share a call; it is not resolvable through this API." }, "numericValue": { "type": [ "number", "null" ] }, "booleanValue": { "type": [ "boolean", "null" ] }, "reasoning": { "type": "string", "description": "The scorer's rationale for this individual score." } }, "required": [ "conditionKey", "metricKey", "sourceCallId", "numericValue", "booleanValue", "reasoning" ], "description": "One un-aggregated score behind a result cell, with the reasoning that produced it" }, "BenchmarkGeneration": { "type": "object", "properties": { "publicationId": { "type": "string", "format": "uuid" }, "suite": { "type": "string" }, "suiteVersion": { "type": "string" }, "targetKey": { "type": "string" }, "targetName": { "type": "string" }, "iterations": { "type": "integer" }, "sampleCallCount": { "type": "integer" }, "publishedAt": { "type": "string" }, "supersededAt": { "type": [ "string", "null" ], "description": "When a later sweep replaced this generation. Null means it is the current one." }, "isCurrent": { "type": "boolean", "description": "Whether this is the generation the other endpoints return." } }, "required": [ "publicationId", "suite", "suiteVersion", "targetKey", "targetName", "iterations", "sampleCallCount", "publishedAt", "supersededAt", "isCurrent" ], "description": "One published sweep of a target, current or superseded — an entry in its history" }, "BenchmarkTargetDetail": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/BenchmarkTarget" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkResult" }, "description": "Every cell of this sweep: the overall rollup plus one set per condition." } }, "required": [ "target", "results" ] }, "VapiCallUploadResponse": { "type": "object", "properties": { "callId": { "type": "string", "description": "ID of the uploaded call" } }, "required": [ "callId" ], "description": "Vapi call upload response" }, "VapiCallUploadCreate": { "type": "object", "properties": { "vapiEndOfCallReportPayload": { "type": "object", "additionalProperties": {}, "description": "Raw Vapi data forwarded directly from the Vapi end-of-call-report webhook" }, "properties": { "type": "object", "additionalProperties": {}, "description": "Optional metadata (key-value pairs) to include with the call. Useful for filtering and display in call details." }, "skipAlreadyImported": { "type": "boolean", "default": false, "description": "Skip already imported Vapi calls with the same Vapi call id." } }, "required": [ "vapiEndOfCallReportPayload" ], "description": "Vapi call upload payload", "example": { "vapiEndOfCallReportPayload": { "call": { "monitor": { "listenUrl": "https://example.com/listen" }, "id": "call-123", "type": "inboundPhoneCall" }, "type": "end-of-call-report", "status": "completed", "assistant": { "name": "Agent Smith" }, "customer": { "number": "+1234567890" }, "phoneNumber": { "number": "+0987654321" }, "artifact": { "recordingUrl": "https://example.com/recording.mp3", "stereoRecordingUrl": "https://example.com/stereo-recording.mp3", "messages": [ { "role": "system", "content": "System message" }, { "role": "bot", "content": "Hello, I'm Agent Smith" }, { "role": "user", "content": "Hello" } ] }, "startedAt": "2025-05-19T23:13:32+08:00", "endedAt": "2025-05-19T23:23:32+08:00", "endedReason": "customer-ended-call" }, "properties": { "business_name": "customer-business-name", "business_id": "customer-business-id" } } }, "RetellCallUploadResponse": { "type": "object", "properties": { "callId": { "type": "string", "description": "ID of the uploaded call" } }, "required": [ "callId" ], "description": "Retell call upload response" }, "RetellCallUploadCreate": { "type": "object", "properties": { "retellCallEndedPayload": { "type": "object", "additionalProperties": {}, "description": "Raw Retell data forwarded directly from the Retell call_ended webhook" }, "properties": { "type": "object", "additionalProperties": {}, "description": "Optional metadata (key-value pairs) to include with the call. Useful for filtering and display in call details." }, "skipAlreadyImported": { "type": "boolean", "default": false, "description": "Skip already imported Retell calls with the same Retell call id." } }, "required": [ "retellCallEndedPayload" ], "description": "Retell call upload payload", "example": { "retellCallEndedPayload": { "event": "call_ended", "call": { "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6", "from_number": "+1234567890", "call_type": "web_call", "start_timestamp": "1703302407333", "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", "to_number": "+0987654321", "direction": "inbound", "recording_url": "https://retell.ai/recordings/call-123456.mp3", "disconnection_reason": "agent_hangup", "end_timestamp": "1703302407333", "duration_ms": 120000, "transcript_object": [ { "role": "agent", "content": "Hello, thank you for calling!", "words": [ { "word": "Hello", "start": 0.7, "end": 1 } ] }, { "role": "user", "content": "Hi, I have a question about my account.", "words": [ { "word": "Hi", "start": 2.5, "end": 2.7 } ] } ], "transcript_with_tool_calls": [ { "role": "tool_call_result", "tool_call_id": "call-id-123", "name": "function_name", "arguments": "{ key: \"value\" }" } ] } }, "properties": { "business_name": "customer-business-name", "business_id": "customer-business-id" } } }, "CallAnalysisCompletedWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "call.analysis.completed", "description": "Event name", "example": "call.analysis.completed" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "callId": { "type": "string", "format": "uuid", "description": "The call this analysis ran on" }, "callAnalysisJobId": { "type": "string", "format": "uuid", "description": "The completed call analysis job" }, "projectId": { "type": "string", "format": "uuid", "description": "Project the call belongs to" } }, "required": [ "callId", "callAnalysisJobId", "projectId" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "call.analysis.completed" }, "CallAnalysisFailedWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "call.analysis.failed", "description": "Event name", "example": "call.analysis.failed" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "callId": { "type": "string", "format": "uuid", "description": "The call this analysis ran on" }, "callAnalysisJobId": { "type": "string", "format": "uuid", "description": "The completed call analysis job" }, "projectId": { "type": "string", "format": "uuid", "description": "Project the call belongs to" }, "errorMessage": { "type": "string", "description": "Failure reason if available" } }, "required": [ "callId", "callAnalysisJobId", "projectId" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "call.analysis.failed" }, "CallAnalysisCancelledWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "call.analysis.cancelled", "description": "Event name", "example": "call.analysis.cancelled" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "callId": { "type": "string", "format": "uuid", "description": "The call this analysis ran on" }, "callAnalysisJobId": { "type": "string", "format": "uuid", "description": "The completed call analysis job" }, "projectId": { "type": "string", "format": "uuid", "description": "Project the call belongs to" } }, "required": [ "callId", "callAnalysisJobId", "projectId" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "call.analysis.cancelled" }, "CallEvaluationCompletedWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "call.evaluation.completed", "description": "Event name", "example": "call.evaluation.completed" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "evaluationJobId": { "type": "string", "format": "uuid", "description": "The completed evaluation job" }, "projectId": { "type": "string", "format": "uuid", "description": "Project the evaluation belongs to" } }, "required": [ "evaluationJobId", "projectId" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "call.evaluation.completed" }, "CallEvaluationFailedWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "call.evaluation.failed", "description": "Event name", "example": "call.evaluation.failed" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "evaluationJobId": { "type": "string", "format": "uuid", "description": "The completed evaluation job" }, "projectId": { "type": "string", "format": "uuid", "description": "Project the evaluation belongs to" }, "errorMessage": { "type": "string", "description": "Failure reason if available" } }, "required": [ "evaluationJobId", "projectId" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "call.evaluation.failed" }, "SimulationRunPlanJobStartedWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "simulation.run_plan_job.started", "description": "Event name", "example": "simulation.run_plan_job.started" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "simulationRunPlanJobId": { "type": "string", "format": "uuid", "description": "The run plan job this event is about" } }, "required": [ "simulationRunPlanJobId" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "simulation.run_plan_job.started" }, "SimulationRunPlanJobCompletedWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "simulation.run_plan_job.completed", "description": "Event name", "example": "simulation.run_plan_job.completed" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "simulationRunPlanJobId": { "type": "string", "format": "uuid", "description": "The run plan job this event is about" } }, "required": [ "simulationRunPlanJobId" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "simulation.run_plan_job.completed" }, "SimulationRunPlanJobFailedWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "simulation.run_plan_job.failed", "description": "Event name", "example": "simulation.run_plan_job.failed" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "simulationRunPlanJobId": { "type": "string", "format": "uuid", "description": "The run plan job this event is about" }, "status": { "type": "string", "description": "Terminal status of the job" }, "reason": { "type": "string", "description": "Human-readable reason for the failure" } }, "required": [ "simulationRunPlanJobId" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "simulation.run_plan_job.failed" }, "SimulationRunPlanJobCancelledWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "simulation.run_plan_job.cancelled", "description": "Event name", "example": "simulation.run_plan_job.cancelled" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "simulationRunPlanJobId": { "type": "string", "format": "uuid", "description": "The run plan job this event is about" } }, "required": [ "simulationRunPlanJobId" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "simulation.run_plan_job.cancelled" }, "SimulationJobStartedWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "simulation.job.started", "description": "Event name", "example": "simulation.job.started" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "simulationJobId": { "type": "string", "format": "uuid", "description": "The simulation job this event is about" }, "simulationRunPlanJobId": { "type": "string", "format": "uuid", "description": "Parent run plan job" } }, "required": [ "simulationJobId", "simulationRunPlanJobId" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "simulation.job.started" }, "SimulationJobCompletedWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "simulation.job.completed", "description": "Event name", "example": "simulation.job.completed" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "simulationJobId": { "type": "string", "format": "uuid", "description": "The simulation job this event is about" }, "simulationRunPlanJobId": { "type": "string", "format": "uuid", "description": "Parent run plan job" }, "callId": { "type": "string", "format": "uuid", "description": "The call produced by this simulation job, if any" } }, "required": [ "simulationJobId", "simulationRunPlanJobId" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "simulation.job.completed" }, "SimulationJobFailedWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "simulation.job.failed", "description": "Event name", "example": "simulation.job.failed" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "simulationJobId": { "type": "string", "format": "uuid", "description": "The simulation job this event is about" }, "simulationRunPlanJobId": { "type": "string", "format": "uuid", "description": "Parent run plan job" }, "status": { "type": "string", "description": "Terminal status of the job" }, "reason": { "type": "string", "description": "Human-readable reason for the failure" } }, "required": [ "simulationJobId", "simulationRunPlanJobId" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "simulation.job.failed" }, "SimulationJobCancelledWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "simulation.job.cancelled", "description": "Event name", "example": "simulation.job.cancelled" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "simulationJobId": { "type": "string", "format": "uuid", "description": "The simulation job this event is about" }, "simulationRunPlanJobId": { "type": "string", "format": "uuid", "description": "Parent run plan job" } }, "required": [ "simulationJobId", "simulationRunPlanJobId" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "simulation.job.cancelled" }, "MetricCollectionJobCompletedWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "metric_collection.job.completed", "description": "Event name", "example": "metric_collection.job.completed" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "metricCollectionJobId": { "type": "string", "format": "uuid", "description": "The metric collection job that completed" }, "projectId": { "type": "string", "format": "uuid", "description": "Project the job ran in" }, "callIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Calls included in the job" }, "policyIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Metric policies that matched and triggered the job (empty for user-triggered jobs)" } }, "required": [ "metricCollectionJobId", "projectId", "callIds", "policyIds" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "metric_collection.job.completed" }, "MetricCollectionJobFailedWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "metric_collection.job.failed", "description": "Event name", "example": "metric_collection.job.failed" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "metricCollectionJobId": { "type": "string", "format": "uuid", "description": "The metric collection job that completed" }, "projectId": { "type": "string", "format": "uuid", "description": "Project the job ran in" }, "callIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Calls included in the job" }, "policyIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Metric policies that matched and triggered the job (empty for user-triggered jobs)" }, "errorMessage": { "type": "string", "description": "Failure reason if available" } }, "required": [ "metricCollectionJobId", "projectId", "callIds", "policyIds" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "metric_collection.job.failed" }, "ChatAnalysisCompletedWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "chat.analysis.completed", "description": "Event name", "example": "chat.analysis.completed" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "chatId": { "type": "string", "format": "uuid", "description": "The chat this analysis ran on" }, "projectId": { "type": "string", "format": "uuid", "description": "Project the chat belongs to" } }, "required": [ "chatId", "projectId" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "chat.analysis.completed" }, "ChatAnalysisFailedWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "chat.analysis.failed", "description": "Event name", "example": "chat.analysis.failed" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "chatId": { "type": "string", "format": "uuid", "description": "The chat this analysis ran on" }, "projectId": { "type": "string", "format": "uuid", "description": "Project the chat belongs to" }, "errorMessage": { "type": "string", "description": "Failure reason if available" } }, "required": [ "chatId", "projectId" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "chat.analysis.failed" }, "IssueOpenedWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "issue.opened", "description": "Event name", "example": "issue.opened" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "issueId": { "type": "string", "format": "uuid", "description": "The issue that was opened" }, "alertId": { "type": [ "string", "null" ], "format": "uuid", "description": "Alert configuration that produced the issue, or null for non-alert sources" }, "projectId": { "type": "string", "format": "uuid", "description": "Project the issue belongs to" }, "source": { "type": "string", "enum": [ "TREND_ALERT", "SINGLE_CALL_ALERT", "TRACE_FAILURE", "MANUAL", "API", "AGENT" ], "description": "What produced the issue (trend alert, AI clustering, manual triage, API, ...)" }, "title": { "type": [ "string", "null" ], "description": "Issue title at the time it opened, when available" }, "severity": { "type": [ "string", "null" ], "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "Issue severity, or null when the producer did not set one" }, "groupKey": { "type": [ "string", "null" ], "description": "Group key identifying the issue dimension (per the alert config); null for non-alert sources" }, "openedAt": { "type": "string", "format": "date-time", "description": "When the issue was first opened" }, "value": { "type": [ "number", "null" ], "description": "Triggering metric value, or null when the alert tracks presence/absence" } }, "required": [ "issueId", "alertId", "projectId", "source", "title", "severity", "groupKey", "openedAt", "value" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "issue.opened" }, "IssueResolvedWebhook": { "type": "object", "properties": { "event": { "type": "string", "const": "issue.resolved", "description": "Event name", "example": "issue.resolved" }, "version": { "type": "string", "const": "1.0", "description": "Payload schema version", "example": "1.0" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the webhook was generated", "example": "2026-05-18T09:44:40.971Z" }, "data": { "type": "object", "properties": { "issueId": { "type": "string", "format": "uuid", "description": "The issue that was opened" }, "alertId": { "type": [ "string", "null" ], "format": "uuid", "description": "Alert configuration that produced the issue, or null for non-alert sources" }, "projectId": { "type": "string", "format": "uuid", "description": "Project the issue belongs to" }, "source": { "type": "string", "enum": [ "TREND_ALERT", "SINGLE_CALL_ALERT", "TRACE_FAILURE", "MANUAL", "API", "AGENT" ], "description": "What produced the issue (trend alert, AI clustering, manual triage, API, ...)" }, "title": { "type": [ "string", "null" ], "description": "Issue title at the time it opened, when available" }, "severity": { "type": [ "string", "null" ], "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "Issue severity, or null when the producer did not set one" }, "groupKey": { "type": [ "string", "null" ], "description": "Group key identifying the issue dimension (per the alert config); null for non-alert sources" }, "openedAt": { "type": "string", "format": "date-time", "description": "When the issue was first opened" }, "value": { "type": [ "number", "null" ], "description": "Triggering metric value, or null when the alert tracks presence/absence" }, "resolvedAt": { "type": "string", "format": "date-time", "description": "When the issue was resolved" } }, "required": [ "issueId", "alertId", "projectId", "source", "title", "severity", "groupKey", "openedAt", "value", "resolvedAt" ] } }, "required": [ "event", "version", "timestamp", "data" ], "title": "issue.resolved" }, "HttpRequestMetricPayload": { "type": "object", "properties": { "version": { "type": "string", "const": "1.0", "description": "Payload schema version" }, "requestId": { "type": "string", "format": "uuid", "description": "Unique per request. Quote it when reporting a problem." }, "metric": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "call": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "callDirection": { "type": "string", "description": "INBOUND or OUTBOUND", "example": "INBOUND" }, "startedAt": { "type": "string", "format": "date-time", "example": "2026-10-26T14:00:02.000Z" }, "endedAt": { "type": [ "string", "null" ], "format": "date-time" }, "durationMs": { "type": [ "number", "null" ] }, "endedStatus": { "type": [ "string", "null" ] }, "externalId": { "type": [ "string", "null" ], "description": "Your correlation id, if you sent one with the call" }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Roark agent id" }, "endpoint": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "environment": { "type": "string" }, "phoneNumberE164": { "type": [ "string", "null" ] } }, "required": [ "id", "environment", "phoneNumberE164" ], "description": "The endpoint the call reached the agent on, when known" } }, "required": [ "id", "endpoint" ] } }, "customers": { "type": "array", "items": { "type": "object", "properties": { "phoneNumberE164": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] } }, "required": [ "phoneNumberE164", "label" ] } }, "properties": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The custom properties on the call", "example": { "cardId": "card_123" } } }, "required": [ "id", "projectId", "callDirection", "startedAt", "endedAt", "durationMs", "endedStatus", "externalId", "agents", "customers", "properties" ] }, "simulation": { "type": [ "object", "null" ], "properties": { "jobId": { "type": "string", "format": "uuid" }, "runPlanJobId": { "type": [ "string", "null" ], "format": "uuid" }, "flow": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" } }, "required": [ "id", "title" ] }, "testCase": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "isDefault": { "type": "boolean" } }, "required": [ "id", "title", "isDefault" ], "description": "The test case of the flow this call ran. isDefault is true for the happy path." }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The run variables this simulation ran with", "example": { "cardNumber": "4111111111111111", "newPin": "4821" } }, "persona": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The persona the simulated caller played" } }, "required": [ "jobId", "runPlanJobId", "flow", "testCase", "variables", "persona" ], "description": "Set when the call is a Roark simulation, null on a live call" } }, "required": [ "version", "requestId", "metric", "call", "simulation" ], "title": "HTTP request metric payload" }, "HttpRequestMetricVerdict": { "type": "object", "properties": { "passed": { "type": "boolean", "description": "Whether the call did what it should" }, "reason": { "type": "string", "description": "Shown next to the result in Roark. Longer than 1000 characters is cut." } }, "required": [ "passed" ], "title": "HTTP request metric verdict" } } }, "security": [ { "Bearer": [] } ], "servers": [ { "description": "Production", "url": "https://api.roark.ai" } ], "tags": [ { "name": "Agent" }, { "name": "Agent Endpoint" }, { "name": "Phone Number" }, { "name": "Call" }, { "name": "Chat" }, { "name": "Metric" }, { "name": "Metric Policy" }, { "name": "Metric Collection Job" }, { "name": "Customer Flow" }, { "name": "Customer Flow Edge Case" }, { "name": "Simulation" }, { "name": "Simulation Persona" }, { "name": "Simulation Environment" }, { "name": "Simulation Scenario" }, { "name": "Simulation Run Plan" }, { "name": "Simulation Template" }, { "name": "Simulation Run Plan Job" }, { "name": "Simulation Job" }, { "name": "HTTP Request Definition" }, { "name": "Webhook" }, { "name": "Issue" }, { "name": "Autoimprove" }, { "name": "Agent Config" }, { "name": "Knowledge Base" }, { "name": "Config" }, { "name": "Organization Project" }, { "name": "Organization Project Member" }, { "name": "Organization Project API Key" }, { "name": "Organization Config" }, { "name": "CLI Auth" }, { "name": "Me" }, { "name": "Project" }, { "name": "Usage" }, { "name": "Analytics" }, { "name": "Dashboard" }, { "name": "Benchmark" }, { "name": "Health" }, { "name": "Prospect Simulation" } ], "webhooks": { "Webhook": { "post": { "operationId": "webhook_event", "summary": "Event", "description": "Roark POSTs a JSON payload to every endpoint subscribed to one of the events listed below. Every payload uses the same envelope (`event`, `version`, `timestamp`, `data`); the `event` field is the discriminator that selects the matching `data` shape.\n\nAcknowledge with any 2xx response within 10 seconds. Non-2xx responses and timeouts are retried with exponential backoff.\n\n**Events**\n- `call.analysis.completed`\n- `call.analysis.failed`\n- `call.analysis.cancelled`\n- `call.evaluation.completed`\n- `call.evaluation.failed`\n- `simulation.run_plan_job.started`\n- `simulation.run_plan_job.completed`\n- `simulation.run_plan_job.failed`\n- `simulation.run_plan_job.cancelled`\n- `simulation.job.started`\n- `simulation.job.completed`\n- `simulation.job.failed`\n- `simulation.job.cancelled`\n- `metric_collection.job.completed`\n- `metric_collection.job.failed`\n- `chat.analysis.completed`\n- `chat.analysis.failed`\n- `issue.opened`\n- `issue.resolved`", "tags": [ "Webhook" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CallAnalysisCompletedWebhook" }, { "$ref": "#/components/schemas/CallAnalysisFailedWebhook" }, { "$ref": "#/components/schemas/CallAnalysisCancelledWebhook" }, { "$ref": "#/components/schemas/CallEvaluationCompletedWebhook" }, { "$ref": "#/components/schemas/CallEvaluationFailedWebhook" }, { "$ref": "#/components/schemas/SimulationRunPlanJobStartedWebhook" }, { "$ref": "#/components/schemas/SimulationRunPlanJobCompletedWebhook" }, { "$ref": "#/components/schemas/SimulationRunPlanJobFailedWebhook" }, { "$ref": "#/components/schemas/SimulationRunPlanJobCancelledWebhook" }, { "$ref": "#/components/schemas/SimulationJobStartedWebhook" }, { "$ref": "#/components/schemas/SimulationJobCompletedWebhook" }, { "$ref": "#/components/schemas/SimulationJobFailedWebhook" }, { "$ref": "#/components/schemas/SimulationJobCancelledWebhook" }, { "$ref": "#/components/schemas/MetricCollectionJobCompletedWebhook" }, { "$ref": "#/components/schemas/MetricCollectionJobFailedWebhook" }, { "$ref": "#/components/schemas/ChatAnalysisCompletedWebhook" }, { "$ref": "#/components/schemas/ChatAnalysisFailedWebhook" }, { "$ref": "#/components/schemas/IssueOpenedWebhook" }, { "$ref": "#/components/schemas/IssueResolvedWebhook" } ], "discriminator": { "propertyName": "event", "mapping": { "call.analysis.completed": "#/components/schemas/CallAnalysisCompletedWebhook", "call.analysis.failed": "#/components/schemas/CallAnalysisFailedWebhook", "call.analysis.cancelled": "#/components/schemas/CallAnalysisCancelledWebhook", "call.evaluation.completed": "#/components/schemas/CallEvaluationCompletedWebhook", "call.evaluation.failed": "#/components/schemas/CallEvaluationFailedWebhook", "simulation.run_plan_job.started": "#/components/schemas/SimulationRunPlanJobStartedWebhook", "simulation.run_plan_job.completed": "#/components/schemas/SimulationRunPlanJobCompletedWebhook", "simulation.run_plan_job.failed": "#/components/schemas/SimulationRunPlanJobFailedWebhook", "simulation.run_plan_job.cancelled": "#/components/schemas/SimulationRunPlanJobCancelledWebhook", "simulation.job.started": "#/components/schemas/SimulationJobStartedWebhook", "simulation.job.completed": "#/components/schemas/SimulationJobCompletedWebhook", "simulation.job.failed": "#/components/schemas/SimulationJobFailedWebhook", "simulation.job.cancelled": "#/components/schemas/SimulationJobCancelledWebhook", "metric_collection.job.completed": "#/components/schemas/MetricCollectionJobCompletedWebhook", "metric_collection.job.failed": "#/components/schemas/MetricCollectionJobFailedWebhook", "chat.analysis.completed": "#/components/schemas/ChatAnalysisCompletedWebhook", "chat.analysis.failed": "#/components/schemas/ChatAnalysisFailedWebhook", "issue.opened": "#/components/schemas/IssueOpenedWebhook", "issue.resolved": "#/components/schemas/IssueResolvedWebhook" } } } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx response is treated as success." } } } }, "HttpRequestMetric": { "post": { "operationId": "http_request_metric_check", "summary": "HTTP request metric", "description": "What an HTTP request metric sends to your endpoint, and the answer it expects. Roark sends it once per call the metric grades, live or simulated, after the call is analysed.\n\nWith no body template, Roark POSTs the payload below. A body template fills `{{path}}` placeholders from the same payload, for example `{{call.properties.cardId}}` or `{{simulation.variables.newPin}}`. A placeholder the call has no value for (a run variable on a live call) skips the request and records the metric as missing data.\n\nAnswer with HTTP 200 and `{\"passed\": true | false, \"reason\": \"...\"}` within 30 seconds. Timeouts, connection failures and 5xx responses are retried twice with the same `requestId`, so drop a request you have already answered. Any other answer records an error on the metric, never a fail. Redirects are not followed.", "tags": [ "Metric" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpRequestMetricPayload" } } } }, "responses": { "200": { "description": "The verdict for this call.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpRequestMetricVerdict" } } } } } } } }, "paths": { "/health": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HealthResponse" } }, "required": [ "data" ] } } }, "description": "Health check response" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" }, "503": { "description": "Service unavailable — a dependency is unhealthy" } }, "operationId": "getHealth", "tags": [ "Health" ], "summary": "Get API health status", "description": "Returns the health status of the API and its dependencies", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst health = await client.health.get();\n\nconsole.log(health.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nhealth = client.health.get()\nprint(health.data)" } ] } }, "/v1/cli/auth/token": { "post": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string" }, "name": { "type": "string" }, "projectId": { "type": [ "string", "null" ] }, "organizationId": { "type": [ "string", "null" ] }, "defaultProjectId": { "type": [ "string", "null" ] }, "scopeKind": { "type": "string", "enum": [ "PROJECT", "USER" ] } }, "required": [ "token", "name", "projectId", "organizationId", "defaultProjectId", "scopeKind" ] } }, "required": [ "data" ] } } }, "description": "The minted API key" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1CliAuthToken", "tags": [ "CLI Auth" ], "summary": "Exchange a CLI authorization code for an API key", "description": "Completes the CLI browser-login flow: verifies the single-use authorization code and its PKCE code_verifier, then mints and returns the approved API key exactly once.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "code_verifier": { "type": "string", "minLength": 1 } }, "required": [ "code", "code_verifier" ] } } } } } }, "/v1/public/prospect-sim/run": { "post": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "reportToken": { "type": "string" }, "status": { "type": "string" } }, "required": [ "reportToken", "status" ] } }, "required": [ "data" ] } } }, "description": "The simulation was accepted and started" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1PublicProspect-simRun", "tags": [ "Prospect Simulation" ], "summary": "Run a free simulation against a prospect agent", "description": "Public endpoint: provisions a per-prospect project, runs a canned scenario template against the submitted phone number, and returns a report token to poll. The teaser report is also emailed when ready.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "templateKey": { "type": "string", "enum": [ "appointment", "support", "billing" ] }, "phoneNumber": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "agentDescription": { "type": "string", "maxLength": 2000 }, "captchaToken": { "type": "string" } }, "required": [ "templateKey", "phoneNumber", "email" ] } } } } } }, "/v1/public/prospect-sim/report/{token}": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" }, "agentLabel": { "type": "string" }, "prospectName": { "type": [ "string", "null" ] }, "live": { "type": [ "object", "null" ], "properties": { "total": { "type": "number" }, "completed": { "type": "number" }, "activeIndex": { "type": [ "number", "null" ] }, "calls": { "type": "array", "items": { "type": "object", "properties": { "callId": { "type": "string" }, "personaLabel": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "in_progress", "completed", "failed" ] } }, "required": [ "callId", "personaLabel", "state" ] } } }, "required": [ "total", "completed", "activeIndex", "calls" ] }, "teaser": { "type": [ "object", "null" ], "properties": { "verdict": { "type": "string" }, "verdictProse": { "type": "string" }, "callCount": { "type": "number" }, "checksPassed": { "type": "number" }, "checksTotal": { "type": "number" }, "scorecard": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "passed": { "type": "boolean" }, "passRatePct": { "type": [ "number", "null" ] } }, "required": [ "name", "passed", "passRatePct" ] } }, "summary": { "type": "array", "items": { "type": "object", "properties": { "heading": { "type": [ "string", "null" ] }, "body": { "type": "string" } }, "required": [ "heading", "body" ] } }, "themes": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "severity": { "type": "string" }, "affectedCount": { "type": "number" }, "totalCount": { "type": "number" }, "summary": { "type": "string" } }, "required": [ "title", "severity", "affectedCount", "totalCount", "summary" ] } }, "lockedThemeCount": { "type": "number" }, "statTiles": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" }, "sub": { "type": [ "string", "null" ] } }, "required": [ "label", "value", "sub" ] } }, "topFinding": { "type": [ "object", "null" ], "properties": { "title": { "type": "string" }, "body": { "type": "string" } }, "required": [ "title", "body" ] }, "lockedFindingCount": { "type": "number" } }, "required": [ "verdict", "verdictProse", "callCount", "checksPassed", "checksTotal", "scorecard", "summary", "themes", "lockedThemeCount", "statTiles", "topFinding", "lockedFindingCount" ] } }, "required": [ "status", "agentLabel", "prospectName", "live", "teaser" ] } }, "required": [ "data" ] } } }, "description": "The teaser report (or its pending status)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1PublicProspect-simReportByToken", "tags": [ "Prospect Simulation" ], "summary": "Read a prospect simulation teaser report", "description": "Public endpoint scoped by the unguessable report token. Returns a truncated teaser once the debrief is ready; the full report is gated behind claiming an account.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "token", "required": true } ] } }, "/v1/public/prospect-sim/report/{token}/observer-url": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "wsUrl": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ] } }, "required": [ "wsUrl", "expiresAt" ] } }, "required": [ "data" ] } } }, "description": "The live observer URL, or null when not currently watchable" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1PublicProspect-simReportByTokenObserver-url", "tags": [ "Prospect Simulation" ], "summary": "Mint a live observer WebSocket URL for a prospect call", "description": "Public endpoint scoped by the report token. Returns a short-lived, self-authenticating WebSocket URL for watching a prospect call live, but only while that call is actually in flight; otherwise wsUrl is null. Pass `callId` (from the live progress list) to pick one of the parallel calls; without it the most recently started live call is used.", "parameters": [ { "in": "query", "name": "callId", "schema": { "type": "string", "format": "uuid" } }, { "schema": { "type": "string" }, "in": "path", "name": "token", "required": true } ] } }, "/v1/me": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MeResponse" } }, "required": [ "data" ] } } }, "description": "The current credential" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Me", "tags": [ "Me" ], "summary": "Describe the current credential", "description": "Returns the scope of the credential making the request, the organization it acts in, its default project (if any) and the permissions it was granted. Works for both project-scoped API keys and user-scoped credentials from the CLI or an MCP connector.", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst me = await client.me.get();\n\nconsole.log(me.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nme = client.me.get()\nprint(me.data)" } ] } }, "/v1/me/api-keys": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MeApiKeyListResponse" } }, "required": [ "data" ] } } }, "description": "Your personal credentials" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1MeApi-keys", "tags": [ "Me" ], "summary": "List your personal credentials", "description": "Returns the credentials that act as you: the ones created in the dashboard, from `roark auth login`, and MCP connectors. Requires a personal credential; a project API key is refused. Defaults to ACTIVE, pass ?status=REVOKED to see revoked ones. The key value itself is never returned.", "parameters": [ { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "ACTIVE", "REVOKED" ], "description": "Filter by status. Defaults to ACTIVE.", "example": "ACTIVE" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.me.listAPIKeys();\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.me.list_api_keys()\nprint(response.data)" } ] }, "post": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateMyApiKeyResponse" } }, "required": [ "data" ] } } }, "description": "The created credential, with its key value (returned only here)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1MeApi-keys", "tags": [ "Me" ], "summary": "Create a personal credential", "description": "Mints a credential that acts as you, for a CLI or an automation. The key value is returned exactly once, in the `key` field: capture it now, it is unreadable afterwards. Requires a personal credential (a project API key is refused) and admin on the project the credential defaults to. The new credential can never exceed the one that created it: not in scope, not in permissions, and not in lifetime. Omit a field to copy it from the calling credential.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMyApiKeyInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.me.createAPIKey({ name: 'CI deploy gate' });\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.me.create_api_key(\n name=\"CI deploy gate\",\n)\nprint(response.data)" } ] } }, "/v1/me/api-keys/{id}": { "delete": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MeApiKeyRevokeResponse" } }, "required": [ "data" ] } } }, "description": "The credential was revoked" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1MeApi-keysById", "tags": [ "Me" ], "summary": "Revoke one of your personal credentials", "description": "Revokes a credential that acts as you. It stops working immediately. A credential may revoke itself, which is what `roark auth logout` does. Repeating the call is safe; an unknown id, or one belonging to someone else, answers 404.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.me.revokeAPIKey('id');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.me.revoke_api_key(\n \"id\",\n)\nprint(response.data)" } ] } }, "/v1/projects": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectListResponse" } }, "required": [ "data" ] } } }, "description": "Projects available to this credential" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Projects", "tags": [ "Project" ], "summary": "List projects available to this credential", "description": "Returns every project the calling credential may act on, with the permissions it holds in each. A project-scoped API key returns the single project it is bound to. A user-scoped credential returns the projects in its organization where the holder is an active member. Use the returned id in the X-Roark-Project-Id header.", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst projects = await client.project.list();\n\nconsole.log(projects.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nprojects = client.project.list()\nprint(projects.data)" } ] } }, "/v1/agent/endpoint": { "get": { "responses": { "200": { "description": "List of agent endpoints", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentEndpointDetailResponse" } }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of items" }, "hasMore": { "type": "boolean", "description": "Whether there are more items to fetch" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page of items" } }, "required": [ "total", "hasMore", "nextCursor" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1AgentEndpoint", "tags": [ "Agent Endpoint" ], "summary": "List agent endpoints", "description": "Returns a paginated list of agent endpoints for the authenticated project.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20, "description": "Maximum number of endpoints to return (default: 20, max: 50)" } }, { "in": "query", "name": "after", "schema": { "type": "string", "description": "Cursor for pagination - endpoint ID to start after" } }, { "in": "query", "name": "agentId", "schema": { "type": "string", "format": "uuid", "description": "Filter by agent ID" } }, { "in": "query", "name": "searchText", "schema": { "type": "string", "description": "Search text to filter endpoints" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst agentEndpoints = await client.agentEndpoint.list();\n\nconsole.log(agentEndpoints.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nagent_endpoints = client.agent_endpoint.list()\nprint(agent_endpoints.data)" } ] }, "post": { "responses": { "201": { "description": "The created agent endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentEndpointDetailResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1AgentEndpoint", "tags": [ "Agent Endpoint" ], "summary": "Create a new agent endpoint", "description": "Creates a new agent endpoint for the authenticated project.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentEndpointInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst agentEndpoint = await client.agentEndpoint.create({\n agentId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n direction: 'INCOMING',\n value: 'value',\n});\n\nconsole.log(agentEndpoint.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nagent_endpoint = client.agent_endpoint.create(\n agent_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n direction=\"INCOMING\",\n value=\"value\",\n)\nprint(agent_endpoint.data)" } ] } }, "/v1/agent/endpoint/{endpointId}": { "get": { "responses": { "200": { "description": "The requested agent endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentEndpointDetailResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1AgentEndpointByEndpointId", "tags": [ "Agent Endpoint" ], "summary": "Get agent endpoint by ID", "description": "Returns a specific agent endpoint by its ID.", "parameters": [ { "name": "endpointId", "in": "path", "required": true, "description": "The ID of the agent endpoint to retrieve", "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.agentEndpoint.getByID('endpointId');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.agent_endpoint.get_by_id(\n \"endpointId\",\n)\nprint(response.data)" } ] }, "put": { "responses": { "200": { "description": "The updated agent endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentEndpointDetailResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1AgentEndpointByEndpointId", "tags": [ "Agent Endpoint" ], "summary": "Update an agent endpoint", "description": "Updates an existing agent endpoint by its ID. Only environment and outboundDialType can be modified.", "parameters": [ { "name": "endpointId", "in": "path", "required": true, "description": "The ID of the agent endpoint to update", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentEndpointInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst agentEndpoint = await client.agentEndpoint.update('endpointId');\n\nconsole.log(agentEndpoint.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nagent_endpoint = client.agent_endpoint.update(\n endpoint_id=\"endpointId\",\n)\nprint(agent_endpoint.data)" } ] } }, "/v1/agent/{agentId}/prompts": { "get": { "responses": { "200": { "description": "The agent's prompt lineages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAgentPromptsResponse" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1AgentByAgentIdPrompts", "tags": [ "Agent" ], "summary": "List an agent's prompts", "description": "Returns the agent's prompt lineages. Each lineage is an independent version history, labelled by its `source` (USER, API, CONFIG, or a provider integration). `prompt` is the current content.", "parameters": [ { "in": "path", "name": "agentId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst agentPrompts = await client.agentPrompt.list('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(agentPrompts.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nagent_prompts = client.agent_prompt.list(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(agent_prompts.data)" } ] }, "put": { "responses": { "200": { "description": "The prompt was set (or already matched the current version).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SetAgentPromptResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1AgentByAgentIdPrompts", "tags": [ "Agent" ], "summary": "Set an agent's prompt", "description": "Sets the agent's API-managed prompt. This is its own version history (`source: API_MANAGED`), separate from prompts observed on calls, edited in the app, or managed by config-as-code. Setting the same content twice is a no-op (no new version). Roark does not run your agent and no metric reads this prompt: it is stored and versioned for your reference.", "parameters": [ { "in": "path", "name": "agentId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetAgentPromptInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst agentPrompt = await client.agentPrompt.update('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n prompt: 'x',\n});\n\nconsole.log(agentPrompt.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nagent_prompt = client.agent_prompt.update(\n agent_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n prompt=\"x\",\n)\nprint(agent_prompt.data)" } ] } }, "/v1/agent/{agentId}/prompts/{promptId}/versions": { "get": { "responses": { "200": { "description": "The version history of the prompt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAgentPromptVersionsResponse" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1AgentByAgentIdPromptsByPromptIdVersions", "tags": [ "Agent" ], "summary": "List a prompt's versions", "description": "Returns the full version history of a single prompt lineage, newest first.", "parameters": [ { "in": "path", "name": "agentId", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "promptId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.agentPrompt.listVersions('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n agentId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.agent_prompt.list_versions(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n agent_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] } }, "/v1/agent/{agentId}/versions": { "get": { "responses": { "200": { "description": "The agent's versions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentVersionsResponse" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1AgentByAgentIdVersions", "tags": [ "Agent" ], "summary": "List an agent's versions", "description": "The open draft first, if there is one, then published versions newest first. Paginated: pass `pagination.nextCursor` as `after` for the next page.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "in": "query", "name": "after", "schema": { "type": "string", "format": "uuid" } }, { "schema": { "type": "string" }, "in": "path", "name": "agentId", "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst agentVersions = await client.agentVersion.list('agentId');\n\nconsole.log(agentVersions.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nagent_versions = client.agent_version.list(\n agent_id=\"agentId\",\n)\nprint(agent_versions.data)" } ] } }, "/v1/agent/{agentId}/versions/{versionId}": { "get": { "responses": { "200": { "description": "The version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentVersionResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1AgentByAgentIdVersionsByVersionId", "tags": [ "Agent" ], "summary": "Get an agent version", "description": "One version with every setting, plus the issues that stop it from running, if any.", "parameters": [ { "in": "path", "name": "agentId", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "versionId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.agentVersion.getByID('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n agentId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.agent_version.get_by_id(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n agent_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] } }, "/v1/agent/{agentId}/versions/{versionId}/rollback": { "post": { "responses": { "201": { "description": "The new live version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentVersionResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1AgentByAgentIdVersionsByVersionIdRollback", "tags": [ "Agent" ], "summary": "Roll an agent back to a version", "description": "Publishes a new version, numbered after the latest, with this version's settings and makes it live. History stays append-only. An open draft started before this is kept but can no longer be published (409 `agent_draft_base_changed`); discard it or start a new one. Pass `expectedLiveVersionId` to be refused (409 `agent_live_version_changed`) if another version went live since you read it.", "parameters": [ { "in": "path", "name": "agentId", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "versionId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollbackAgentVersionInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.agentVersion.rollback('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n agentId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.agent_version.rollback(\n version_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n agent_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] } }, "/v1/agent/{agentId}/draft": { "get": { "responses": { "200": { "description": "The draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentVersionResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1AgentByAgentIdDraft", "tags": [ "Agent" ], "summary": "Get an agent's draft", "description": "The agent's open draft, with the issues that would stop it from being published.", "parameters": [ { "in": "path", "name": "agentId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst agentDraft = await client.agentDraft.get('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(agentDraft.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nagent_draft = client.agent_draft.get(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(agent_draft.data)" } ] }, "post": { "responses": { "201": { "description": "The new draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentVersionResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1AgentByAgentIdDraft", "tags": [ "Agent" ], "summary": "Start a draft", "description": "Opens the agent's one shared draft, a copy of the live version or of an older published version. Fails with 409 when a draft is already open.", "parameters": [ { "in": "path", "name": "agentId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentDraftInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst agentDraft = await client.agentDraft.create('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(agentDraft.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nagent_draft = client.agent_draft.create(\n agent_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(agent_draft.data)" } ] }, "put": { "responses": { "200": { "description": "The edited draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentVersionResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1AgentByAgentIdDraft", "tags": [ "Agent" ], "summary": "Edit the draft", "description": "Changes settings on the draft. Omitted settings stay as they are. Pass the revision you read as expectedRevision to fail with 409 if anyone edited the draft since, instead of applying on top of their edit.", "parameters": [ { "in": "path", "name": "agentId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentDraftInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst agentDraft = await client.agentDraft.update('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n settings: {},\n});\n\nconsole.log(agentDraft.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nagent_draft = client.agent_draft.update(\n agent_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n settings={},\n)\nprint(agent_draft.data)" } ] }, "delete": { "responses": { "200": { "description": "The discarded draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentVersionResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1AgentByAgentIdDraft", "tags": [ "Agent" ], "summary": "Discard the draft", "description": "Throws the open draft away and returns it. The live version is unchanged.", "parameters": [ { "in": "path", "name": "agentId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst agentDraft = await client.agentDraft.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(agentDraft.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nagent_draft = client.agent_draft.delete(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(agent_draft.data)" } ] } }, "/v1/agent/{agentId}/draft/publish": { "post": { "responses": { "200": { "description": "The published version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentVersionResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1AgentByAgentIdDraftPublish", "tags": [ "Agent" ], "summary": "Publish the draft", "description": "Makes the draft the live version, numbered v1, v2, ... Fails with 409 if the draft was edited after expectedRevision, if another version was published since the draft started, or if it changes nothing; with 400 and the issues if the version cannot run.", "parameters": [ { "in": "path", "name": "agentId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishAgentDraftInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.agentDraft.publish('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n expectedRevision: 1,\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.agent_draft.publish(\n agent_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n expected_revision=1,\n)\nprint(response.data)" } ] } }, "/v1/agent": { "get": { "responses": { "200": { "description": "List of agents", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the agent" }, "name": { "type": "string", "description": "Name of the agent" }, "description": { "type": [ "string", "null" ], "description": "Description of the agent" }, "customId": { "type": [ "string", "null" ], "description": "Custom identifier for the agent" }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format" }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format" } }, "required": [ "id", "name", "description", "customId", "createdAt", "updatedAt" ] } }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of items" }, "hasMore": { "type": "boolean", "description": "Whether there are more items to fetch" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page of items" } }, "required": [ "total", "hasMore", "nextCursor" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Agent", "tags": [ "Agent" ], "summary": "List agents", "description": "Returns a paginated list of agents for the authenticated project.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "in": "query", "name": "after", "schema": { "type": "string" } }, { "in": "query", "name": "searchText", "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst agents = await client.agent.list();\n\nconsole.log(agents.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nagents = client.agent.list()\nprint(agents.data)" } ] }, "post": { "responses": { "201": { "description": "The created agent", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the agent" }, "name": { "type": "string", "description": "Name of the agent" }, "description": { "type": [ "string", "null" ], "description": "Description of the agent" }, "customId": { "type": [ "string", "null" ], "description": "Custom identifier for the agent" }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format" }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format" } }, "required": [ "id", "name", "description", "customId", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1Agent", "tags": [ "Agent" ], "summary": "Create a new agent", "description": "Creates a new agent for the authenticated project.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Name of the agent" }, "description": { "type": [ "string", "null" ], "description": "Description of the agent" }, "customId": { "type": [ "string", "null" ], "description": "Custom identifier for the agent" } }, "required": [ "name" ], "title": "CreateAgentInput", "description": "Input for creating a new agent" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst agent = await client.agent.create({ name: 'x' });\n\nconsole.log(agent.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nagent = client.agent.create(\n name=\"x\",\n)\nprint(agent.data)" } ] } }, "/v1/agent/{agentId}": { "get": { "responses": { "200": { "description": "The requested agent", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the agent" }, "name": { "type": "string", "description": "Name of the agent" }, "description": { "type": [ "string", "null" ], "description": "Description of the agent" }, "customId": { "type": [ "string", "null" ], "description": "Custom identifier for the agent" }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format" }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format" } }, "required": [ "id", "name", "description", "customId", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1AgentByAgentId", "tags": [ "Agent" ], "summary": "Get agent by ID", "description": "Returns a specific agent by its ID.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "The ID of the agent to retrieve", "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.agent.getByID('agentId');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.agent.get_by_id(\n \"agentId\",\n)\nprint(response.data)" } ] }, "put": { "responses": { "200": { "description": "The updated agent", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the agent" }, "name": { "type": "string", "description": "Name of the agent" }, "description": { "type": [ "string", "null" ], "description": "Description of the agent" }, "customId": { "type": [ "string", "null" ], "description": "Custom identifier for the agent" }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format" }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format" } }, "required": [ "id", "name", "description", "customId", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1AgentByAgentId", "tags": [ "Agent" ], "summary": "Update an agent", "description": "Updates an existing agent by its ID.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "The ID of the agent to update", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Name of the agent" }, "description": { "type": [ "string", "null" ], "description": "Description of the agent" } }, "title": "UpdateAgentInput", "description": "Input for updating an existing agent" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst agent = await client.agent.update('agentId');\n\nconsole.log(agent.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nagent = client.agent.update(\n agent_id=\"agentId\",\n)\nprint(agent.data)" } ] }, "delete": { "responses": { "200": { "description": "The agent was deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the deleted agent" }, "deleted": { "type": "boolean", "const": true, "description": "Always true when the agent was successfully deleted" } }, "required": [ "id", "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1AgentByAgentId", "tags": [ "Agent" ], "summary": "Delete an agent", "description": "Soft-deletes an agent by its ID. The agent is hidden from all reads and stops being attributed to new calls, but its record and history are retained. Fails with 409 if the agent is still referenced by simulation run plans: cancel those run plans first. Note: if the agent syncs from a provider integration, also exclude it in the integration settings (or delete the integration) so its calls stop reaching Roark.", "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "The ID of the agent to delete", "schema": { "type": "string" } } ] } }, "/v1/agent/build": { "post": { "responses": { "201": { "description": "The built agent", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the agent" }, "name": { "type": "string", "description": "Name of the agent" }, "description": { "type": [ "string", "null" ], "description": "Description of the agent" }, "customId": { "type": [ "string", "null" ], "description": "Custom identifier for the agent" }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format" }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format" } }, "required": [ "id", "name", "description", "customId", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1AgentBuild", "tags": [ "Agent" ], "summary": "Build a Roark-hosted agent", "description": "Creates a new Roark-hosted agent from a one-line job description. Roark authors the system prompt and hosts the config, so the agent is live and self-improvable from creation.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Name of the agent" }, "jobDescription": { "type": "string", "minLength": 1, "description": "One-line description of what the agent should do. Roark authors the system prompt from this." }, "voice": { "type": [ "string", "null" ], "description": "Optional display name of the agent's voice. The authored prompt matches its delivery to it." }, "tts": { "type": [ "object", "null" ], "properties": { "provider": { "type": "string", "enum": [ "CARTESIA", "ELEVENLABS", "OPENAI", "RIME" ], "description": "Text-to-speech provider, for example ELEVENLABS" }, "voiceId": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The provider's id for the voice" }, "model": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "description": "The provider's voice model, for example eleven_flash_v2_5. Its current one when omitted" } }, "required": [ "provider", "voiceId" ], "description": "Optional provider voice the hosted agent speaks with" }, "stt": { "type": [ "object", "null" ], "properties": { "provider": { "type": "string", "enum": [ "DEEPGRAM", "OPENAI_WHISPER", "SPEECHMATICS", "ASSEMBLYAI", "ELEVENLABS" ], "description": "Speech-to-text provider, for example DEEPGRAM" }, "model": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The provider's model id, for example nova-3" } }, "required": [ "provider", "model" ], "description": "Optional transcriber the hosted agent hears with. Roark's default when omitted" }, "llm": { "type": [ "object", "null" ], "properties": { "provider": { "type": "string", "enum": [ "OPENAI", "ANTHROPIC", "GOOGLE", "XAI", "ULTRAVOX", "AWS", "ELEVENLABS" ], "description": "Text model provider, for example OPENAI" }, "model": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The provider's model id, for example gpt-4.1" } }, "required": [ "provider", "model" ], "description": "Optional text model the hosted agent thinks with. Roark's default when omitted" } }, "required": [ "name", "jobDescription" ], "title": "BuildAgentInput", "description": "Input for building a new Roark-hosted agent" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.agent.build({ jobDescription: 'x', name: 'x' });\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.agent.build(\n job_description=\"x\",\n name=\"x\",\n)\nprint(response.data)" } ] } }, "/v1/phone-number": { "get": { "responses": { "200": { "description": "The phone numbers the project owns", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumberResponse" } } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Phone-number", "tags": [ "Phone Number" ], "summary": "List phone numbers", "description": "Returns the phone numbers the project owns, oldest first, with the agent each is assigned to.", "parameters": [ { "in": "query", "name": "agentId", "schema": { "type": "string", "format": "uuid", "description": "Only the numbers assigned to this agent" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst phoneNumbers = await client.phoneNumber.list();\n\nconsole.log(phoneNumbers.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nphone_numbers = client.phone_number.list()\nprint(phone_numbers.data)" } ] }, "post": { "responses": { "201": { "description": "The purchased phone number", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PhoneNumberResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Insufficient credit" }, "example": { "type": "payment_required", "code": "insufficient_credits", "message": "Not enough credit to start this work. Add credit and try again." } } }, "description": "Payment Required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1Phone-number", "tags": [ "Phone Number" ], "summary": "Buy a phone number", "description": "Buys a number from the carrier for this project: the one named by e164, or one Roark picks to match autoPick (trying the next match if the carrier has just sold one). Free inside the plan allowance; past it, the first month of rent is charged now and monthly after that.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePhoneNumberInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst phoneNumber = await client.phoneNumber.create();\n\nconsole.log(phoneNumber.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nphone_number = client.phone_number.create()\nprint(phone_number.data)" } ] } }, "/v1/phone-number/available": { "get": { "responses": { "200": { "description": "Numbers available to buy", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AvailablePhoneNumberResponse" } } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Phone-numberAvailable", "tags": [ "Phone Number" ], "summary": "Search available phone numbers", "description": "Returns US or Canadian numbers the carrier has for sale, local or toll-free, narrowed by area code or by digits the number must contain. When an area code has no numbers, nearby ones are returned flagged bestEffort; an empty list means nothing matched. Buy one with POST /v1/phone-number, or let Roark pick with autoPick.", "parameters": [ { "in": "query", "name": "country", "schema": { "type": "string", "enum": [ "US", "CA" ], "description": "ISO 3166-1 alpha-2 country of the number: US or CA", "example": "US", "default": "US" } }, { "in": "query", "name": "numberType", "schema": { "type": "string", "enum": [ "LOCAL", "TOLL_FREE" ], "description": "LOCAL for a number in an area code, TOLL_FREE for one from the shared US and Canada toll-free pool", "example": "LOCAL", "default": "LOCAL" } }, { "in": "query", "name": "areaCode", "schema": { "type": "string", "pattern": "^\\d{3}$", "description": "Three-digit area code, or a toll-free prefix such as 800. When it has no numbers, nearby ones are returned instead, flagged bestEffort.", "example": "415" } }, { "in": "query", "name": "contains", "schema": { "type": "string", "pattern": "^[0-9A-Za-z*]{1,7}$", "description": "Digits or letters the number must contain (1 to 7, * matches any digit)", "example": "555" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of results (default: 20, max: 100)" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.phoneNumber.listAvailable();\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.phone_number.list_available()\nprint(response.data)" } ] } }, "/v1/phone-number/allowance": { "get": { "responses": { "200": { "description": "The phone number allowance", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PhoneNumberAllowanceResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Phone-numberAllowance", "tags": [ "Phone Number" ], "summary": "Get the phone number allowance", "description": "Returns how many numbers the organization gets for free, how many it holds, what a paid number costs a month, and whether a purchase would be admitted right now.", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.phoneNumber.getAllowance();\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.phone_number.get_allowance()\nprint(response.data)" } ] } }, "/v1/phone-number/{phoneNumberId}": { "put": { "responses": { "200": { "description": "The updated phone number", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PhoneNumberResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1Phone-numberByPhoneNumberId", "tags": [ "Phone Number" ], "summary": "Update a phone number", "description": "Relabels a number or changes which agent it is assigned to. A field left out is untouched; null clears it.", "parameters": [ { "in": "path", "name": "phoneNumberId", "schema": { "type": "string", "format": "uuid", "description": "Phone number ID" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePhoneNumberInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst phoneNumber = await client.phoneNumber.update('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(phoneNumber.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nphone_number = client.phone_number.update(\n phone_number_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(phone_number.data)" } ] }, "delete": { "responses": { "200": { "description": "The number was released", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReleasePhoneNumberResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1Phone-numberByPhoneNumberId", "tags": [ "Phone Number" ], "summary": "Release a phone number", "description": "Gives the number back to the carrier. This cannot be undone: rent stops today and nothing is refunded.", "parameters": [ { "in": "path", "name": "phoneNumberId", "schema": { "type": "string", "format": "uuid", "description": "Phone number ID" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst phoneNumber = await client.phoneNumber.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(phoneNumber.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nphone_number = client.phone_number.delete(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(phone_number.data)" } ] } }, "/v1/call": { "get": { "responses": { "200": { "description": "List of calls", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the call", "example": "550e8400-e29b-41d4-a716-446655440000" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this call belongs to", "example": "660e8400-e29b-41d4-a716-446655440001" }, "title": { "type": [ "string", "null" ], "description": "Auto-generated title for the call based on content", "example": "Customer support inquiry" }, "summary": { "type": [ "string", "null" ], "description": "Auto-generated summary of the call conversation", "example": "Customer inquired about billing and payment options" }, "status": { "type": [ "string", "null" ], "enum": [ "RINGING", "IN_PROGRESS", "ENDED" ], "description": "Current status of the call", "example": "ENDED" }, "callDirection": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direction of the call (inbound or outbound)", "example": "INBOUND" }, "startedAt": { "type": "string", "description": "Timestamp when the call started", "example": "2024-01-15T10:00:00Z" }, "endedAt": { "type": [ "string", "null" ], "description": "Timestamp when the call ended", "example": "2024-01-15T10:30:00Z" }, "durationMs": { "type": [ "number", "null" ], "description": "Duration of the call in milliseconds", "example": 1800000 }, "endedStatus": { "type": [ "string", "null" ], "enum": [ "PARTICIPANTS_DID_NOT_SPEAK", "AGENT_DID_NOT_ANSWER", "AGENT_DID_NOT_SPEAK", "AGENT_STOPPED_SPEAKING", "AGENT_ENDED_CALL", "AGENT_SAID_END_CALL_PHRASE", "AGENT_TRANSFERRED_CALL", "AGENT_BUSY", "AGENT_ERROR", "CUSTOMER_ENDED_CALL", "VOICE_MAIL_REACHED", "SILENCE_TIME_OUT", "PHONE_CALL_PROVIDER_CONNECTION_ERROR", "CUSTOMER_DID_NOT_ANSWER", "CUSTOMER_DID_NOT_SPEAK", "CUSTOMER_STOPPED_SPEAKING", "CUSTOMER_BUSY", "DIAL_ERROR", "MAX_DURATION_REACHED", "UNKNOWN" ], "description": "Status indicating how the call ended", "example": "AGENT_ENDED_CALL" }, "recordingUrl": { "type": [ "string", "null" ], "description": "Pre-signed URL to the call recording (expires in 1 hour)", "example": "https://s3.amazonaws.com/bucket/recording.mp3?..." }, "recordingUrlAccess": { "type": "string", "enum": [ "AVAILABLE", "NOT_AVAILABLE", "RESTRICTED" ], "description": "Indicates the status of `recordingUrl`. `AVAILABLE`: signed URL returned. `NOT_AVAILABLE`: no recording on file yet (e.g. still processing). `RESTRICTED`: the calling API key does not have the `recording:read` permission and the URL has been withheld.", "example": "AVAILABLE" }, "simulationJobId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the simulation job if this call was generated by a simulation", "example": "880e8400-e29b-41d4-a716-446655440003" }, "supersededByCallId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the call that superseded this one (if applicable)", "example": "990e8400-e29b-41d4-a716-446655440004" }, "externalId": { "type": [ "string", "null" ], "description": "Caller-supplied correlation ID echoed back from the create request, if any was provided", "example": "session-abc-123" }, "agents": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agentVersionId": { "type": [ "string", "null" ], "format": "uuid", "description": "For an agent hosted on Roark, the version of it that handled the call" }, "endpoint": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "environment": { "type": "string" }, "phoneNumberE164": { "type": [ "string", "null" ] } }, "required": [ "id", "environment" ] } }, "required": [ "id" ] }, "description": "Agent information", "example": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "endpoint": { "id": "550e8400-e29b-41d4-a716-446655440000", "environment": "Production", "phoneNumberE164": "+1234567890" } } ] }, "customers": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "phoneNumberE164": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] } } }, "description": "Customer information", "example": [ { "phoneNumberE164": "+1234567891", "label": "customer-01" } ] }, "createdAt": { "type": [ "string", "null" ], "description": "Timestamp when the call record was created", "example": "2024-01-15T10:31:00Z" }, "updatedAt": { "type": [ "string", "null" ], "description": "Timestamp when the call record was last updated", "example": "2024-01-15T10:31:00Z" }, "properties": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Custom properties associated with the call", "example": { "ticketId": "TCK-123", "department": "sales" } }, "policyIds": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "IDs of metric policies that have been applied to this call", "example": [ "550e8400-e29b-41d4-a716-446655440000" ] } }, "required": [ "id", "projectId", "callDirection", "startedAt", "recordingUrlAccess" ], "title": "CallResponse", "description": "Response containing call information" } }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of items" }, "hasMore": { "type": "boolean", "description": "Whether there are more items to fetch" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page of items" } }, "required": [ "total", "hasMore", "nextCursor" ] } }, "required": [ "data", "pagination" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Call", "tags": [ "Call" ], "summary": "List calls", "description": "Returns a paginated list of calls for the authenticated project.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of calls to return (default: 20, max: 100)", "example": 20 } }, { "in": "query", "name": "after", "schema": { "type": "string", "description": "Cursor for pagination - use the nextCursor value from a previous response", "example": "eyJzb3J0VmFsdWUiOiIyMDI1LTAxLTE1VDEwOjAwOjAwLjAwMDAwMFoiLCJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9" } }, { "in": "query", "name": "sortBy", "schema": { "type": "string", "enum": [ "createdAt", "startedAt", "endedAt", "duration", "title", "status" ], "default": "createdAt", "description": "Field to sort by (default: createdAt)", "example": "createdAt" } }, { "in": "query", "name": "sortDirection", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction (default: desc)", "example": "desc" } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "RINGING", "IN_PROGRESS", "ENDED" ], "description": "Filter by call status", "example": "ENDED" } }, { "in": "query", "name": "searchText", "schema": { "type": "string", "description": "Search text to filter calls by title, summary, or transcript", "example": "billing inquiry" } }, { "in": "query", "name": "simulationRunPlanJobId", "schema": { "type": "string", "format": "uuid", "description": "Filter by simulation run plan job ID to get all calls from a specific simulation batch", "example": "550e8400-e29b-41d4-a716-446655440000" } }, { "in": "query", "name": "simulationRunPlanJobIds", "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(,[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})*$", "description": "Calls from any of these simulation runs (run plan job ids), comma-separated, at most 100", "example": "550e8400-e29b-41d4-a716-446655440000,660e8400-e29b-41d4-a716-446655440001" } }, { "in": "query", "name": "simulationRunPlanIds", "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(,[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})*$", "description": "Calls from every run of any of these run plans, comma-separated, at most 100", "example": "770e8400-e29b-41d4-a716-446655440002" } }, { "in": "query", "name": "countedInResults", "schema": { "type": "string", "enum": [ "true", "false" ], "description": "true: only simulated calls their run's results count (not invalidated, for example because the agent never spoke). false: only the simulated calls the results leave out, each invalidated. Live calls, and calls removed from their run, match neither.", "example": "true" } }, { "in": "query", "name": "excludeHiddenRuns", "schema": { "type": "string", "enum": [ "true", "false" ], "description": "true: leave out calls from runs hidden from the runs list. Live calls stay in. false is the same as leaving it out.", "example": "true" } }, { "in": "query", "name": "properties", "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": { "exists": { "type": "boolean", "description": "true: the property is set. false: the property is missing." } }, "additionalProperties": false }, "description": "Filter on custom properties, one entry per property name: properties[][exists]=true keeps calls that have the property set (whatever the value), properties[][exists]=false keeps calls missing it (never sent, sent as null, or removed). A property the project has never seen is missing on every call. Names match the way properties are stored, so planTier and plan_tier are one property. At most 20 properties; a name taken by a built-in call filter, such as status, is rejected with 400.", "example": { "plan_tier": { "exists": false }, "region": { "exists": true } } }, "style": "deepObject", "explode": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst calls = await client.call.list();\n\nconsole.log(calls.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\ncalls = client.call.list()\nprint(calls.data)" } ] }, "post": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the call", "example": "550e8400-e29b-41d4-a716-446655440000" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this call belongs to", "example": "660e8400-e29b-41d4-a716-446655440001" }, "status": { "type": [ "string", "null" ], "enum": [ "RINGING", "IN_PROGRESS", "ENDED" ] }, "callDirection": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direction of the call (inbound or outbound)", "example": "INBOUND" }, "startedAt": { "type": "string", "description": "Timestamp when the call started", "example": "2024-01-15T10:00:00Z" }, "agents": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agentVersionId": { "type": [ "string", "null" ], "format": "uuid", "description": "For an agent hosted on Roark, the version of it that handled the call" }, "endpoint": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "environment": { "type": "string" }, "phoneNumberE164": { "type": [ "string", "null" ] } }, "required": [ "id", "environment" ] } }, "required": [ "id" ] } }, "customers": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "phoneNumberE164": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] } } } }, "createdAt": { "type": [ "string", "null" ] }, "externalId": { "type": [ "string", "null" ] } }, "required": [ "id", "projectId", "status", "callDirection", "startedAt", "agents", "customers", "createdAt", "externalId" ], "title": "CallCreateResponse", "description": "Response after creating a call" } }, "required": [ "data" ] } } }, "description": "Call created successfully" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Insufficient credit" }, "example": { "type": "payment_required", "code": "insufficient_credits", "message": "Not enough credit to start this work. Add credit and try again." } } }, "description": "Payment Required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1Call", "tags": [ "Call" ], "summary": "Create a call", "description": "Create a new call with recording, transcript, agents, and customers", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallCreate" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst call = await client.call.create({\n callDirection: 'INBOUND',\n interfaceType: 'PHONE',\n recordingUrl: 'https://example.com',\n startedAt: 'startedAt',\n});\n\nconsole.log(call.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\ncall = client.call.create(\n call_direction=\"INBOUND\",\n interface_type=\"PHONE\",\n recording_url=\"https://example.com\",\n started_at=\"startedAt\",\n)\nprint(call.data)" } ] } }, "/v1/call/{callId}": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the call", "example": "550e8400-e29b-41d4-a716-446655440000" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this call belongs to", "example": "660e8400-e29b-41d4-a716-446655440001" }, "title": { "type": [ "string", "null" ], "description": "Auto-generated title for the call based on content", "example": "Customer support inquiry" }, "summary": { "type": [ "string", "null" ], "description": "Auto-generated summary of the call conversation", "example": "Customer inquired about billing and payment options" }, "status": { "type": [ "string", "null" ], "enum": [ "RINGING", "IN_PROGRESS", "ENDED" ], "description": "Current status of the call", "example": "ENDED" }, "callDirection": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direction of the call (inbound or outbound)", "example": "INBOUND" }, "startedAt": { "type": "string", "description": "Timestamp when the call started", "example": "2024-01-15T10:00:00Z" }, "endedAt": { "type": [ "string", "null" ], "description": "Timestamp when the call ended", "example": "2024-01-15T10:30:00Z" }, "durationMs": { "type": [ "number", "null" ], "description": "Duration of the call in milliseconds", "example": 1800000 }, "endedStatus": { "type": [ "string", "null" ], "enum": [ "PARTICIPANTS_DID_NOT_SPEAK", "AGENT_DID_NOT_ANSWER", "AGENT_DID_NOT_SPEAK", "AGENT_STOPPED_SPEAKING", "AGENT_ENDED_CALL", "AGENT_SAID_END_CALL_PHRASE", "AGENT_TRANSFERRED_CALL", "AGENT_BUSY", "AGENT_ERROR", "CUSTOMER_ENDED_CALL", "VOICE_MAIL_REACHED", "SILENCE_TIME_OUT", "PHONE_CALL_PROVIDER_CONNECTION_ERROR", "CUSTOMER_DID_NOT_ANSWER", "CUSTOMER_DID_NOT_SPEAK", "CUSTOMER_STOPPED_SPEAKING", "CUSTOMER_BUSY", "DIAL_ERROR", "MAX_DURATION_REACHED", "UNKNOWN" ], "description": "Status indicating how the call ended", "example": "AGENT_ENDED_CALL" }, "recordingUrl": { "type": [ "string", "null" ], "description": "Pre-signed URL to the call recording (expires in 1 hour)", "example": "https://s3.amazonaws.com/bucket/recording.mp3?..." }, "recordingUrlAccess": { "type": "string", "enum": [ "AVAILABLE", "NOT_AVAILABLE", "RESTRICTED" ], "description": "Indicates the status of `recordingUrl`. `AVAILABLE`: signed URL returned. `NOT_AVAILABLE`: no recording on file yet (e.g. still processing). `RESTRICTED`: the calling API key does not have the `recording:read` permission and the URL has been withheld.", "example": "AVAILABLE" }, "simulationJobId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the simulation job if this call was generated by a simulation", "example": "880e8400-e29b-41d4-a716-446655440003" }, "supersededByCallId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the call that superseded this one (if applicable)", "example": "990e8400-e29b-41d4-a716-446655440004" }, "externalId": { "type": [ "string", "null" ], "description": "Caller-supplied correlation ID echoed back from the create request, if any was provided", "example": "session-abc-123" }, "agents": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agentVersionId": { "type": [ "string", "null" ], "format": "uuid", "description": "For an agent hosted on Roark, the version of it that handled the call" }, "endpoint": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "environment": { "type": "string" }, "phoneNumberE164": { "type": [ "string", "null" ] } }, "required": [ "id", "environment" ] } }, "required": [ "id" ] }, "description": "Agent information", "example": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "endpoint": { "id": "550e8400-e29b-41d4-a716-446655440000", "environment": "Production", "phoneNumberE164": "+1234567890" } } ] }, "customers": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "phoneNumberE164": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] } } }, "description": "Customer information", "example": [ { "phoneNumberE164": "+1234567891", "label": "customer-01" } ] }, "createdAt": { "type": [ "string", "null" ], "description": "Timestamp when the call record was created", "example": "2024-01-15T10:31:00Z" }, "updatedAt": { "type": [ "string", "null" ], "description": "Timestamp when the call record was last updated", "example": "2024-01-15T10:31:00Z" }, "properties": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Custom properties associated with the call", "example": { "ticketId": "TCK-123", "department": "sales" } }, "policyIds": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "IDs of metric policies that have been applied to this call", "example": [ "550e8400-e29b-41d4-a716-446655440000" ] } }, "required": [ "id", "projectId", "callDirection", "startedAt", "recordingUrlAccess" ], "title": "CallResponse", "description": "Response containing call information" } }, "required": [ "data" ] } } }, "description": "Call retrieved successfully" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Call not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1CallByCallId", "tags": [ "Call" ], "summary": "Get a call by ID", "description": "Retrieve an existing call by its unique identifier", "parameters": [ { "in": "path", "name": "callId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.call.getByID('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.call.get_by_id(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] }, "delete": { "responses": { "200": { "description": "The call was deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the deleted call" }, "deleted": { "type": "boolean", "const": true, "description": "Always true when the call was deleted" } }, "required": [ "id", "deleted" ], "title": "DeleteCallResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Call not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1CallByCallId", "tags": [ "Call" ], "summary": "Delete a call", "description": "Deletes a call by its ID. The call, its metrics and its analysis are hidden from every read, and any analysis still running on it is cancelled. Returns 404 when the call does not exist in this project or was already deleted.", "parameters": [ { "in": "path", "name": "callId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst call = await client.call.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(call.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\ncall = client.call.delete(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(call.data)" } ] } }, "/v1/call/batch-delete": { "post": { "responses": { "200": { "description": "The calls that were deleted and the ones that were not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deletedCallIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Calls this request deleted", "example": [ "550e8400-e29b-41d4-a716-446655440000" ] }, "notFoundCallIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Requested calls that were not deleted because they do not exist in this project or were already deleted", "example": [ "660e8400-e29b-41d4-a716-446655440001" ] } }, "required": [ "deletedCallIds", "notFoundCallIds" ], "title": "BatchDeleteCallsResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1CallBatch-delete", "tags": [ "Call" ], "summary": "Delete calls in batch", "description": "Deletes up to 100 calls by ID in one request. Each deleted call, its metrics and its analysis are hidden from every read, and any analysis still running on it is cancelled. IDs that do not exist in this project, or were already deleted, are returned in notFoundCallIds and left untouched. The request succeeds even when none of the calls are found. IDs are returned lowercase, each once.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "callIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "description": "IDs of the calls to delete, at most 100. Repeated IDs are counted once.", "example": [ "550e8400-e29b-41d4-a716-446655440000", "660e8400-e29b-41d4-a716-446655440001" ] } }, "required": [ "callIds" ], "title": "BatchDeleteCallsRequest" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.call.batchDelete({\n callIds: ['550e8400-e29b-41d4-a716-446655440000', '660e8400-e29b-41d4-a716-446655440001'],\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.call.batch_delete(\n call_ids=[\"550e8400-e29b-41d4-a716-446655440000\", \"660e8400-e29b-41d4-a716-446655440001\"],\n)\nprint(response.data)" } ] } }, "/v1/call/{callId}/sentiment-run": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the sentiment run" }, "averageSentiment": { "type": "number", "description": "Average sentiment score between 0-1 of the call" }, "averageCategoricalSentiment": { "type": "string", "description": "NEUTRAL / NEGATIVE / POSITIVE" }, "commonEmotion": { "type": "string", "description": "Common emotion of the call" } }, "required": [ "status" ], "description": "Sentiment run response payload" } }, "required": [ "data" ] } } }, "description": "Sentiment analysis for a specific call" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1CallByCallIdSentiment-run", "tags": [ "Call" ], "summary": "List call sentiment runs", "description": "Fetch detailed sentiment analysis results for a specific call, including emotional tone, key phrases, and sentiment scores.", "parameters": [ { "in": "path", "name": "callId", "schema": { "type": "string", "format": "uuid", "description": "ID of the call to fetch sentiment run for" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.call.listSentimentRuns('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.call.list_sentiment_runs(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] } }, "/v1/call/{callId}/metrics": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "metricDefinitionId": { "type": "string", "format": "uuid", "description": "Unique identifier for the metric definition" }, "slug": { "type": "string", "description": "Stable metric slug" }, "metricId": { "type": "string", "description": "Alias of `slug` retained for backwards compatibility. Same value as `slug`." }, "name": { "type": "string", "description": "Name of the metric" }, "description": { "type": "string", "description": "Description of what the metric measures" }, "type": { "type": "string", "enum": [ "COUNT", "NUMERIC", "BOOLEAN", "SCALE", "TEXT", "CLASSIFICATION", "OFFSET" ], "description": "Type of value this metric produces" }, "scope": { "type": "string", "enum": [ "GLOBAL", "PER_PARTICIPANT" ], "description": "Whether metric is global or per-participant" }, "unit": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the unit" }, "symbol": { "type": [ "string", "null" ], "description": "Symbol for the unit" } }, "required": [ "name", "symbol" ], "description": "Unit information if applicable" }, "values": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "boolean" }, { "type": "string" } ], "description": "The metric value (type depends on outputType). Present only on SUCCESS rows; omitted for NOT_APPLICABLE / DATA_MISSING / ERROR." }, "callId": { "type": "string", "format": "uuid", "description": "ID of the call this value was computed on. Only set when the response spans multiple conversations (e.g. job-scoped metric values)." }, "chatId": { "type": "string", "format": "uuid", "description": "ID of the chat this value was computed on. Only set when the response spans multiple conversations (e.g. job-scoped metric values)." }, "captureStatus": { "type": "string", "enum": [ "SUCCESS", "NOT_APPLICABLE", "DATA_MISSING", "ERROR" ], "description": "Result state of this metric computation. SUCCESS carries a real `value`; NOT_APPLICABLE / DATA_MISSING / ERROR do not (the `value` field is omitted). Non-SUCCESS rows only appear when the request includes ?status=all." }, "errorMessage": { "type": "string", "description": "Error detail when captureStatus is ERROR — e.g. provider down, LLM timeout. Undefined for other statuses." }, "context": { "type": "string", "enum": [ "CALL", "SEGMENT", "SEGMENT_RANGE" ], "description": "Context level: CALL (entire conversation), SEGMENT (single segment), SEGMENT_RANGE (between/across segments)" }, "participantRole": { "type": "string", "enum": [ "agent", "customer" ], "description": "Role of participant (only for PER_PARTICIPANT metrics)" }, "valueReasoning": { "type": "string", "description": "Explanation for the metric value (especially useful for AI-computed metrics)" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Confidence score (0-1) for the computed value. Defaults to 1.0 for deterministic metrics. Omitted on non-SUCCESS rows." }, "computedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the metric was computed" }, "policyIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs of metric policies that triggered this metric computation" }, "segment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Segment information (for SEGMENT context metrics)" }, "fromSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Starting segment information (for SEGMENT_RANGE context metrics)" }, "toSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Ending segment information (for SEGMENT_RANGE context metrics)" }, "evidenceSpans": { "type": "array", "items": { "type": "object", "properties": { "fromSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "First segment of the span" }, "toSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Last segment of the span (the same as fromSegment for one line)" }, "reason": { "type": "string", "description": "The judge's one-line account of what happens here" } }, "required": [ "fromSegment", "toSegment" ] }, "description": "For CALL-context values of LLM judge metrics that cited where their evidence is: the transcript spans that decided the value, most decisive first. Omitted otherwise." } }, "required": [ "captureStatus", "context", "computedAt" ], "title": "Standard metric value", "description": "A metric value entry. Applies to every metric." }, { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "boolean" }, { "type": "string" } ], "description": "The metric value (type depends on outputType). Present only on SUCCESS rows; omitted for NOT_APPLICABLE / DATA_MISSING / ERROR." }, "callId": { "type": "string", "format": "uuid", "description": "ID of the call this value was computed on. Only set when the response spans multiple conversations (e.g. job-scoped metric values)." }, "chatId": { "type": "string", "format": "uuid", "description": "ID of the chat this value was computed on. Only set when the response spans multiple conversations (e.g. job-scoped metric values)." }, "captureStatus": { "type": "string", "enum": [ "SUCCESS", "NOT_APPLICABLE", "DATA_MISSING", "ERROR" ], "description": "Result state of this metric computation. SUCCESS carries a real `value`; NOT_APPLICABLE / DATA_MISSING / ERROR do not (the `value` field is omitted). Non-SUCCESS rows only appear when the request includes ?status=all." }, "errorMessage": { "type": "string", "description": "Error detail when captureStatus is ERROR — e.g. provider down, LLM timeout. Undefined for other statuses." }, "context": { "type": "string", "enum": [ "CALL", "SEGMENT", "SEGMENT_RANGE" ], "description": "Context level: CALL (entire conversation), SEGMENT (single segment), SEGMENT_RANGE (between/across segments)" }, "participantRole": { "type": "string", "enum": [ "agent", "customer" ], "description": "Role of participant (only for PER_PARTICIPANT metrics)" }, "valueReasoning": { "type": "string", "description": "Explanation for the metric value (especially useful for AI-computed metrics)" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Confidence score (0-1) for the computed value. Defaults to 1.0 for deterministic metrics. Omitted on non-SUCCESS rows." }, "computedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the metric was computed" }, "policyIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs of metric policies that triggered this metric computation" }, "segment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Segment information (for SEGMENT context metrics)" }, "fromSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Starting segment information (for SEGMENT_RANGE context metrics)" }, "toSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Ending segment information (for SEGMENT_RANGE context metrics)" }, "evidenceSpans": { "type": "array", "items": { "type": "object", "properties": { "fromSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "First segment of the span" }, "toSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Last segment of the span (the same as fromSegment for one line)" }, "reason": { "type": "string", "description": "The judge's one-line account of what happens here" } }, "required": [ "fromSegment", "toSegment" ] }, "description": "For CALL-context values of LLM judge metrics that cited where their evidence is: the transcript spans that decided the value, most decisive first. Omitted otherwise." }, "propertyVerdicts": { "type": "array", "items": { "type": "object", "properties": { "propertyName": { "type": "string", "description": "The call property checked, as sent at ingest" }, "expectedValue": { "type": "string", "description": "The value supplied at ingest, frozen at scoring time" }, "observedValue": { "type": "string", "description": "What the transcript said instead. Only present when verdict is MISMATCH." }, "verdict": { "type": "string", "enum": [ "MATCH", "MISMATCH", "TRANSCRIPTION_ERROR", "NOT_MENTIONED" ], "description": "How this property resolved against the transcript. NOT_MENTIONED means the subject never came up and is not a mismatch." }, "reasoning": { "type": "string", "description": "Judge reasoning for this verdict" }, "segment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "The transcript segment this property was referred to in: the conflicting value for MISMATCH, the confirming reference for MATCH. Omitted for NOT_MENTIONED and when the verdict could not be anchored." } }, "required": [ "propertyName", "expectedValue", "verdict" ] }, "description": "Per-property verdicts for the Property Mismatch metric, in the order the properties were checked. Omitted for every other metric." } }, "required": [ "captureStatus", "context", "computedAt" ], "title": "Property verification metric value", "description": "Returned for the Property Mismatch metric (`property_transcript_mismatch`): the standard entry plus the per-property verdict breakdown." } ] }, "description": "Array of metric values (multiple for PER_PARTICIPANT metrics, or multiple segments/turns)" } }, "required": [ "metricDefinitionId", "slug", "metricId", "name", "description", "type", "scope", "values" ], "description": "Metric data grouped by metric definition" }, "description": "Conversation metrics response payload grouped by metric definition" } }, "required": [ "data" ] } } }, "description": "Call-level metrics for a specific call" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1CallByCallIdMetrics", "tags": [ "Call" ], "summary": "List call metrics", "description": "Fetch all call-level metrics for a specific call, including both system-generated and custom metrics. Only returns rows from the **latest** metric-collection job per metric — if the same metric has been recomputed, prior runs are excluded and remain in the metric history. By default returns only successfully computed metrics; pass `?status=all` to also include rows that resolved as NOT_APPLICABLE / DATA_MISSING / ERROR (the `value` field is omitted on those entries — check `captureStatus`).", "parameters": [ { "in": "query", "name": "flatten", "schema": { "type": "string", "description": "Whether to return a flat list instead of grouped by metric definition (default: false)" } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "success", "all" ], "default": "success", "description": "Filter metrics by capture status. `success` (default) returns only successfully computed metrics — backwards-compatible with the historical behavior. `all` also returns NOT_APPLICABLE / DATA_MISSING / ERROR rows (with `value` omitted), so clients can distinguish \"still computing\" from \"computed but no value\" and exit retry loops correctly." } }, { "schema": { "type": "string" }, "in": "path", "name": "callId", "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.call.listMetrics('callId');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.call.list_metrics(\n call_id=\"callId\",\n)\nprint(response.data)" } ] } }, "/v1/call/{callId}/transcript": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "transcriptionSource": { "type": [ "string", "null" ], "enum": [ "ROARK_POST_CALL", "SIMULATION_AGENT_REALTIME", "CUSTOMER_AGENT_REALTIME" ], "description": "The transcription source used for this transcript. Null if no transcript is available." }, "participants": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation participant ID" }, "type": { "type": "string", "const": "AGENT" }, "agentId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the agent entity" } }, "required": [ "id", "type", "agentId" ], "description": "An agent participant" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation participant ID" }, "type": { "type": "string", "const": "CUSTOMER" }, "customerId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the conversation customer record" } }, "required": [ "id", "type", "customerId" ], "description": "A customer participant" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation participant ID" }, "type": { "type": "string", "const": "SIMULATED_CUSTOMER" }, "customerId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the conversation customer record" } }, "required": [ "id", "type", "customerId" ], "description": "A simulated customer participant" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation participant ID" }, "type": { "type": "string", "const": "BACKGROUND_SPEAKER" } }, "required": [ "id", "type" ], "description": "A background speaker participant" } ], "description": "A participant in the conversation" }, "description": "All participants in this transcript, referenced by participantId on each entry" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "participantId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the conversation participant who produced this entry. References participants[].id." }, "role": { "type": [ "string", "null" ], "enum": [ "AGENT", "CUSTOMER" ], "description": "Convenience role derived from participant type" }, "text": { "type": "string", "description": "Transcript text for this entry" }, "startOffsetMs": { "type": "integer", "minimum": 0, "description": "Start time offset in milliseconds from the start of the conversation" }, "endOffsetMs": { "type": "integer", "minimum": 0, "description": "End time offset in milliseconds from the start of the conversation" } }, "required": [ "participantId", "role", "text", "startOffsetMs", "endOffsetMs" ], "description": "A single transcript entry" }, "description": "Ordered list of transcript entries from the call" } }, "required": [ "transcriptionSource", "participants", "entries" ], "description": "Call transcript response" } }, "required": [ "data" ] } } }, "description": "Transcript for the specified call" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1CallByCallIdTranscript", "tags": [ "Call" ], "summary": "Get call transcript", "description": "Fetch the full transcript for a specific call. Optionally specify a transcription source; otherwise the best available source is used automatically.", "parameters": [ { "in": "query", "name": "source", "schema": { "type": "string", "enum": [ "ROARK_POST_CALL", "SIMULATION_AGENT_REALTIME", "CUSTOMER_AGENT_REALTIME" ], "description": "Transcription source to fetch. When omitted, uses the preferred source based on availability: CUSTOMER_AGENT_REALTIME > SIMULATION_AGENT_REALTIME > ROARK_POST_CALL" } }, { "schema": { "type": "string" }, "in": "path", "name": "callId", "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.call.getTranscript('callId');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.call.get_transcript(\n call_id=\"callId\",\n)\nprint(response.data)" } ] } }, "/v1/call/{callId}/tool-invocations": { "post": { "responses": { "200": { "description": "Tool invocations attached to the call", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AppendToolInvocationsResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Insufficient credit" }, "example": { "type": "payment_required", "code": "insufficient_credits", "message": "Not enough credit to start this work. Add credit and try again." } } }, "description": "Payment Required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1CallByCallIdTool-invocations", "tags": [ "Call" ], "summary": "Append tool invocations to a call", "description": "Attach tool invocations that fired during a call to an already-existing call, asynchronously after the call was created. Use this when the tool-call data becomes available later than the call itself (e.g. a Roark simulation, or a call submitted via POST /v1/call before its tools were ready). Writes are idempotent: re-sending an invocation already present on the call (same tool name and timing) is skipped, so retries converge instead of double-counting. Optionally pass `metrics` to (re)score metrics over the newly attached tools, which triggers a billed metric collection job and requires the `metric:create` permission.", "parameters": [ { "in": "path", "name": "callId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendToolInvocationsRequest" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.call.appendToolInvocations('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n toolInvocations: [\n { name: 'name', parameters: { foo: 'string' }, result: 'string', startOffsetMs: 0 },\n ],\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.call.append_tool_invocations(\n call_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n tool_invocations=[{\n \"name\": \"name\",\n \"parameters\": {\n \"foo\": \"string\",\n },\n \"result\": \"string\",\n \"start_offset_ms\": 0,\n }],\n)\nprint(response.data)" } ] } }, "/v1/call/{callId}/properties": { "patch": { "responses": { "200": { "description": "Properties updated on the call", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UpdateCallPropertiesResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "patchV1CallByCallIdProperties", "tags": [ "Call" ], "summary": "Update the properties of a call", "description": "Add, overwrite or remove custom properties on an already-existing call. Use this for data that becomes available after the call was created, e.g. an outcome your system validates a few minutes later. Merge semantics: a value adds or overwrites the property, null removes it, and properties left out are untouched. The patch is applied whole or not at all: a property Roark sets itself, or a value whose type differs from the type the project already stores that property as, rejects the request with a 400 and nothing is written. A 409 means another request created one of the properties with a different value type at the same moment; nothing was written. Optionally pass `metrics` to (re)score metrics over the updated properties, which triggers a billed metric collection job and requires the `metric:create` permission.", "parameters": [ { "in": "path", "name": "callId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCallPropertiesRequest" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.call.updateProperties('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n properties: { partner_outcome: 'apr_returned', delivered_apr: '21.99' },\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.call.update_properties(\n call_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n properties={\n \"delivered_apr\": \"21.99\",\n \"partner_outcome\": \"apr_returned\",\n },\n)\nprint(response.data)" } ] } }, "/v1/call/{callId}/cost": { "get": { "responses": { "200": { "description": "The call’s cost", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CallCost" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Call not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1CallByCallIdCost", "tags": [ "Call" ], "summary": "Get call cost", "description": "The billable spend attributed to one call, split by cost type, with every cost line behind it. Simulated calls include the costs their simulation incurred before the call connected. Amounts are billable spend only, in exact micro-dollars (`*UsdMicros`) and dollars (`*Usd`, for display). Requires an API key with the `billing:read` permission.", "parameters": [ { "in": "path", "name": "callId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.call.getCost('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.call.get_cost(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] } }, "/v1/chat": { "get": { "responses": { "200": { "description": "List of chats", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the chat", "example": "550e8400-e29b-41d4-a716-446655440000" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this chat belongs to", "example": "660e8400-e29b-41d4-a716-446655440001" }, "organizationId": { "type": "string", "format": "uuid", "description": "ID of the organization this chat belongs to", "example": "770e8400-e29b-41d4-a716-446655440002" }, "title": { "type": [ "string", "null" ], "description": "Auto-generated title for the chat based on content", "example": "Account assistance request" }, "summary": { "type": [ "string", "null" ], "description": "Auto-generated summary of the chat conversation", "example": "Customer inquired about account balance and recent transactions" }, "startTimestamp": { "type": "string", "description": "Timestamp when the chat started", "example": "2024-01-15T10:00:00Z" }, "endTimestamp": { "type": "string", "description": "Timestamp when the chat ended", "example": "2024-01-15T10:30:00Z" }, "durationMs": { "type": "number", "description": "Duration of the chat in milliseconds", "example": 1800000 }, "createdAt": { "type": [ "string", "null" ], "description": "Timestamp when the chat record was created", "example": "2024-01-15T10:31:00Z" }, "updatedAt": { "type": [ "string", "null" ], "description": "Timestamp when the chat record was last updated", "example": "2024-01-15T10:31:00Z" }, "simulationJobId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the simulation job if this chat was generated by a simulation", "example": "880e8400-e29b-41d4-a716-446655440003" }, "simulationRunPlanJobId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the simulation run plan job that this chat belongs to (if applicable)", "example": "990e8400-e29b-41d4-a716-446655440004" }, "agents": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "description": "Agent information", "example": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ] }, "customers": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "phoneNumberE164": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] } } }, "description": "Customer information", "example": [ { "phoneNumberE164": null, "label": "web-visitor-abc123" } ] }, "properties": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Custom properties associated with the chat", "example": { "source": "web", "region": "US" } }, "policyIds": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "IDs of metric policies that have been applied to this chat", "example": [ "550e8400-e29b-41d4-a716-446655440000" ] }, "externalId": { "type": [ "string", "null" ], "description": "Caller-supplied correlation ID echoed back from the create request, if any was provided", "example": "session-abc-123" } }, "required": [ "id", "projectId", "organizationId", "startTimestamp", "endTimestamp", "durationMs" ], "title": "ChatResponse", "description": "Response containing the chat information" } }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of items" }, "hasMore": { "type": "boolean", "description": "Whether there are more items to fetch" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page of items" } }, "required": [ "total", "hasMore", "nextCursor" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Chat", "tags": [ "Chat" ], "summary": "List chats", "description": "Returns a paginated list of chats for the authenticated project.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of chats to return (default: 20, max: 100)", "example": 20 } }, { "in": "query", "name": "after", "schema": { "type": "string", "description": "Cursor for pagination - use the nextCursor value from a previous response", "example": "eyJzb3J0VmFsdWUiOiIyMDI1LTAxLTE1VDEwOjAwOjAwLjAwMDAwMFoiLCJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9" } }, { "in": "query", "name": "sortBy", "schema": { "type": "string", "enum": [ "createdAt", "startTimestamp", "endTimestamp", "duration", "title" ], "default": "createdAt", "description": "Field to sort by (default: createdAt)", "example": "createdAt" } }, { "in": "query", "name": "sortDirection", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction (default: desc)", "example": "desc" } }, { "in": "query", "name": "searchText", "schema": { "type": "string", "description": "Search text to filter chats by id, title, summary, message text, or note content", "example": "account balance" } }, { "in": "query", "name": "simulationRunPlanJobId", "schema": { "type": "string", "format": "uuid", "description": "Filter by simulation run plan job ID to get all chats from a specific simulation batch", "example": "550e8400-e29b-41d4-a716-446655440000" } } ] }, "post": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the chat", "example": "550e8400-e29b-41d4-a716-446655440000" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this chat belongs to", "example": "660e8400-e29b-41d4-a716-446655440001" }, "organizationId": { "type": "string", "format": "uuid", "description": "ID of the organization this chat belongs to", "example": "770e8400-e29b-41d4-a716-446655440002" }, "title": { "type": [ "string", "null" ], "description": "Auto-generated title for the chat based on content", "example": "Account assistance request" }, "summary": { "type": [ "string", "null" ], "description": "Auto-generated summary of the chat conversation", "example": "Customer inquired about account balance and recent transactions" }, "startTimestamp": { "type": "string", "description": "Timestamp when the chat started", "example": "2024-01-15T10:00:00Z" }, "endTimestamp": { "type": "string", "description": "Timestamp when the chat ended", "example": "2024-01-15T10:30:00Z" }, "durationMs": { "type": "number", "description": "Duration of the chat in milliseconds", "example": 1800000 }, "createdAt": { "type": [ "string", "null" ], "description": "Timestamp when the chat record was created", "example": "2024-01-15T10:31:00Z" }, "updatedAt": { "type": [ "string", "null" ], "description": "Timestamp when the chat record was last updated", "example": "2024-01-15T10:31:00Z" }, "simulationJobId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the simulation job if this chat was generated by a simulation", "example": "880e8400-e29b-41d4-a716-446655440003" }, "simulationRunPlanJobId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the simulation run plan job that this chat belongs to (if applicable)", "example": "990e8400-e29b-41d4-a716-446655440004" }, "agents": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "description": "Agent information", "example": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ] }, "customers": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "phoneNumberE164": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] } } }, "description": "Customer information", "example": [ { "phoneNumberE164": null, "label": "web-visitor-abc123" } ] }, "properties": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Custom properties associated with the chat", "example": { "source": "web", "region": "US" } }, "policyIds": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "IDs of metric policies that have been applied to this chat", "example": [ "550e8400-e29b-41d4-a716-446655440000" ] }, "externalId": { "type": [ "string", "null" ], "description": "Caller-supplied correlation ID echoed back from the create request, if any was provided", "example": "session-abc-123" } }, "required": [ "id", "projectId", "organizationId", "startTimestamp", "endTimestamp", "durationMs" ], "title": "ChatResponse", "description": "Response containing the chat information" } }, "required": [ "data" ] } } }, "description": "Chat created successfully" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad request - validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Insufficient credit" }, "example": { "type": "payment_required", "code": "insufficient_credits", "message": "Not enough credit to start this work. Add credit and try again." } } }, "description": "Payment Required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1Chat", "tags": [ "Chat" ], "summary": "Create a chat", "description": "Create a new chat with segments (messages and tool invocations)", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCreate" } } } } } }, "/v1/chat/{id}": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the chat", "example": "550e8400-e29b-41d4-a716-446655440000" }, "projectId": { "type": "string", "format": "uuid", "description": "ID of the project this chat belongs to", "example": "660e8400-e29b-41d4-a716-446655440001" }, "organizationId": { "type": "string", "format": "uuid", "description": "ID of the organization this chat belongs to", "example": "770e8400-e29b-41d4-a716-446655440002" }, "title": { "type": [ "string", "null" ], "description": "Auto-generated title for the chat based on content", "example": "Account assistance request" }, "summary": { "type": [ "string", "null" ], "description": "Auto-generated summary of the chat conversation", "example": "Customer inquired about account balance and recent transactions" }, "startTimestamp": { "type": "string", "description": "Timestamp when the chat started", "example": "2024-01-15T10:00:00Z" }, "endTimestamp": { "type": "string", "description": "Timestamp when the chat ended", "example": "2024-01-15T10:30:00Z" }, "durationMs": { "type": "number", "description": "Duration of the chat in milliseconds", "example": 1800000 }, "createdAt": { "type": [ "string", "null" ], "description": "Timestamp when the chat record was created", "example": "2024-01-15T10:31:00Z" }, "updatedAt": { "type": [ "string", "null" ], "description": "Timestamp when the chat record was last updated", "example": "2024-01-15T10:31:00Z" }, "simulationJobId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the simulation job if this chat was generated by a simulation", "example": "880e8400-e29b-41d4-a716-446655440003" }, "simulationRunPlanJobId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the simulation run plan job that this chat belongs to (if applicable)", "example": "990e8400-e29b-41d4-a716-446655440004" }, "agents": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "description": "Agent information", "example": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ] }, "customers": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "phoneNumberE164": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] } } }, "description": "Customer information", "example": [ { "phoneNumberE164": null, "label": "web-visitor-abc123" } ] }, "properties": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Custom properties associated with the chat", "example": { "source": "web", "region": "US" } }, "policyIds": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "IDs of metric policies that have been applied to this chat", "example": [ "550e8400-e29b-41d4-a716-446655440000" ] }, "externalId": { "type": [ "string", "null" ], "description": "Caller-supplied correlation ID echoed back from the create request, if any was provided", "example": "session-abc-123" } }, "required": [ "id", "projectId", "organizationId", "startTimestamp", "endTimestamp", "durationMs" ], "title": "ChatResponse", "description": "Response containing the chat information" } }, "required": [ "data" ] } } }, "description": "Chat retrieved successfully" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Chat not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1ChatById", "tags": [ "Chat" ], "summary": "Get a chat by ID", "description": "Retrieve an existing chat by its unique identifier", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid" }, "required": true } ] } }, "/v1/chat/{id}/transcript": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "participants": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation participant ID" }, "type": { "type": "string", "const": "AGENT" }, "agentId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the agent entity" } }, "required": [ "id", "type", "agentId" ], "description": "An agent participant" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation participant ID" }, "type": { "type": "string", "const": "CUSTOMER" }, "customerId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the conversation customer record" } }, "required": [ "id", "type", "customerId" ], "description": "A customer participant" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation participant ID" }, "type": { "type": "string", "const": "SIMULATED_CUSTOMER" }, "customerId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the conversation customer record" } }, "required": [ "id", "type", "customerId" ], "description": "A simulated customer participant" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation participant ID" }, "type": { "type": "string", "const": "BACKGROUND_SPEAKER" } }, "required": [ "id", "type" ], "description": "A background speaker participant" } ], "description": "A participant in the conversation" }, "description": "All participants in this transcript, referenced by participantId on each entry" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "participantId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the conversation participant who produced this entry. References participants[].id." }, "role": { "type": [ "string", "null" ], "enum": [ "AGENT", "CUSTOMER" ], "description": "Convenience role derived from participant type" }, "text": { "type": "string", "description": "Transcript text for this entry" }, "startOffsetMs": { "type": "integer", "minimum": 0, "description": "Start time offset in milliseconds from the start of the conversation" }, "endOffsetMs": { "type": "integer", "minimum": 0, "description": "End time offset in milliseconds from the start of the conversation" } }, "required": [ "participantId", "role", "text", "startOffsetMs", "endOffsetMs" ], "description": "A single transcript entry" }, "description": "Ordered list of transcript entries from the chat" } }, "required": [ "participants", "entries" ], "description": "Chat transcript response" } }, "required": [ "data" ] } } }, "description": "Transcript for the specified chat" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1ChatByIdTranscript", "tags": [ "Chat" ], "summary": "Get chat transcript", "description": "Fetch the full transcript (messages) for a specific chat.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid", "description": "ID of the chat to fetch transcript for" }, "required": true } ] } }, "/v1/chat/{id}/metrics": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "metricDefinitionId": { "type": "string", "format": "uuid", "description": "Unique identifier for the metric definition" }, "slug": { "type": "string", "description": "Stable metric slug" }, "metricId": { "type": "string", "description": "Alias of `slug` retained for backwards compatibility. Same value as `slug`." }, "name": { "type": "string", "description": "Name of the metric" }, "description": { "type": "string", "description": "Description of what the metric measures" }, "type": { "type": "string", "enum": [ "COUNT", "NUMERIC", "BOOLEAN", "SCALE", "TEXT", "CLASSIFICATION", "OFFSET" ], "description": "Type of value this metric produces" }, "scope": { "type": "string", "enum": [ "GLOBAL", "PER_PARTICIPANT" ], "description": "Whether metric is global or per-participant" }, "unit": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the unit" }, "symbol": { "type": [ "string", "null" ], "description": "Symbol for the unit" } }, "required": [ "name", "symbol" ], "description": "Unit information if applicable" }, "values": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "boolean" }, { "type": "string" } ], "description": "The metric value (type depends on outputType). Present only on SUCCESS rows; omitted for NOT_APPLICABLE / DATA_MISSING / ERROR." }, "callId": { "type": "string", "format": "uuid", "description": "ID of the call this value was computed on. Only set when the response spans multiple conversations (e.g. job-scoped metric values)." }, "chatId": { "type": "string", "format": "uuid", "description": "ID of the chat this value was computed on. Only set when the response spans multiple conversations (e.g. job-scoped metric values)." }, "captureStatus": { "type": "string", "enum": [ "SUCCESS", "NOT_APPLICABLE", "DATA_MISSING", "ERROR" ], "description": "Result state of this metric computation. SUCCESS carries a real `value`; NOT_APPLICABLE / DATA_MISSING / ERROR do not (the `value` field is omitted). Non-SUCCESS rows only appear when the request includes ?status=all." }, "errorMessage": { "type": "string", "description": "Error detail when captureStatus is ERROR — e.g. provider down, LLM timeout. Undefined for other statuses." }, "context": { "type": "string", "enum": [ "CALL", "SEGMENT", "SEGMENT_RANGE" ], "description": "Context level: CALL (entire conversation), SEGMENT (single segment), SEGMENT_RANGE (between/across segments)" }, "participantRole": { "type": "string", "enum": [ "agent", "customer" ], "description": "Role of participant (only for PER_PARTICIPANT metrics)" }, "valueReasoning": { "type": "string", "description": "Explanation for the metric value (especially useful for AI-computed metrics)" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Confidence score (0-1) for the computed value. Defaults to 1.0 for deterministic metrics. Omitted on non-SUCCESS rows." }, "computedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the metric was computed" }, "policyIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs of metric policies that triggered this metric computation" }, "segment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Segment information (for SEGMENT context metrics)" }, "fromSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Starting segment information (for SEGMENT_RANGE context metrics)" }, "toSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Ending segment information (for SEGMENT_RANGE context metrics)" }, "evidenceSpans": { "type": "array", "items": { "type": "object", "properties": { "fromSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "First segment of the span" }, "toSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Last segment of the span (the same as fromSegment for one line)" }, "reason": { "type": "string", "description": "The judge's one-line account of what happens here" } }, "required": [ "fromSegment", "toSegment" ] }, "description": "For CALL-context values of LLM judge metrics that cited where their evidence is: the transcript spans that decided the value, most decisive first. Omitted otherwise." } }, "required": [ "captureStatus", "context", "computedAt" ], "title": "Standard metric value", "description": "A metric value entry. Applies to every metric." }, { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "boolean" }, { "type": "string" } ], "description": "The metric value (type depends on outputType). Present only on SUCCESS rows; omitted for NOT_APPLICABLE / DATA_MISSING / ERROR." }, "callId": { "type": "string", "format": "uuid", "description": "ID of the call this value was computed on. Only set when the response spans multiple conversations (e.g. job-scoped metric values)." }, "chatId": { "type": "string", "format": "uuid", "description": "ID of the chat this value was computed on. Only set when the response spans multiple conversations (e.g. job-scoped metric values)." }, "captureStatus": { "type": "string", "enum": [ "SUCCESS", "NOT_APPLICABLE", "DATA_MISSING", "ERROR" ], "description": "Result state of this metric computation. SUCCESS carries a real `value`; NOT_APPLICABLE / DATA_MISSING / ERROR do not (the `value` field is omitted). Non-SUCCESS rows only appear when the request includes ?status=all." }, "errorMessage": { "type": "string", "description": "Error detail when captureStatus is ERROR — e.g. provider down, LLM timeout. Undefined for other statuses." }, "context": { "type": "string", "enum": [ "CALL", "SEGMENT", "SEGMENT_RANGE" ], "description": "Context level: CALL (entire conversation), SEGMENT (single segment), SEGMENT_RANGE (between/across segments)" }, "participantRole": { "type": "string", "enum": [ "agent", "customer" ], "description": "Role of participant (only for PER_PARTICIPANT metrics)" }, "valueReasoning": { "type": "string", "description": "Explanation for the metric value (especially useful for AI-computed metrics)" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Confidence score (0-1) for the computed value. Defaults to 1.0 for deterministic metrics. Omitted on non-SUCCESS rows." }, "computedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the metric was computed" }, "policyIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs of metric policies that triggered this metric computation" }, "segment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Segment information (for SEGMENT context metrics)" }, "fromSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Starting segment information (for SEGMENT_RANGE context metrics)" }, "toSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Ending segment information (for SEGMENT_RANGE context metrics)" }, "evidenceSpans": { "type": "array", "items": { "type": "object", "properties": { "fromSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "First segment of the span" }, "toSegment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "Last segment of the span (the same as fromSegment for one line)" }, "reason": { "type": "string", "description": "The judge's one-line account of what happens here" } }, "required": [ "fromSegment", "toSegment" ] }, "description": "For CALL-context values of LLM judge metrics that cited where their evidence is: the transcript spans that decided the value, most decisive first. Omitted otherwise." }, "propertyVerdicts": { "type": "array", "items": { "type": "object", "properties": { "propertyName": { "type": "string", "description": "The call property checked, as sent at ingest" }, "expectedValue": { "type": "string", "description": "The value supplied at ingest, frozen at scoring time" }, "observedValue": { "type": "string", "description": "What the transcript said instead. Only present when verdict is MISMATCH." }, "verdict": { "type": "string", "enum": [ "MATCH", "MISMATCH", "TRANSCRIPTION_ERROR", "NOT_MENTIONED" ], "description": "How this property resolved against the transcript. NOT_MENTIONED means the subject never came up and is not a mismatch." }, "reasoning": { "type": "string", "description": "Judge reasoning for this verdict" }, "segment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Segment ID" }, "text": { "type": "string", "description": "Segment text content" }, "startOffsetMs": { "type": "number", "description": "Start time offset in milliseconds" }, "endOffsetMs": { "type": "number", "description": "End time offset in milliseconds" } }, "required": [ "id", "text", "startOffsetMs", "endOffsetMs" ], "description": "The transcript segment this property was referred to in: the conflicting value for MISMATCH, the confirming reference for MATCH. Omitted for NOT_MENTIONED and when the verdict could not be anchored." } }, "required": [ "propertyName", "expectedValue", "verdict" ] }, "description": "Per-property verdicts for the Property Mismatch metric, in the order the properties were checked. Omitted for every other metric." } }, "required": [ "captureStatus", "context", "computedAt" ], "title": "Property verification metric value", "description": "Returned for the Property Mismatch metric (`property_transcript_mismatch`): the standard entry plus the per-property verdict breakdown." } ] }, "description": "Array of metric values (multiple for PER_PARTICIPANT metrics, or multiple segments/turns)" } }, "required": [ "metricDefinitionId", "slug", "metricId", "name", "description", "type", "scope", "values" ], "description": "Metric data grouped by metric definition" }, "description": "Conversation metrics response payload grouped by metric definition" } }, "required": [ "data" ] } } }, "description": "Metrics for a specific chat" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1ChatByIdMetrics", "tags": [ "Chat" ], "summary": "List chat metrics", "description": "Fetch all metrics for a specific chat, including both system-generated and custom metrics. Only returns rows from the **latest** metric-collection job per metric — if the same metric has been recomputed, prior runs are excluded and remain in the metric history. By default returns only successfully computed metrics; pass `?status=all` to also include rows that resolved as NOT_APPLICABLE / DATA_MISSING / ERROR (the `value` field is omitted on those entries — check `captureStatus`).", "parameters": [ { "in": "query", "name": "flatten", "schema": { "type": "string", "description": "Whether to return a flat list instead of grouped by metric definition (default: false)" } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "success", "all" ], "default": "success", "description": "Filter metrics by capture status. `success` (default) returns only successfully computed metrics — backwards-compatible with the historical behavior. `all` also returns NOT_APPLICABLE / DATA_MISSING / ERROR rows (with `value` omitted), so clients can distinguish \"still computing\" from \"computed but no value\" and exit retry loops correctly." } }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/v1/metric/definitions": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMetricDefinitionsResponse" } } }, "description": "Cursor-paginated metric definitions available in the project" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1MetricDefinitions", "tags": [ "Metric" ], "summary": "List metric definitions", "description": "Fetch metric definitions available in the project, including both system-generated and custom metrics. Results are ordered by immutable definition ID; pass `nextCursor` to retrieve the following page.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 500 } }, { "in": "query", "name": "after", "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.metric.listDefinitions();\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.metric.list_definitions()\nprint(response.data)" } ] }, "post": { "responses": { "201": { "description": "The created metric definition", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateMetricDefinitionResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1MetricDefinitions", "tags": [ "Metric" ], "summary": "Create custom metric definition", "description": "Create a new metric definition. The `calculationType` field selects the variant: LLM_JUDGE (LLM-evaluated), FORMULA (computed from a math expression over other metrics), or PATTERN (detects a trigger→outcome pattern within a window). To create a threshold on top of an existing metric, use `POST /metric/definitions/{idOrSlug}/thresholds` instead.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMetricDefinitionInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.metric.createDefinition({\n calculationType: 'LLM_JUDGE',\n name: 'Customer Satisfaction',\n outputType: 'BOOLEAN',\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.metric.create_definition(\n calculation_type=\"LLM_JUDGE\",\n name=\"Customer Satisfaction\",\n output_type=\"BOOLEAN\",\n)\nprint(response.data)" } ] } }, "/v1/metric/definitions/{idOrSlug}": { "get": { "responses": { "200": { "description": "The metric definition", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MetricDefinitionResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1MetricDefinitionsByIdOrSlug", "tags": [ "Metric" ], "summary": "Get a metric definition", "description": "Fetch a single metric definition by its UUID or its stable `slug` (e.g. `customer_satisfaction`). Resolution is scoped to the project — a project-owned metric wins over an org-wide one, which wins over a system metric of the same `slug`.", "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "description": "The metric definition's Roark ID (UUID) or its stable `slug` (e.g. `customer_satisfaction`).", "schema": { "type": "string" } } ] }, "put": { "responses": { "200": { "description": "The updated metric definition (with `versionId` advanced to the new version)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UpdateMetricDefinitionResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1MetricDefinitionsByIdOrSlug", "tags": [ "Metric" ], "summary": "Update a metric definition", "description": "Update the editable subset of a custom metric definition, addressed by its UUID or its stable `slug`. Only the supplied fields are changed; omitted fields are left unchanged. Every update creates a new immutable version; the response carries the advanced `versionId`. Immutable fields (scope, outputType, calcType, …) are rejected, and which fields are editable depends on the metric (e.g. derived metrics only allow `name`). Roark's own metrics are rejected here: this endpoint edits the shared definition, which every workspace sees. To change one for your workspace alone, edit its variant with PUT /v1/metric/definitions/{idOrSlug}/variants/{variantId}, which forks it for you and leaves every other workspace on the original.", "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "description": "The metric definition's Roark ID (UUID) or its stable `slug` (e.g. `customer_satisfaction`).", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMetricDefinitionInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.metric.updateDefinition('idOrSlug');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.metric.update_definition(\n id_or_slug=\"idOrSlug\",\n)\nprint(response.data)" } ] }, "delete": { "responses": { "200": { "description": "The metric definition was archived", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Roark ID of the archived metric definition" }, "deleted": { "type": "boolean", "const": true, "description": "Always true when the metric definition was successfully archived" } }, "required": [ "id", "deleted" ], "title": "DeleteMetricDefinitionResponse", "description": "Result of archiving (soft-deleting) a metric definition" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1MetricDefinitionsByIdOrSlug", "tags": [ "Metric" ], "summary": "Delete a metric definition", "description": "Archives (soft-deletes) a custom metric definition, addressed by its UUID or its stable `slug`. The metric is hidden from all reads and stops being collected, but its record and previously collected values are retained. System metrics cannot be deleted. Fails with 409 if the metric is still used as a source by a derived metric (delete those first).", "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "description": "The metric definition's Roark ID (UUID) or its stable `slug` (e.g. `customer_satisfaction`).", "schema": { "type": "string" } } ] } }, "/v1/metric/definitions/{idOrSlug}/thresholds": { "post": { "responses": { "201": { "description": "The created threshold (as a metric definition)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ThresholdMetricResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1MetricDefinitionsByIdOrSlugThresholds", "tags": [ "Metric" ], "summary": "Create a threshold on a metric", "description": "Create a boolean threshold derived from an existing metric. The source metric is addressed by its UUID or its stable `slug`. The threshold fires when the source metric meets the comparison condition. Scope and supported contexts are inherited from the source metric.", "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "description": "The metric definition's Roark ID (UUID) or its stable `slug` (e.g. `customer_satisfaction`).", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateThresholdInput" } } } } } }, "/v1/metric/definitions/{idOrSlug}/variants": { "get": { "responses": { "200": { "description": "The variants visible to your organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MetricVariantListResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1MetricDefinitionsByIdOrSlugVariants", "tags": [ "Metric" ], "summary": "List a metric’s variants", "description": "Every configuration of this metric your organization can use: Roark’s own variants and any your\norganization has added or forked. `isDefault` marks the one the metric is scored with when nothing\npins another; pass any variant’s `id` as `sourceVariantId` to pin it on a derived metric.\n\nAuto-managed variants (the ones a package materializes for you) are not listed: they are engine state,\nnot configuration you author.", "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "description": "Metric definition UUID or its stable slug.", "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst metricVariants = await client.metricVariant.list('idOrSlug');\n\nconsole.log(metricVariants.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nmetric_variants = client.metric_variant.list(\n \"idOrSlug\",\n)\nprint(metric_variants.data)" } ] }, "post": { "responses": { "201": { "description": "The created variant", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MetricVariantResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1MetricDefinitionsByIdOrSlugVariants", "tags": [ "Metric" ], "summary": "Create a metric variant", "description": "Add a configuration of this metric for your organization, seeded from its Default. Edit it with\nPUT to change what it measures, then pin it where you want it used.\n\nThreshold metrics have no variants: their configuration comes from the metric they derive from.\nMetrics in a package that manages its own variants reject this too.", "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "description": "Metric definition UUID or its stable slug.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMetricVariantInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst metricVariant = await client.metricVariant.create('idOrSlug', { name: 'Strict' });\n\nconsole.log(metricVariant.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nmetric_variant = client.metric_variant.create(\n id_or_slug=\"idOrSlug\",\n name=\"Strict\",\n)\nprint(metric_variant.data)" } ] } }, "/v1/metric/definitions/{idOrSlug}/variants/{variantId}": { "get": { "responses": { "200": { "description": "The variant", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MetricVariantResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1MetricDefinitionsByIdOrSlugVariantsByVariantId", "tags": [ "Metric" ], "summary": "Get a metric variant", "description": "One configuration of this metric, by id.", "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "description": "Metric definition UUID or its stable slug.", "schema": { "type": "string" } }, { "name": "variantId", "in": "path", "required": true, "description": "Variant UUID.", "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.metricVariant.getByID('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n idOrSlug: 'idOrSlug',\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.metric_variant.get_by_id(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n id_or_slug=\"idOrSlug\",\n)\nprint(response.data)" } ] }, "put": { "responses": { "200": { "description": "The updated variant, or your organization’s fork of it", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MetricVariantResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1MetricDefinitionsByIdOrSlugVariantsByVariantId", "tags": [ "Metric" ], "summary": "Update a metric variant", "description": "Rename a variant, change its configuration, or both. Every configuration change creates a new\nimmutable version and advances `versionId`; the response carries the advanced value.\n\n**Editing one of Roark’s own variants forks it for your organization.** The response carries the\nnew variant’s `id`, which will differ from the one in the path, and `isSystem` becomes false. Roark’s\nvariant is untouched and other organizations keep it. DELETE your fork to go back to it.\n\nWhich fields are editable depends on the metric: some Roark metrics lock their prompt or output\nconfiguration, and a locked field is rejected rather than ignored.", "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "description": "Metric definition UUID or its stable slug.", "schema": { "type": "string" } }, { "name": "variantId", "in": "path", "required": true, "description": "Variant UUID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMetricVariantInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst metricVariant = await client.metricVariant.update('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n idOrSlug: 'idOrSlug',\n});\n\nconsole.log(metricVariant.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nmetric_variant = client.metric_variant.update(\n variant_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n id_or_slug=\"idOrSlug\",\n)\nprint(metric_variant.data)" } ] }, "delete": { "responses": { "200": { "description": "The variant was deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeleteMetricVariantResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1MetricDefinitionsByIdOrSlugVariantsByVariantId", "tags": [ "Metric" ], "summary": "Delete a metric variant", "description": "Remove one of your organization’s variants. Anything pinned to it falls back to the Default, so\ndeleting a fork of a Roark variant returns you to Roark’s configuration.\n\nRoark’s own variants cannot be deleted, and neither can a Default. Values already collected under\nthe deleted variant are retained.", "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "description": "Metric definition UUID or its stable slug.", "schema": { "type": "string" } }, { "name": "variantId", "in": "path", "required": true, "description": "Variant UUID.", "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst metricVariant = await client.metricVariant.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n idOrSlug: 'idOrSlug',\n});\n\nconsole.log(metricVariant.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nmetric_variant = client.metric_variant.delete(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n id_or_slug=\"idOrSlug\",\n)\nprint(metric_variant.data)" } ] } }, "/v1/metric/policies": { "get": { "responses": { "200": { "description": "Paginated list of metric policies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMetricPoliciesResponse" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1MetricPolicies", "tags": [ "Metric Policy" ], "summary": "List metric policies", "description": "Returns a paginated list of metric policies for the project, including system policies.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20, "description": "Maximum number of policies to return (default: 20, max: 50)", "example": 20 } }, { "in": "query", "name": "after", "schema": { "type": "string", "description": "Cursor for pagination - use the nextCursor value from a previous response" } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "description": "Filter by policy status" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst metricPolicies = await client.metricPolicy.list();\n\nconsole.log(metricPolicies.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nmetric_policies = client.metric_policy.list()\nprint(metric_policies.data)" } ] }, "post": { "responses": { "201": { "description": "The created metric policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MetricPolicyResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1MetricPolicies", "tags": [ "Metric Policy" ], "summary": "Create a metric policy", "description": "Creates a new metric policy. Policies define which metrics to collect and under what conditions.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMetricPolicyInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst metricPolicy = await client.metricPolicy.create({\n metrics: [{ id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' }],\n modality: 'call',\n name: 'Evaluate all inbound calls',\n});\n\nconsole.log(metricPolicy.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nmetric_policy = client.metric_policy.create(\n metrics=[{\n \"id\": \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\"\n }],\n modality=\"call\",\n name=\"Evaluate all inbound calls\",\n)\nprint(metric_policy.data)" } ] } }, "/v1/metric/policies/{policyId}": { "get": { "responses": { "200": { "description": "The requested metric policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MetricPolicyResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1MetricPoliciesByPolicyId", "tags": [ "Metric Policy" ], "summary": "Get metric policy by ID", "description": "Returns a specific metric policy with its conditions and metrics.", "parameters": [ { "name": "policyId", "in": "path", "required": true, "description": "The ID of the metric policy to retrieve", "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.metricPolicy.getByID('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.metric_policy.get_by_id(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] }, "put": { "responses": { "200": { "description": "The updated metric policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MetricPolicyResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1MetricPoliciesByPolicyId", "tags": [ "Metric Policy" ], "summary": "Update a metric policy", "description": "Updates an existing metric policy. System policies cannot be modified.", "parameters": [ { "name": "policyId", "in": "path", "required": true, "description": "The ID of the metric policy to update", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMetricPolicyInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst metricPolicy = await client.metricPolicy.update('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(metricPolicy.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nmetric_policy = client.metric_policy.update(\n policy_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(metric_policy.data)" } ] }, "delete": { "responses": { "200": { "description": "Metric policy deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "description": "Whether the policy was deleted" } }, "required": [ "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1MetricPoliciesByPolicyId", "tags": [ "Metric Policy" ], "summary": "Delete a metric policy", "description": "Soft-deletes a metric policy. System policies cannot be deleted.", "parameters": [ { "name": "policyId", "in": "path", "required": true, "description": "The ID of the metric policy to delete", "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst metricPolicy = await client.metricPolicy.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(metricPolicy.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nmetric_policy = client.metric_policy.delete(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(metric_policy.data)" } ] } }, "/v1/metric/collection-jobs": { "get": { "responses": { "200": { "description": "Paginated list of metric collection jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMetricCollectionJobsResponse" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1MetricCollection-jobs", "tags": [ "Metric Collection Job" ], "summary": "List metric collection jobs", "description": "Returns a paginated list of metric collection jobs for the project.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20, "description": "Maximum number of jobs to return (default: 20, max: 50)", "example": 20 } }, { "in": "query", "name": "after", "schema": { "type": "string", "description": "Cursor for pagination - use the nextCursor value from a previous response" } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELED" ], "description": "Filter by job status" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst metricCollectionJobs = await client.metricCollectionJob.list();\n\nconsole.log(metricCollectionJobs.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nmetric_collection_jobs = client.metric_collection_job.list()\nprint(metric_collection_jobs.data)" } ] }, "post": { "responses": { "201": { "description": "The created metric collection job", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MetricCollectionJobResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Insufficient credit" }, "example": { "type": "payment_required", "code": "insufficient_credits", "message": "Not enough credit to start this work. Add credit and try again." } } }, "description": "Payment Required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1MetricCollection-jobs", "tags": [ "Metric Collection Job" ], "summary": "Create and run a metric collection job", "description": "Creates a metric collection job for the specified calls or chats and metrics, then triggers processing. Provide exactly one of callIds or chatIds. Pass policyId to score with a metric policy’s settings (for example to re-score past calls after changing which properties Property Verification checks); metrics then defaults to every metric that policy collects.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMetricCollectionJobInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst metricCollectionJob = await client.metricCollectionJob.create();\n\nconsole.log(metricCollectionJob.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nmetric_collection_job = client.metric_collection_job.create()\nprint(metric_collection_job.data)" } ] } }, "/v1/metric/collection-jobs/{jobId}": { "get": { "responses": { "200": { "description": "The requested metric collection job", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MetricCollectionJobResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1MetricCollection-jobsByJobId", "tags": [ "Metric Collection Job" ], "summary": "Get metric collection job by ID", "description": "Returns a specific metric collection job with progress information.", "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "The ID of the metric collection job to retrieve", "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.metricCollectionJob.getByID('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.metric_collection_job.get_by_id(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] } }, "/v1/metric/collection-jobs/{jobId}/retry": { "post": { "responses": { "201": { "description": "The newly created (retry) metric collection job", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MetricCollectionJobResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Insufficient credit" }, "example": { "type": "payment_required", "code": "insufficient_credits", "message": "Not enough credit to start this work. Add credit and try again." } } }, "description": "Payment Required" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1MetricCollection-jobsByJobIdRetry", "tags": [ "Metric Collection Job" ], "summary": "Retry a metric collection job", "description": "Creates a new metric collection job using the same conversations and metrics as a previous job, then triggers processing. The previous job must be in a terminal state (COMPLETED, FAILED, or CANCELED). Returns the newly created job — track its id for downstream fetches.", "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "The ID of the previous metric collection job to retry", "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/metric/collection-jobs/{jobId}/cancel": { "post": { "responses": { "200": { "description": "The canceled job, or the job unchanged if it had already finished", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MetricCollectionJobResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1MetricCollection-jobsByJobIdCancel", "tags": [ "Metric Collection Job" ], "summary": "Cancel a metric collection job", "description": "Stops a metric collection job that has not finished. No further conversations are processed and the job ends in CANCELED.\n\nItems the job had not reached are marked SKIPPED. Metric values already produced are kept, and items that were mid-computation when the cancel arrived may still complete. Only the items that completed are billed.\n\nSafe to call more than once: a job that has already finished (COMPLETED, FAILED, or CANCELED) is returned unchanged.", "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "The ID of the metric collection job to cancel", "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.metricCollectionJob.cancel('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.metric_collection_job.cancel(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] } }, "/v1/metric/collection-jobs/{jobId}/metric-values": { "get": { "responses": { "200": { "description": "Metric values produced by the job, grouped by metric definition", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MetricCollectionJobMetricValuesResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1MetricCollection-jobsByJobIdMetric-values", "tags": [ "Metric Collection Job" ], "summary": "Get metric values produced by a metric collection job", "description": "Returns the metric values produced by the specified job, grouped by metric definition. Unlike `GET /v1/call/:callId/metrics` (which returns the latest values on a call, regardless of which job computed them), this endpoint returns exactly the values *this* job produced — including for calls whose live values have since been overwritten by a later job. By default returns only SUCCESS rows; pass `?status=all` to also include NOT_APPLICABLE / DATA_MISSING / ERROR.", "parameters": [ { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "success", "all" ], "default": "success", "description": "Filter metrics by capture status. `success` (default) returns only successfully computed metrics; `all` also returns NOT_APPLICABLE / DATA_MISSING / ERROR rows with the `value` field omitted." } }, { "schema": { "type": "string" }, "in": "path", "name": "jobId", "required": true } ] } }, "/v1/persona": { "get": { "responses": { "200": { "description": "List of personas", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the persona" }, "name": { "type": "string", "description": "The name the agent will identify as during conversations" }, "displayName": { "type": [ "string", "null" ], "description": "Label shown in place of the name across the dashboard (e.g. a short descriptor like \"Irate Escalator\"). The persona still identifies as `name` on calls. Omit or set null to display the name itself." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of the persona" }, "language": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ], "description": "Primary language ISO 639-1 code for the persona" }, "secondaryLanguage": { "type": [ "string", "null" ], "enum": [ "EN" ], "description": "Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish)" }, "understoodLanguages": { "type": "array", "items": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ] }, "minItems": 1, "description": "Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support." }, "accent": { "type": "string", "enum": [ "US", "US_X_SOUTH", "GB", "ES", "DE", "IN", "FR", "NL", "SA", "GR", "AU", "IT", "ID", "TH", "JP", "NZ", "PH", "SG", "MY", "HK", "TR", "PT", "IL" ], "description": "Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants" }, "age": { "type": "string", "enum": [ "CHILD", "TEENAGER", "ADULT", "ELDERLY" ], "default": "ADULT", "description": "How old the caller sounds and behaves. Only ages the persona's accent has a voice for are accepted; defaults to ADULT, which every accent supports." }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender of the persona" }, "backgroundNoise": { "type": "string", "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "default": "NONE", "description": "Background noise setting" }, "speechPace": { "type": "string", "enum": [ "SUPER_SLOW", "SLOW", "NORMAL", "FAST", "SUPER_FAST" ], "default": "NORMAL", "description": "Speech pace of the persona" }, "speechClarity": { "type": "string", "enum": [ "CLEAR", "VAGUE", "RAMBLING" ], "default": "CLEAR", "description": "Speech clarity of the persona" }, "hasDisfluencies": { "type": "boolean", "default": false, "description": "Whether the persona uses filler words like \"um\" and \"uh\"" }, "baseEmotion": { "type": "string", "enum": [ "NEUTRAL", "CHEERFUL", "CONFUSED", "FRUSTRATED", "SKEPTICAL", "RUSHED", "DISTRACTED", "ANGRY", "ANXIOUS", "SAD" ], "default": "NEUTRAL", "description": "Base emotional state of the persona" }, "intentClarity": { "type": "string", "enum": [ "CLEAR", "INDIRECT", "VAGUE" ], "default": "CLEAR", "description": "How clearly the persona expresses their intentions" }, "confirmationStyle": { "type": "string", "enum": [ "EXPLICIT", "VAGUE" ], "default": "EXPLICIT", "description": "How the persona confirms information" }, "memoryReliability": { "type": "string", "enum": [ "HIGH", "LOW" ], "default": "HIGH", "description": "How reliable the persona's memory is" }, "responseTiming": { "type": "string", "enum": [ "RELAXED", "NORMAL", "QUICK", "BARGE_IN" ], "default": "NORMAL", "description": "Deprecated and inert: it no longer affects the call. It set how long the persona waited once the agent stopped talking, and measured across production simulations it moved the reply gap by less than the noise floor, because model and speech latency dominate it. Every persona now uses one voice-activity profile. Use `interruption` for a caller who talks over the agent. Still accepted and stored so existing clients keep working. BARGE_IN is stored as `responseTiming: QUICK` with `interruption: OCCASIONAL`." }, "interruption": { "type": "string", "enum": [ "OFF", "BACKCHANNEL", "OCCASIONAL", "HEAVY" ], "default": "OFF", "description": "How much the persona talks over the agent while it is still speaking. OFF waits its turn. BACKCHANNEL makes listening noises (\"mm-hm\") over the agent without taking the floor, which tests whether the agent wrongly stops for them. OCCASIONAL adds cutting in on some long agent turns, HEAVY on most of them. Timing is randomised per turn, so two runs of the same persona do not interrupt at identical moments." }, "backstoryPrompt": { "type": [ "string", "null" ], "description": "Background story and behavioral patterns for the persona", "example": "A busy professional calling during lunch break" }, "idleMessages": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Messages the persona will say when the agent goes silent during a call. null = \"Automatic\": language-appropriate defaults are used at call time." }, "idleTimeoutSeconds": { "type": "integer", "minimum": 5, "maximum": 60, "default": 10, "description": "Seconds of silence before the persona sends an idle message" }, "idleMessageMaxSpokenCount": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3, "description": "Maximum number of idle messages the persona will send before giving up" }, "idleMessageResetCountOnUserSpeechEnabled": { "type": "boolean", "default": true, "description": "Whether the idle message counter resets when the agent speaks" }, "properties": { "type": "object", "additionalProperties": {}, "default": {}, "description": "Additional custom properties about the persona", "example": { "age": 35, "zipCode": "94105", "occupation": "Software Engineer" } }, "phoneNumber": { "type": "string", "description": "The E.164 number every call with this persona uses, when Roark has pinned one for your project. Present only when set; read-only.", "example": "+19312830919" }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "description": "Last update timestamp" } }, "required": [ "id", "name", "language", "understoodLanguages", "accent", "age", "gender", "backgroundNoise", "speechPace", "speechClarity", "hasDisfluencies", "baseEmotion", "intentClarity", "confirmationStyle", "memoryReliability", "responseTiming", "interruption", "idleMessages", "idleTimeoutSeconds", "idleMessageMaxSpokenCount", "idleMessageResetCountOnUserSpeechEnabled", "properties", "createdAt", "updatedAt" ] } }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of items" }, "hasMore": { "type": "boolean", "description": "Whether there are more items to fetch" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page of items" } }, "required": [ "total", "hasMore", "nextCursor" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Persona", "tags": [ "Simulation Persona" ], "summary": "List personas", "description": "Returns a paginated list of personas for the authenticated project.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "in": "query", "name": "after", "schema": { "type": "string" } }, { "in": "query", "name": "searchText", "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationPersonas = await client.simulationPersona.list();\n\nconsole.log(simulationPersonas.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_personas = client.simulation_persona.list()\nprint(simulation_personas.data)" } ] }, "post": { "responses": { "201": { "description": "The created persona", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the persona" }, "name": { "type": "string", "description": "The name the agent will identify as during conversations" }, "displayName": { "type": [ "string", "null" ], "description": "Label shown in place of the name across the dashboard (e.g. a short descriptor like \"Irate Escalator\"). The persona still identifies as `name` on calls. Omit or set null to display the name itself." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of the persona" }, "language": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ], "description": "Primary language ISO 639-1 code for the persona" }, "secondaryLanguage": { "type": [ "string", "null" ], "enum": [ "EN" ], "description": "Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish)" }, "understoodLanguages": { "type": "array", "items": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ] }, "minItems": 1, "description": "Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support." }, "accent": { "type": "string", "enum": [ "US", "US_X_SOUTH", "GB", "ES", "DE", "IN", "FR", "NL", "SA", "GR", "AU", "IT", "ID", "TH", "JP", "NZ", "PH", "SG", "MY", "HK", "TR", "PT", "IL" ], "description": "Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants" }, "age": { "type": "string", "enum": [ "CHILD", "TEENAGER", "ADULT", "ELDERLY" ], "default": "ADULT", "description": "How old the caller sounds and behaves. Only ages the persona's accent has a voice for are accepted; defaults to ADULT, which every accent supports." }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender of the persona" }, "backgroundNoise": { "type": "string", "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "default": "NONE", "description": "Background noise setting" }, "speechPace": { "type": "string", "enum": [ "SUPER_SLOW", "SLOW", "NORMAL", "FAST", "SUPER_FAST" ], "default": "NORMAL", "description": "Speech pace of the persona" }, "speechClarity": { "type": "string", "enum": [ "CLEAR", "VAGUE", "RAMBLING" ], "default": "CLEAR", "description": "Speech clarity of the persona" }, "hasDisfluencies": { "type": "boolean", "default": false, "description": "Whether the persona uses filler words like \"um\" and \"uh\"" }, "baseEmotion": { "type": "string", "enum": [ "NEUTRAL", "CHEERFUL", "CONFUSED", "FRUSTRATED", "SKEPTICAL", "RUSHED", "DISTRACTED", "ANGRY", "ANXIOUS", "SAD" ], "default": "NEUTRAL", "description": "Base emotional state of the persona" }, "intentClarity": { "type": "string", "enum": [ "CLEAR", "INDIRECT", "VAGUE" ], "default": "CLEAR", "description": "How clearly the persona expresses their intentions" }, "confirmationStyle": { "type": "string", "enum": [ "EXPLICIT", "VAGUE" ], "default": "EXPLICIT", "description": "How the persona confirms information" }, "memoryReliability": { "type": "string", "enum": [ "HIGH", "LOW" ], "default": "HIGH", "description": "How reliable the persona's memory is" }, "responseTiming": { "type": "string", "enum": [ "RELAXED", "NORMAL", "QUICK", "BARGE_IN" ], "default": "NORMAL", "description": "Deprecated and inert: it no longer affects the call. It set how long the persona waited once the agent stopped talking, and measured across production simulations it moved the reply gap by less than the noise floor, because model and speech latency dominate it. Every persona now uses one voice-activity profile. Use `interruption` for a caller who talks over the agent. Still accepted and stored so existing clients keep working. BARGE_IN is stored as `responseTiming: QUICK` with `interruption: OCCASIONAL`." }, "interruption": { "type": "string", "enum": [ "OFF", "BACKCHANNEL", "OCCASIONAL", "HEAVY" ], "default": "OFF", "description": "How much the persona talks over the agent while it is still speaking. OFF waits its turn. BACKCHANNEL makes listening noises (\"mm-hm\") over the agent without taking the floor, which tests whether the agent wrongly stops for them. OCCASIONAL adds cutting in on some long agent turns, HEAVY on most of them. Timing is randomised per turn, so two runs of the same persona do not interrupt at identical moments." }, "backstoryPrompt": { "type": [ "string", "null" ], "description": "Background story and behavioral patterns for the persona", "example": "A busy professional calling during lunch break" }, "idleMessages": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Messages the persona will say when the agent goes silent during a call. null = \"Automatic\": language-appropriate defaults are used at call time." }, "idleTimeoutSeconds": { "type": "integer", "minimum": 5, "maximum": 60, "default": 10, "description": "Seconds of silence before the persona sends an idle message" }, "idleMessageMaxSpokenCount": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3, "description": "Maximum number of idle messages the persona will send before giving up" }, "idleMessageResetCountOnUserSpeechEnabled": { "type": "boolean", "default": true, "description": "Whether the idle message counter resets when the agent speaks" }, "properties": { "type": "object", "additionalProperties": {}, "default": {}, "description": "Additional custom properties about the persona", "example": { "age": 35, "zipCode": "94105", "occupation": "Software Engineer" } }, "phoneNumber": { "type": "string", "description": "The E.164 number every call with this persona uses, when Roark has pinned one for your project. Present only when set; read-only.", "example": "+19312830919" }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "description": "Last update timestamp" } }, "required": [ "id", "name", "language", "understoodLanguages", "accent", "age", "gender", "backgroundNoise", "speechPace", "speechClarity", "hasDisfluencies", "baseEmotion", "intentClarity", "confirmationStyle", "memoryReliability", "responseTiming", "interruption", "idleMessages", "idleTimeoutSeconds", "idleMessageMaxSpokenCount", "idleMessageResetCountOnUserSpeechEnabled", "properties", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1Persona", "tags": [ "Simulation Persona" ], "summary": "Create a new persona", "description": "Creates a new persona for the authenticated project.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name the agent will identify as during conversations" }, "displayName": { "type": [ "string", "null" ], "description": "Label shown in place of the name across the dashboard (e.g. a short descriptor like \"Irate Escalator\"). The persona still identifies as `name` on calls. Omit or set null to display the name itself." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of the persona" }, "language": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ], "description": "Primary language ISO 639-1 code for the persona" }, "secondaryLanguage": { "type": [ "string", "null" ], "enum": [ "EN" ], "description": "Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish)" }, "understoodLanguages": { "type": "array", "items": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ] }, "minItems": 1, "description": "Languages the persona can understand. Defaults to the languages the persona speaks." }, "accent": { "type": "string", "enum": [ "US", "US_X_SOUTH", "GB", "ES", "DE", "IN", "FR", "NL", "SA", "GR", "AU", "IT", "ID", "TH", "JP", "NZ", "PH", "SG", "MY", "HK", "TR", "PT", "IL" ], "description": "Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants" }, "age": { "type": "string", "enum": [ "CHILD", "TEENAGER", "ADULT", "ELDERLY" ], "default": "ADULT", "description": "How old the caller sounds and behaves. Only ages the persona's accent has a voice for are accepted; defaults to ADULT, which every accent supports." }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender of the persona" }, "backgroundNoise": { "type": "string", "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "default": "NONE", "description": "Background noise setting" }, "speechPace": { "type": "string", "enum": [ "SUPER_SLOW", "SLOW", "NORMAL", "FAST", "SUPER_FAST" ], "default": "NORMAL", "description": "Speech pace of the persona" }, "speechClarity": { "type": "string", "enum": [ "CLEAR", "VAGUE", "RAMBLING" ], "default": "CLEAR", "description": "Speech clarity of the persona" }, "hasDisfluencies": { "type": "boolean", "default": false, "description": "Whether the persona uses filler words like \"um\" and \"uh\"" }, "baseEmotion": { "type": "string", "enum": [ "NEUTRAL", "CHEERFUL", "CONFUSED", "FRUSTRATED", "SKEPTICAL", "RUSHED", "DISTRACTED", "ANGRY", "ANXIOUS", "SAD" ], "default": "NEUTRAL", "description": "Base emotional state of the persona" }, "intentClarity": { "type": "string", "enum": [ "CLEAR", "INDIRECT", "VAGUE" ], "default": "CLEAR", "description": "How clearly the persona expresses their intentions" }, "confirmationStyle": { "type": "string", "enum": [ "EXPLICIT", "VAGUE" ], "default": "EXPLICIT", "description": "How the persona confirms information" }, "memoryReliability": { "type": "string", "enum": [ "HIGH", "LOW" ], "default": "HIGH", "description": "How reliable the persona's memory is" }, "responseTiming": { "type": "string", "enum": [ "RELAXED", "NORMAL", "QUICK", "BARGE_IN" ], "default": "NORMAL", "description": "Deprecated and inert: it no longer affects the call. It set how long the persona waited once the agent stopped talking, and measured across production simulations it moved the reply gap by less than the noise floor, because model and speech latency dominate it. Every persona now uses one voice-activity profile. Use `interruption` for a caller who talks over the agent. Still accepted and stored so existing clients keep working. BARGE_IN is stored as `responseTiming: QUICK` with `interruption: OCCASIONAL`." }, "interruption": { "type": "string", "enum": [ "OFF", "BACKCHANNEL", "OCCASIONAL", "HEAVY" ], "description": "How much the persona talks over the agent. Defaults to OFF, a caller that waits its turn." }, "backstoryPrompt": { "type": [ "string", "null" ], "description": "Background story and behavioral patterns for the persona", "example": "A busy professional calling during lunch break" }, "idleMessages": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Messages the persona will say when the agent goes silent during a call. Defaults to language-appropriate phrases when omitted or sent as null." }, "idleTimeoutSeconds": { "type": "integer", "minimum": 5, "maximum": 60, "default": 10, "description": "Seconds of silence before the persona sends an idle message" }, "idleMessageMaxSpokenCount": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3, "description": "Maximum number of idle messages the persona will send before giving up" }, "idleMessageResetCountOnUserSpeechEnabled": { "type": "boolean", "default": true, "description": "Whether the idle message counter resets when the agent speaks" }, "properties": { "type": "object", "additionalProperties": {}, "default": {}, "description": "Additional custom properties about the persona", "example": { "age": 35, "zipCode": "94105", "occupation": "Software Engineer" } } }, "required": [ "name", "language", "accent", "gender" ], "title": "CreatePersonaInput", "description": "Input for creating a new persona" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationPersona = await client.simulationPersona.create({\n accent: 'US',\n gender: 'MALE',\n language: 'EN',\n name: 'name',\n});\n\nconsole.log(simulationPersona.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_persona = client.simulation_persona.create(\n accent=\"US\",\n gender=\"MALE\",\n language=\"EN\",\n name=\"name\",\n)\nprint(simulation_persona.data)" } ] } }, "/v1/persona/{personaId}": { "get": { "responses": { "200": { "description": "The requested persona", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the persona" }, "name": { "type": "string", "description": "The name the agent will identify as during conversations" }, "displayName": { "type": [ "string", "null" ], "description": "Label shown in place of the name across the dashboard (e.g. a short descriptor like \"Irate Escalator\"). The persona still identifies as `name` on calls. Omit or set null to display the name itself." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of the persona" }, "language": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ], "description": "Primary language ISO 639-1 code for the persona" }, "secondaryLanguage": { "type": [ "string", "null" ], "enum": [ "EN" ], "description": "Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish)" }, "understoodLanguages": { "type": "array", "items": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ] }, "minItems": 1, "description": "Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support." }, "accent": { "type": "string", "enum": [ "US", "US_X_SOUTH", "GB", "ES", "DE", "IN", "FR", "NL", "SA", "GR", "AU", "IT", "ID", "TH", "JP", "NZ", "PH", "SG", "MY", "HK", "TR", "PT", "IL" ], "description": "Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants" }, "age": { "type": "string", "enum": [ "CHILD", "TEENAGER", "ADULT", "ELDERLY" ], "default": "ADULT", "description": "How old the caller sounds and behaves. Only ages the persona's accent has a voice for are accepted; defaults to ADULT, which every accent supports." }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender of the persona" }, "backgroundNoise": { "type": "string", "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "default": "NONE", "description": "Background noise setting" }, "speechPace": { "type": "string", "enum": [ "SUPER_SLOW", "SLOW", "NORMAL", "FAST", "SUPER_FAST" ], "default": "NORMAL", "description": "Speech pace of the persona" }, "speechClarity": { "type": "string", "enum": [ "CLEAR", "VAGUE", "RAMBLING" ], "default": "CLEAR", "description": "Speech clarity of the persona" }, "hasDisfluencies": { "type": "boolean", "default": false, "description": "Whether the persona uses filler words like \"um\" and \"uh\"" }, "baseEmotion": { "type": "string", "enum": [ "NEUTRAL", "CHEERFUL", "CONFUSED", "FRUSTRATED", "SKEPTICAL", "RUSHED", "DISTRACTED", "ANGRY", "ANXIOUS", "SAD" ], "default": "NEUTRAL", "description": "Base emotional state of the persona" }, "intentClarity": { "type": "string", "enum": [ "CLEAR", "INDIRECT", "VAGUE" ], "default": "CLEAR", "description": "How clearly the persona expresses their intentions" }, "confirmationStyle": { "type": "string", "enum": [ "EXPLICIT", "VAGUE" ], "default": "EXPLICIT", "description": "How the persona confirms information" }, "memoryReliability": { "type": "string", "enum": [ "HIGH", "LOW" ], "default": "HIGH", "description": "How reliable the persona's memory is" }, "responseTiming": { "type": "string", "enum": [ "RELAXED", "NORMAL", "QUICK", "BARGE_IN" ], "default": "NORMAL", "description": "Deprecated and inert: it no longer affects the call. It set how long the persona waited once the agent stopped talking, and measured across production simulations it moved the reply gap by less than the noise floor, because model and speech latency dominate it. Every persona now uses one voice-activity profile. Use `interruption` for a caller who talks over the agent. Still accepted and stored so existing clients keep working. BARGE_IN is stored as `responseTiming: QUICK` with `interruption: OCCASIONAL`." }, "interruption": { "type": "string", "enum": [ "OFF", "BACKCHANNEL", "OCCASIONAL", "HEAVY" ], "default": "OFF", "description": "How much the persona talks over the agent while it is still speaking. OFF waits its turn. BACKCHANNEL makes listening noises (\"mm-hm\") over the agent without taking the floor, which tests whether the agent wrongly stops for them. OCCASIONAL adds cutting in on some long agent turns, HEAVY on most of them. Timing is randomised per turn, so two runs of the same persona do not interrupt at identical moments." }, "backstoryPrompt": { "type": [ "string", "null" ], "description": "Background story and behavioral patterns for the persona", "example": "A busy professional calling during lunch break" }, "idleMessages": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Messages the persona will say when the agent goes silent during a call. null = \"Automatic\": language-appropriate defaults are used at call time." }, "idleTimeoutSeconds": { "type": "integer", "minimum": 5, "maximum": 60, "default": 10, "description": "Seconds of silence before the persona sends an idle message" }, "idleMessageMaxSpokenCount": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3, "description": "Maximum number of idle messages the persona will send before giving up" }, "idleMessageResetCountOnUserSpeechEnabled": { "type": "boolean", "default": true, "description": "Whether the idle message counter resets when the agent speaks" }, "properties": { "type": "object", "additionalProperties": {}, "default": {}, "description": "Additional custom properties about the persona", "example": { "age": 35, "zipCode": "94105", "occupation": "Software Engineer" } }, "phoneNumber": { "type": "string", "description": "The E.164 number every call with this persona uses, when Roark has pinned one for your project. Present only when set; read-only.", "example": "+19312830919" }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "description": "Last update timestamp" } }, "required": [ "id", "name", "language", "understoodLanguages", "accent", "age", "gender", "backgroundNoise", "speechPace", "speechClarity", "hasDisfluencies", "baseEmotion", "intentClarity", "confirmationStyle", "memoryReliability", "responseTiming", "interruption", "idleMessages", "idleTimeoutSeconds", "idleMessageMaxSpokenCount", "idleMessageResetCountOnUserSpeechEnabled", "properties", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1PersonaByPersonaId", "tags": [ "Simulation Persona" ], "summary": "Get persona by ID", "description": "Returns a specific persona by its ID.", "parameters": [ { "name": "personaId", "in": "path", "required": true, "description": "The ID of the persona to retrieve", "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationPersona.getByID('personaId');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.simulation_persona.get_by_id(\n \"personaId\",\n)\nprint(response.data)" } ] }, "put": { "responses": { "200": { "description": "The updated persona", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the persona" }, "name": { "type": "string", "description": "The name the agent will identify as during conversations" }, "displayName": { "type": [ "string", "null" ], "description": "Label shown in place of the name across the dashboard (e.g. a short descriptor like \"Irate Escalator\"). The persona still identifies as `name` on calls. Omit or set null to display the name itself." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of the persona" }, "language": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ], "description": "Primary language ISO 639-1 code for the persona" }, "secondaryLanguage": { "type": [ "string", "null" ], "enum": [ "EN" ], "description": "Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish)" }, "understoodLanguages": { "type": "array", "items": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ] }, "minItems": 1, "description": "Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support." }, "accent": { "type": "string", "enum": [ "US", "US_X_SOUTH", "GB", "ES", "DE", "IN", "FR", "NL", "SA", "GR", "AU", "IT", "ID", "TH", "JP", "NZ", "PH", "SG", "MY", "HK", "TR", "PT", "IL" ], "description": "Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants" }, "age": { "type": "string", "enum": [ "CHILD", "TEENAGER", "ADULT", "ELDERLY" ], "default": "ADULT", "description": "How old the caller sounds and behaves. Only ages the persona's accent has a voice for are accepted; defaults to ADULT, which every accent supports." }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender of the persona" }, "backgroundNoise": { "type": "string", "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "default": "NONE", "description": "Background noise setting" }, "speechPace": { "type": "string", "enum": [ "SUPER_SLOW", "SLOW", "NORMAL", "FAST", "SUPER_FAST" ], "default": "NORMAL", "description": "Speech pace of the persona" }, "speechClarity": { "type": "string", "enum": [ "CLEAR", "VAGUE", "RAMBLING" ], "default": "CLEAR", "description": "Speech clarity of the persona" }, "hasDisfluencies": { "type": "boolean", "default": false, "description": "Whether the persona uses filler words like \"um\" and \"uh\"" }, "baseEmotion": { "type": "string", "enum": [ "NEUTRAL", "CHEERFUL", "CONFUSED", "FRUSTRATED", "SKEPTICAL", "RUSHED", "DISTRACTED", "ANGRY", "ANXIOUS", "SAD" ], "default": "NEUTRAL", "description": "Base emotional state of the persona" }, "intentClarity": { "type": "string", "enum": [ "CLEAR", "INDIRECT", "VAGUE" ], "default": "CLEAR", "description": "How clearly the persona expresses their intentions" }, "confirmationStyle": { "type": "string", "enum": [ "EXPLICIT", "VAGUE" ], "default": "EXPLICIT", "description": "How the persona confirms information" }, "memoryReliability": { "type": "string", "enum": [ "HIGH", "LOW" ], "default": "HIGH", "description": "How reliable the persona's memory is" }, "responseTiming": { "type": "string", "enum": [ "RELAXED", "NORMAL", "QUICK", "BARGE_IN" ], "default": "NORMAL", "description": "Deprecated and inert: it no longer affects the call. It set how long the persona waited once the agent stopped talking, and measured across production simulations it moved the reply gap by less than the noise floor, because model and speech latency dominate it. Every persona now uses one voice-activity profile. Use `interruption` for a caller who talks over the agent. Still accepted and stored so existing clients keep working. BARGE_IN is stored as `responseTiming: QUICK` with `interruption: OCCASIONAL`." }, "interruption": { "type": "string", "enum": [ "OFF", "BACKCHANNEL", "OCCASIONAL", "HEAVY" ], "default": "OFF", "description": "How much the persona talks over the agent while it is still speaking. OFF waits its turn. BACKCHANNEL makes listening noises (\"mm-hm\") over the agent without taking the floor, which tests whether the agent wrongly stops for them. OCCASIONAL adds cutting in on some long agent turns, HEAVY on most of them. Timing is randomised per turn, so two runs of the same persona do not interrupt at identical moments." }, "backstoryPrompt": { "type": [ "string", "null" ], "description": "Background story and behavioral patterns for the persona", "example": "A busy professional calling during lunch break" }, "idleMessages": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Messages the persona will say when the agent goes silent during a call. null = \"Automatic\": language-appropriate defaults are used at call time." }, "idleTimeoutSeconds": { "type": "integer", "minimum": 5, "maximum": 60, "default": 10, "description": "Seconds of silence before the persona sends an idle message" }, "idleMessageMaxSpokenCount": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3, "description": "Maximum number of idle messages the persona will send before giving up" }, "idleMessageResetCountOnUserSpeechEnabled": { "type": "boolean", "default": true, "description": "Whether the idle message counter resets when the agent speaks" }, "properties": { "type": "object", "additionalProperties": {}, "default": {}, "description": "Additional custom properties about the persona", "example": { "age": 35, "zipCode": "94105", "occupation": "Software Engineer" } }, "phoneNumber": { "type": "string", "description": "The E.164 number every call with this persona uses, when Roark has pinned one for your project. Present only when set; read-only.", "example": "+19312830919" }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "description": "Last update timestamp" } }, "required": [ "id", "name", "language", "understoodLanguages", "accent", "age", "gender", "backgroundNoise", "speechPace", "speechClarity", "hasDisfluencies", "baseEmotion", "intentClarity", "confirmationStyle", "memoryReliability", "responseTiming", "interruption", "idleMessages", "idleTimeoutSeconds", "idleMessageMaxSpokenCount", "idleMessageResetCountOnUserSpeechEnabled", "properties", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1PersonaByPersonaId", "tags": [ "Simulation Persona" ], "summary": "Update a persona", "description": "Updates an existing persona by its ID.", "parameters": [ { "name": "personaId", "in": "path", "required": true, "description": "The ID of the persona to update", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name the agent will identify as during conversations" }, "displayName": { "type": [ "string", "null" ], "description": "Label shown in place of the name across the dashboard (e.g. a short descriptor like \"Irate Escalator\"). The persona still identifies as `name` on calls. Omit or set null to display the name itself." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of the persona" }, "language": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ], "description": "Primary language ISO 639-1 code for the persona" }, "secondaryLanguage": { "type": [ "string", "null" ], "enum": [ "EN" ], "description": "Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish)" }, "understoodLanguages": { "type": "array", "items": { "type": "string", "enum": [ "EN", "ES", "DE", "HI", "FR", "NL", "AR", "EL", "IT", "ID", "TH", "JA", "TL", "MS", "ZH", "TR", "PT", "HE" ] }, "minItems": 1, "description": "Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support." }, "accent": { "type": "string", "enum": [ "US", "US_X_SOUTH", "GB", "ES", "DE", "IN", "FR", "NL", "SA", "GR", "AU", "IT", "ID", "TH", "JP", "NZ", "PH", "SG", "MY", "HK", "TR", "PT", "IL" ], "description": "Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants" }, "age": { "type": "string", "enum": [ "CHILD", "TEENAGER", "ADULT", "ELDERLY" ], "default": "ADULT", "description": "How old the caller sounds and behaves. Only ages the persona's accent has a voice for are accepted; defaults to ADULT, which every accent supports." }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "Gender of the persona" }, "backgroundNoise": { "type": "string", "enum": [ "NONE", "AIRPORT", "CHILDREN_PLAYING", "CITY", "COFFEE_SHOP", "CONSTRUCTION", "CRYING_BABY", "DRIVING", "LIBRARY", "OFFICE", "THUNDERSTORM", "TRAIN" ], "default": "NONE", "description": "Background noise setting" }, "speechPace": { "type": "string", "enum": [ "SUPER_SLOW", "SLOW", "NORMAL", "FAST", "SUPER_FAST" ], "default": "NORMAL", "description": "Speech pace of the persona" }, "speechClarity": { "type": "string", "enum": [ "CLEAR", "VAGUE", "RAMBLING" ], "default": "CLEAR", "description": "Speech clarity of the persona" }, "hasDisfluencies": { "type": "boolean", "default": false, "description": "Whether the persona uses filler words like \"um\" and \"uh\"" }, "baseEmotion": { "type": "string", "enum": [ "NEUTRAL", "CHEERFUL", "CONFUSED", "FRUSTRATED", "SKEPTICAL", "RUSHED", "DISTRACTED", "ANGRY", "ANXIOUS", "SAD" ], "default": "NEUTRAL", "description": "Base emotional state of the persona" }, "intentClarity": { "type": "string", "enum": [ "CLEAR", "INDIRECT", "VAGUE" ], "default": "CLEAR", "description": "How clearly the persona expresses their intentions" }, "confirmationStyle": { "type": "string", "enum": [ "EXPLICIT", "VAGUE" ], "default": "EXPLICIT", "description": "How the persona confirms information" }, "memoryReliability": { "type": "string", "enum": [ "HIGH", "LOW" ], "default": "HIGH", "description": "How reliable the persona's memory is" }, "responseTiming": { "type": "string", "enum": [ "RELAXED", "NORMAL", "QUICK", "BARGE_IN" ], "default": "NORMAL", "description": "Deprecated and inert: it no longer affects the call. It set how long the persona waited once the agent stopped talking, and measured across production simulations it moved the reply gap by less than the noise floor, because model and speech latency dominate it. Every persona now uses one voice-activity profile. Use `interruption` for a caller who talks over the agent. Still accepted and stored so existing clients keep working. BARGE_IN is stored as `responseTiming: QUICK` with `interruption: OCCASIONAL`." }, "interruption": { "type": "string", "enum": [ "OFF", "BACKCHANNEL", "OCCASIONAL", "HEAVY" ], "default": "OFF", "description": "How much the persona talks over the agent while it is still speaking. OFF waits its turn. BACKCHANNEL makes listening noises (\"mm-hm\") over the agent without taking the floor, which tests whether the agent wrongly stops for them. OCCASIONAL adds cutting in on some long agent turns, HEAVY on most of them. Timing is randomised per turn, so two runs of the same persona do not interrupt at identical moments." }, "backstoryPrompt": { "type": [ "string", "null" ], "description": "Background story and behavioral patterns for the persona", "example": "A busy professional calling during lunch break" }, "idleMessages": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Messages the persona will say when the agent goes silent during a call. null = \"Automatic\": language-appropriate defaults are used at call time." }, "idleTimeoutSeconds": { "type": "integer", "minimum": 5, "maximum": 60, "default": 10, "description": "Seconds of silence before the persona sends an idle message" }, "idleMessageMaxSpokenCount": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3, "description": "Maximum number of idle messages the persona will send before giving up" }, "idleMessageResetCountOnUserSpeechEnabled": { "type": "boolean", "default": true, "description": "Whether the idle message counter resets when the agent speaks" }, "properties": { "type": "object", "additionalProperties": {}, "default": {}, "description": "Additional custom properties about the persona", "example": { "age": 35, "zipCode": "94105", "occupation": "Software Engineer" } } }, "title": "UpdatePersonaInput", "description": "Input for updating an existing persona" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationPersona = await client.simulationPersona.update('personaId');\n\nconsole.log(simulationPersona.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_persona = client.simulation_persona.update(\n persona_id=\"personaId\",\n)\nprint(simulation_persona.data)" } ] }, "delete": { "responses": { "200": { "description": "The persona was deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the deleted persona" }, "deleted": { "type": "boolean", "const": true, "description": "Always true when the persona was successfully deleted" } }, "required": [ "id", "deleted" ] } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1PersonaByPersonaId", "tags": [ "Simulation Persona" ], "summary": "Delete a persona", "description": "Soft-deletes a persona by its ID. The persona is hidden from all reads and stops being available to new simulations, but its record and history are retained. System personas cannot be deleted.", "parameters": [ { "name": "personaId", "in": "path", "required": true, "description": "The ID of the persona to delete", "schema": { "type": "string" } } ] } }, "/v1/simulation/run": { "post": { "responses": { "200": { "description": "The run that was started", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RunSimulationResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Insufficient credit" }, "example": { "type": "payment_required", "code": "insufficient_credits", "message": "Not enough credit to start this work. Add credit and try again." } } }, "description": "Payment Required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1SimulationRun", "tags": [ "Simulation" ], "summary": "Run a simulation", "description": "Starts a simulation and returns the run.\n\nSend `template` to run one of the built-in templates: it supplies the metrics and checks,\nand for some templates the flows too, so the request only names the agent and the direction.\nSend `plan` to describe a simulation yourself and run it once. Send `planId` to run a plan\nyou already have.\n\n`template` and `plan` both resolve to a run plan, returned as `simulationRunPlanId`. Add\n`saveAsPlan` to keep it, or read it back to see exactly what ran. A plan built from a\ntemplate is a snapshot: retuning the template later never changes what that plan runs, which\nis what makes a saved one safe to pin in CI.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunSimulationInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulation.run({\n plan: {\n agentEndpoints: [{ id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' }],\n direction: 'INBOUND',\n maxSimulationDurationSeconds: 300,\n },\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.simulation.run(\n plan={\n \"agent_endpoints\": [{\n \"id\": \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\"\n }],\n \"direction\": \"INBOUND\",\n \"max_simulation_duration_seconds\": 300,\n },\n)\nprint(response.data)" } ] } }, "/v1/simulation/run-group": { "post": { "responses": { "201": { "description": "The run group, with its report requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SimulationRunGroup" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Insufficient credit" }, "example": { "type": "payment_required", "code": "insufficient_credits", "message": "Not enough credit to start this work. Add credit and try again." } } }, "description": "Payment Required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "A run or plan was not found in this project" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1SimulationRun-group", "tags": [ "Simulation" ], "summary": "Create a run group", "description": "Groups several simulation runs so they read as one, and starts generating the group report:\none document across every run, with a scorecard summed across them and the issues found,\neach merged from the per-run debriefs.\n\nSend `simulationRunPlanJobIds` to group runs that already exist (runs still in progress are\nfine: the report waits for them). Send `simulationRunPlanIds` to start one run of each plan\nand group those; this places real calls, exactly as starting each plan would.\n\nPoll GET /v1/simulation/run-group/{groupId} until `latestReport.status` is READY.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSimulationRunGroupInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationRunGroup = await client.simulationRunGroup.create();\n\nconsole.log(simulationRunGroup.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_run_group = client.simulation_run_group.create()\nprint(simulation_run_group.data)" } ] }, "get": { "responses": { "200": { "description": "Paginated list of run groups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSimulationRunGroupsResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1SimulationRun-group", "tags": [ "Simulation" ], "summary": "List run groups", "description": "Returns the run groups in the project, newest first, with their runs and where each group report stands. Read a report document from GET /v1/simulation/run-group/{groupId}.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of run groups to return (default: 20, max: 100)" } }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "default": 0, "description": "Pagination offset" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationRunGroups = await client.simulationRunGroup.list();\n\nconsole.log(simulationRunGroups.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_run_groups = client.simulation_run_group.list()\nprint(simulation_run_groups.data)" } ] } }, "/v1/simulation/run-group/{groupId}": { "get": { "responses": { "200": { "description": "The run group", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SimulationRunGroup" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Run group not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1SimulationRun-groupByGroupId", "tags": [ "Simulation" ], "summary": "Get a run group", "description": "Returns a run group with its runs in group order and its latest group report, including the report document once READY.", "parameters": [ { "name": "groupId", "in": "path", "required": true, "description": "The run group ID", "schema": { "type": "string", "format": "uuid" }, "example": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e" } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationRunGroup.getByID('5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.simulation_run_group.get_by_id(\n \"5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e\",\n)\nprint(response.data)" } ] }, "delete": { "responses": { "200": { "description": "Run group deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "description": "Whether the run group was deleted" } }, "required": [ "deleted" ] } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Run group not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1SimulationRun-groupByGroupId", "tags": [ "Simulation" ], "summary": "Delete a run group", "description": "Deletes a run group. Its runs, and their results, are untouched.", "parameters": [ { "name": "groupId", "in": "path", "required": true, "description": "The run group ID", "schema": { "type": "string", "format": "uuid" }, "example": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e" } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationRunGroup = await client.simulationRunGroup.delete(\n '5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e',\n);\n\nconsole.log(simulationRunGroup.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_run_group = client.simulation_run_group.delete(\n \"5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e\",\n)\nprint(simulation_run_group.data)" } ] } }, "/v1/simulation/run-group/{groupId}/report": { "post": { "responses": { "202": { "description": "The report generation, in flight", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SimulationRunGroupReport" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Run group not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1SimulationRun-groupByGroupIdReport", "tags": [ "Simulation" ], "summary": "Regenerate a run group report", "description": "Generates the group report again over the latest state of its runs. Returns the report generation; if one is already in flight it is returned instead of starting another. Poll GET /v1/simulation/run-group/{groupId} until `latestReport.status` is READY.", "parameters": [ { "name": "groupId", "in": "path", "required": true, "description": "The run group ID", "schema": { "type": "string", "format": "uuid" }, "example": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e" } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationRunGroup.regenerateReport(\n '5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e',\n);\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.simulation_run_group.regenerate_report(\n \"5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e\",\n)\nprint(response.data)" } ] } }, "/v1/simulation/group": { "get": { "responses": { "200": { "description": "Paginated list of simulation groups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSimulationGroupsResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1SimulationGroup", "tags": [ "Simulation" ], "summary": "List simulation groups", "description": "Returns the saved simulation groups in the project, most recently edited first, each with its plans in run order and notification settings.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of groups to return (default: 20, max: 100)" } }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "default": 0, "description": "Pagination offset" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationGroups = await client.simulationGroup.list();\n\nconsole.log(simulationGroups.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_groups = client.simulation_group.list()\nprint(simulation_groups.data)" } ] }, "post": { "responses": { "201": { "description": "The saved group", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SimulationGroup" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Invalid input, or Slack channels without Slack connected" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "A plan was not found in this project" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1SimulationGroup", "tags": [ "Simulation" ], "summary": "Create a simulation group", "description": "Saves a named set of plans to run together, again and again. Nothing runs yet:\nPOST /v1/simulation/group/{groupId}/run starts one run of every plan and groups them\ninto a run group with one combined report.\n\nSlack channels need Slack connected to the project. Email is on by default.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSimulationGroupInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationGroup = await client.simulationGroup.create({\n name: 'Release regression',\n simulationRunPlanIds: [\n '3c1d2e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f',\n '6d7e8f9a-0b1c-4d2e-9f3a-4b5c6d7e8f9a',\n ],\n});\n\nconsole.log(simulationGroup.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_group = client.simulation_group.create(\n name=\"Release regression\",\n simulation_run_plan_ids=[\"3c1d2e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f\", \"6d7e8f9a-0b1c-4d2e-9f3a-4b5c6d7e8f9a\"],\n)\nprint(simulation_group.data)" } ] } }, "/v1/simulation/group/{groupId}": { "get": { "responses": { "200": { "description": "The simulation group", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SimulationGroup" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Simulation group not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1SimulationGroupByGroupId", "tags": [ "Simulation" ], "summary": "Get a simulation group", "description": "Returns a saved simulation group with its plans in run order and notification settings.", "parameters": [ { "name": "groupId", "in": "path", "required": true, "description": "The simulation group ID", "schema": { "type": "string", "format": "uuid" }, "example": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d" } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationGroup.getByID('2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.simulation_group.get_by_id(\n \"2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d\",\n)\nprint(response.data)" } ] }, "put": { "responses": { "200": { "description": "The updated group", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SimulationGroup" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Invalid input, or Slack channels without Slack connected" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Simulation group or a plan not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "The group is managed by config as code" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1SimulationGroupByGroupId", "tags": [ "Simulation" ], "summary": "Update a simulation group", "description": "Edits a saved simulation group. Omitted fields keep their current value; `notifications`,\nwhen sent, replaces the settings as a whole. Run groups it already started keep theirs.\n\nA group managed by config as code (`configManaged: true`) returns 409: change it in the config file.", "parameters": [ { "name": "groupId", "in": "path", "required": true, "description": "The simulation group ID", "schema": { "type": "string", "format": "uuid" }, "example": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSimulationGroupInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationGroup = await client.simulationGroup.update('2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d');\n\nconsole.log(simulationGroup.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_group = client.simulation_group.update(\n group_id=\"2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d\",\n)\nprint(simulation_group.data)" } ] }, "delete": { "responses": { "200": { "description": "Simulation group deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "description": "Whether the group was deleted" } }, "required": [ "deleted" ] } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Simulation group not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "The group is managed by config as code" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1SimulationGroupByGroupId", "tags": [ "Simulation" ], "summary": "Delete a simulation group", "description": "Deletes a saved simulation group and any schedules that run it. Run groups it already started, and their reports, stay. A group managed by config as code returns 409.", "parameters": [ { "name": "groupId", "in": "path", "required": true, "description": "The simulation group ID", "schema": { "type": "string", "format": "uuid" }, "example": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d" } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationGroup = await client.simulationGroup.delete('2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d');\n\nconsole.log(simulationGroup.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_group = client.simulation_group.delete(\n \"2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d\",\n)\nprint(simulation_group.data)" } ] } }, "/v1/simulation/group/{groupId}/run": { "post": { "responses": { "201": { "description": "The run group the run started", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SimulationRunGroup" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "A plan could not start (the started runs are still grouped)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Insufficient credit" }, "example": { "type": "payment_required", "code": "insufficient_credits", "message": "Not enough credit to start this work. Add credit and try again." } } }, "description": "Payment Required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Simulation group or one of its plans not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1SimulationGroupByGroupIdRun", "tags": [ "Simulation" ], "summary": "Run a simulation group", "description": "Starts one run of every plan in the group, exactly as POST /v1/simulation/plan/{planId}/job\nwould for each, and groups the runs into a run group whose combined report is announced\nthrough the group's notification settings once it is ready. This places real calls.\nConfig-managed groups can be run here too.\n\nReturns the run group. Poll GET /v1/simulation/run-group/{groupId} until\n`latestReport.status` is READY.\n\nIf a plan cannot start after others did, the runs that started are still grouped and the\n400 names the run group id.", "parameters": [ { "name": "groupId", "in": "path", "required": true, "description": "The simulation group ID", "schema": { "type": "string", "format": "uuid" }, "example": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d" } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationGroup.run('2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.simulation_group.run(\n \"2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d\",\n)\nprint(response.data)" } ] } }, "/v1/simulation/environment": { "get": { "responses": { "200": { "description": "List of environments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEnvironmentsResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1SimulationEnvironment", "tags": [ "Simulation Environment" ], "summary": "List environments", "description": "Returns a paginated list of environments: the project's own plus the environments Roark curates and shares across every project. Reference one by id when setting a customer flow variant's environment.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "in": "query", "name": "after", "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationEnvironments = await client.simulationEnvironment.list();\n\nconsole.log(simulationEnvironments.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_environments = client.simulation_environment.list()\nprint(simulation_environments.data)" } ] }, "post": { "responses": { "201": { "description": "The created environment", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EnvironmentResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1SimulationEnvironment", "tags": [ "Simulation Environment" ], "summary": "Create an environment", "description": "Creates an environment for the project: a noise bed and the level it plays at. Reference it by id when setting a customer flow variant's environment. Roark's curated presets always play at the default level, so this is how a project gets the same bed louder or quieter.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnvironmentInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationEnvironment = await client.simulationEnvironment.create({\n backgroundNoise: 'OFFICE',\n name: 'Busy call centre',\n});\n\nconsole.log(simulationEnvironment.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_environment = client.simulation_environment.create(\n background_noise=\"OFFICE\",\n name=\"Busy call centre\",\n)\nprint(simulation_environment.data)" } ] } }, "/v1/simulation/environment/{environmentId}": { "get": { "responses": { "200": { "description": "The requested environment", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EnvironmentResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1SimulationEnvironmentByEnvironmentId", "tags": [ "Simulation Environment" ], "summary": "Get environment by ID", "description": "Returns a single environment by its ID.", "parameters": [ { "in": "path", "name": "environmentId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationEnvironment.getByID('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.simulation_environment.get_by_id(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] }, "put": { "responses": { "200": { "description": "The updated environment", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EnvironmentResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1SimulationEnvironmentByEnvironmentId", "tags": [ "Simulation Environment" ], "summary": "Update an environment", "description": "Updates one of the project's environments. Only the fields sent are changed. Runs already built keep the snapshot they were built with. Roark-curated environments cannot be edited (403).", "parameters": [ { "in": "path", "name": "environmentId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEnvironmentInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationEnvironment = await client.simulationEnvironment.update(\n '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n);\n\nconsole.log(simulationEnvironment.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_environment = client.simulation_environment.update(\n environment_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(simulation_environment.data)" } ] }, "delete": { "responses": { "200": { "description": "The environment was deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeleteEnvironmentResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1SimulationEnvironmentByEnvironmentId", "tags": [ "Simulation Environment" ], "summary": "Delete an environment", "description": "Soft-deletes one of the project's environments. It disappears from reads and cannot be picked for new runs; runs already built keep their snapshot. Refused (409) while a live customer flow variant still uses it: move those variants first. Roark-curated environments cannot be deleted (403).", "parameters": [ { "in": "path", "name": "environmentId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationEnvironment = await client.simulationEnvironment.delete(\n '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n);\n\nconsole.log(simulationEnvironment.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_environment = client.simulation_environment.delete(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(simulation_environment.data)" } ] } }, "/v1/simulation/plan": { "get": { "responses": { "200": { "description": "Paginated list of run plans", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRunPlansResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1SimulationPlan", "tags": [ "Simulation Run Plan" ], "summary": "List run plans", "description": "Returns a paginated list of simulation run plans. Optionally filter by search text or agent ID.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20, "description": "Maximum number of run plans to return (default: 20, max: 50)", "example": 20 } }, { "in": "query", "name": "after", "schema": { "type": "string", "description": "Cursor for pagination - use the nextCursor value from a previous response" } }, { "in": "query", "name": "searchText", "schema": { "type": "string", "description": "Search text to filter run plans by name" } }, { "in": "query", "name": "agentId", "schema": { "type": "string", "format": "uuid", "description": "Filter run plans by agent ID" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationRunPlans = await client.simulationRunPlan.list();\n\nconsole.log(simulationRunPlans.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_run_plans = client.simulation_run_plan.list()\nprint(simulation_run_plans.data)" } ] }, "post": { "responses": { "201": { "description": "The created run plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateRunPlanResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1SimulationPlan", "tags": [ "Simulation Run Plan" ], "summary": "Create a run plan", "description": "Creates a new simulation run plan.\n\nTo run a simulation, use POST /v1/simulation/run instead: it starts a run from a plan or\nfrom an inline configuration, and takes runtime variables. Create a plan here when you want\na reusable, named one to run later.\n\nSend `template` instead of a full configuration to save one of the built-in templates as a\nplan. It takes the same fields as the template variant of POST /v1/simulation/run, builds the\nsame plan, and never starts it.\n\nTo compare one property, attach the flow once and send `comparisonProperty` with the\n`comparisonValues` to run: the plan attaches the flow once per value.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRunPlanInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationRunPlan = await client.simulationRunPlan.create({\n agentEndpoints: [{ id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' }],\n direction: 'INBOUND',\n maxSimulationDurationSeconds: 300,\n name: 'My Run Plan',\n});\n\nconsole.log(simulationRunPlan.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_run_plan = client.simulation_run_plan.create(\n agent_endpoints=[{\n \"id\": \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\"\n }],\n direction=\"INBOUND\",\n max_simulation_duration_seconds=300,\n name=\"My Run Plan\",\n)\nprint(simulation_run_plan.data)" } ] } }, "/v1/simulation/plan/{planId}": { "put": { "responses": { "200": { "description": "The updated run plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RunPlanResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1SimulationPlanByPlanId", "tags": [ "Simulation Run Plan" ], "summary": "Update a run plan", "description": "Updates an existing simulation run plan by its ID.", "parameters": [ { "name": "planId", "in": "path", "required": true, "description": "The ID of the run plan to update", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRunPlanInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationRunPlan = await client.simulationRunPlan.update(\n '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n);\n\nconsole.log(simulationRunPlan.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_run_plan = client.simulation_run_plan.update(\n plan_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(simulation_run_plan.data)" } ] }, "delete": { "responses": { "200": { "description": "Run plan deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "description": "Whether the run plan was deleted" } }, "required": [ "deleted" ] } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "Conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1SimulationPlanByPlanId", "tags": [ "Simulation Run Plan" ], "summary": "Delete a run plan", "description": "Soft-deletes a simulation run plan by its ID.", "parameters": [ { "name": "planId", "in": "path", "required": true, "description": "The ID of the run plan to delete", "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationRunPlan = await client.simulationRunPlan.delete(\n '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n);\n\nconsole.log(simulationRunPlan.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_run_plan = client.simulation_run_plan.delete(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(simulation_run_plan.data)" } ] }, "get": { "responses": { "200": { "description": "The requested run plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RunPlanResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1SimulationPlanByPlanId", "tags": [ "Simulation Run Plan" ], "summary": "Get run plan by ID", "description": "Returns a specific simulation run plan by its ID.", "parameters": [ { "name": "planId", "in": "path", "required": true, "description": "The ID of the run plan to retrieve", "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationRunPlan.getByID('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.simulation_run_plan.get_by_id(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] } }, "/v1/simulation/plan/jobs": { "get": { "responses": { "200": { "description": "Paginated list of simulation plan jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSimulationPlanJobsResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1SimulationPlanJobs", "tags": [ "Simulation Run Plan Job" ], "summary": "List simulation plan jobs", "description": "Returns a paginated list of simulation run plan jobs. Filter by status, plan ID, or label to find specific simulation batches.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20, "description": "Maximum number of plan jobs to return (default: 20, max: 50)", "example": 20 } }, { "in": "query", "name": "after", "schema": { "type": "string", "format": "uuid", "description": "Cursor for pagination - use the nextCursor value from a previous response", "example": "550e8400-e29b-41d4-a716-446655440000" } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "PENDING", "QUEUED", "CREATING_SNAPSHOTS", "CREATING_SIMULATIONS", "PREPARING_CAPACITY", "RUNNING_SIMULATIONS", "COMPLETED", "FAILED", "TIMED_OUT", "CANCELLED", "CANCELLING", "ENDING_SIMULATIONS" ], "description": "Filter by plan job status (PENDING, QUEUED, CREATING_SNAPSHOTS, CREATING_SIMULATIONS, PREPARING_CAPACITY, RUNNING_SIMULATIONS, COMPLETED, FAILED, TIMED_OUT, CANCELLED, CANCELLING, ENDING_SIMULATIONS)", "example": "COMPLETED" } }, { "in": "query", "name": "simulationRunPlanId", "schema": { "type": "string", "format": "uuid", "description": "Filter by simulation run plan ID", "example": "550e8400-e29b-41d4-a716-446655440000" } }, { "in": "query", "name": "labelId", "schema": { "type": "string", "format": "uuid", "description": "Filter by label ID attached to the plan job. Use this if you know the label ID.", "example": "550e8400-e29b-41d4-a716-446655440000" } }, { "in": "query", "name": "labelName", "schema": { "type": "string", "description": "Filter by label name attached to the plan job. More user-friendly alternative to labelId. Case-insensitive.", "example": "production-ready" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationRunPlanJobs = await client.simulationRunPlanJob.list();\n\nconsole.log(simulationRunPlanJobs.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_run_plan_jobs = client.simulation_run_plan_job.list()\nprint(simulation_run_plan_jobs.data)" } ] } }, "/v1/simulation/plan/job/{jobId}": { "get": { "responses": { "200": { "description": "Successfully retrieved simulation plan job", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GetSimulationPlanJobResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Simulation plan job not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1SimulationPlanJobByJobId", "tags": [ "Simulation Run Plan Job" ], "summary": "Get simulation plan job", "description": "Retrieve details of a simulation plan job including all associated simulation jobs (calls)", "parameters": [ { "in": "path", "name": "jobId", "schema": { "type": "string", "format": "uuid" }, "required": true, "example": "7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f", "description": "Simulation run plan job ID" } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationRunPlanJob.getByID('7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.simulation_run_plan_job.get_by_id(\n \"7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f\",\n)\nprint(response.data)" } ] } }, "/v1/simulation/plan/job/{jobId}/cancel": { "post": { "responses": { "200": { "description": "The run is cancelled, or had already finished", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CancelSimulationPlanJobResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Simulation plan job not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1SimulationPlanJobByJobIdCancel", "tags": [ "Simulation Run Plan Job" ], "summary": "Cancel a simulation plan job", "description": "Stops a run that has not finished yet. Already-finished runs are left alone.\n\nIntended for CI: when a pipeline is cancelled or superseded, cancelling the run stops it\nplacing calls you no longer need. Safe to call more than once.", "parameters": [ { "in": "path", "name": "jobId", "schema": { "type": "string", "format": "uuid" }, "required": true, "example": "7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f", "description": "Simulation run plan job ID" } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationRunPlanJob.cancel('7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.simulation_run_plan_job.cancel(\n \"7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f\",\n)\nprint(response.data)" } ] } }, "/v1/simulation/plan/{planId}/job": { "post": { "responses": { "200": { "description": "Successfully triggered simulation run plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RunSimulationPlanResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Insufficient credit" }, "example": { "type": "payment_required", "code": "insufficient_credits", "message": "Not enough credit to start this work. Add credit and try again." } } }, "description": "Payment Required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Simulation run plan not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1SimulationPlanByPlanIdJob", "tags": [ "Simulation Run Plan Job" ], "deprecated": true, "summary": "Run a simulation plan", "description": "Deprecated: use POST /v1/simulation/run, which does the same thing and can also take the\nplan configuration inline, so a one-off run does not have to create a plan first.\n\nCreates and executes a job for an existing simulation run plan. Optionally provide runtime\nvariables to override plan-defined variables.", "parameters": [ { "in": "path", "name": "planId", "schema": { "type": "string", "format": "uuid" }, "required": true, "example": "7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f", "description": "Simulation run plan ID" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunSimulationPlanBody" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationRunPlanJob.start('7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.simulation_run_plan_job.start(\n plan_id=\"7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f\",\n)\nprint(response.data)" } ] } }, "/v1/simulation/plan/job/{jobId}/results": { "get": { "responses": { "200": { "description": "The run’s results", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SimulationRunResults" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Simulation run, or the `compareToJobId` run, not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1SimulationPlanJobByJobIdResults", "tags": [ "Simulation Run Plan Job" ], "summary": "Get simulation run results", "description": "Everything the run report shows, in one request: the summary and score, the pass/fail verdict,\nper-metric aggregates, every simulation with its check results, breakdowns by agent and persona,\nthe comparison against the previous run (or `compareToJobId`), the sweep attribution, and the\nwritten debrief with its executive summary, failure themes and recommendations.\n\nSafe to call while the run is in progress: counts reflect what has landed so far. `verdict` and\n`sweepAttribution` stay null until the run ends. The debrief is generated automatically a few\nminutes after a run with graded calls settles; poll until `debrief.status` is READY, or request\none with POST /v1/simulation/plan/job/{jobId}/debrief.", "parameters": [ { "in": "query", "name": "compareToJobId", "schema": { "type": "string", "format": "uuid", "description": "Simulation run plan job to compare this run against, e.g. the last run on your main branch. Defaults to the plan's previous settled run. Any run in the project works, including another plan's: checks are matched by metric, and a check only one run graded reads null on the other side.", "example": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" } }, { "schema": { "type": "string" }, "in": "path", "name": "jobId", "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationRunPlanJob.getResults('jobId');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.simulation_run_plan_job.get_results(\n job_id=\"jobId\",\n)\nprint(response.data)" } ] } }, "/v1/simulation/plan/job/{jobId}/debrief": { "post": { "responses": { "202": { "description": "The debrief, as requested or as it already stands", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SimulationRunDebrief" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Simulation run not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "The run has not finished yet" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1SimulationPlanJobByJobIdDebrief", "tags": [ "Simulation Run Plan Job" ], "summary": "Generate simulation run debrief", "description": "Request the written debrief for a settled run: executive summary, failure themes and recommendations.\nRuns with graded calls get one automatically, so this is for regenerating one (`regenerate: true`)\nor retrying one that failed.\n\nReturns immediately. Generation takes a few minutes: poll GET\n/v1/simulation/plan/job/{jobId}/results until `debrief.status` is READY or FAILED.\nWithout `regenerate`, a debrief that is ready or already being written is returned as-is.", "parameters": [ { "in": "path", "name": "jobId", "schema": { "type": "string", "format": "uuid", "description": "Simulation run plan job ID" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateSimulationRunDebriefInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationRunPlanJob.createDebrief(\n '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n);\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.simulation_run_plan_job.create_debrief(\n job_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] } }, "/v1/simulation/plan/job/{jobId}/cost": { "get": { "responses": { "200": { "description": "The run’s cost", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SimulationRunCost" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Simulation run not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1SimulationPlanJobByJobIdCost", "tags": [ "Simulation Run Plan Job" ], "summary": "Get simulation run cost", "description": "The billable spend for one simulation run (run plan job), split by cost type, with the spend of each simulated call in it. Safe to call while the run is in progress: totals reflect the costs recorded so far. Amounts are billable spend only, in exact micro-dollars (`*UsdMicros`) and dollars (`*Usd`, for display). Requires an API key with the `billing:read` permission.", "parameters": [ { "in": "path", "name": "jobId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationRunPlanJob.getCost('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.simulation_run_plan_job.get_cost(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] } }, "/v1/simulation/template": { "get": { "responses": { "200": { "description": "The built-in simulation templates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSimulationTemplatesResponse" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1SimulationTemplate", "tags": [ "Simulation Template" ], "summary": "List simulation templates", "description": "Returns the built-in simulation templates, each resolved against this project: the metric and\ncheck definitions it collects, and the flows it runs with the variants it covers.\n\nA template is a preset rather than a stored object, so building a run from one produces an\nordinary run plan you own and can edit afterwards. Pass a `slug` as `template` to\nPOST /v1/simulation/run.\n\nEvery entry is complete, so there is no per-template endpoint to follow up with, and the list\nis a fixed catalogue rather than a paginated one. Only templates a request can actually run\nare listed.", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationTemplates = await client.simulationTemplate.list();\n\nconsole.log(simulationTemplates.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_templates = client.simulation_template.list()\nprint(simulation_templates.data)" } ] } }, "/v1/simulation/job/lookup": { "get": { "responses": { "200": { "description": "Successfully found simulation job", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SimulationJobResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "No active lease or associated job found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1SimulationJobLookup", "tags": [ "Simulation Job" ], "summary": "Lookup by phone number", "description": "Find the matching simulation using the number used by the Roark simulation agent.", "parameters": [ { "in": "query", "name": "roarkPhoneNumber", "schema": { "type": "string" }, "required": true, "example": "+15551234567", "description": "Phone number provisioned by Roark for the simulation job in E.164 format. In the case of an inbound simulation, this is the number that calls your agent; in the case of an outbound simulation, this is the number you call from your agent." }, { "in": "query", "name": "callReceivedAt", "schema": { "type": "string", "format": "date-time" }, "required": false, "example": "2024-01-15T10:30:00Z", "description": "ISO 8601 timestamp of when the call was received. Alternatively, any time between the start and end of the call is valid. Defaults to the current time, which fetches any jobs that are currently ongoing." } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationJob.lookup({ roarkPhoneNumber: 'roarkPhoneNumber' });\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.simulation_job.lookup(\n roark_phone_number=\"roarkPhoneNumber\",\n)\nprint(response.data)" } ] } }, "/v1/simulation/job/{jobId}": { "get": { "responses": { "200": { "description": "Successfully found simulation job", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SimulationJobResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Simulation job not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1SimulationJobByJobId", "tags": [ "Simulation Job" ], "summary": "Get simulation by ID", "description": "Get a individual simulation run directly by its ID. This is generally part of a larger simulation run plan job.", "parameters": [ { "in": "path", "name": "jobId", "schema": { "type": "string", "format": "uuid" }, "required": true, "example": "7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f", "description": "Simulation job ID" } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulationJob.getByID('7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.simulation_job.get_by_id(\n \"7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f\",\n)\nprint(response.data)" } ] } }, "/v1/simulation/job/{jobId}/tool-mock": { "get": { "responses": { "200": { "description": "The mocked invocations, oldest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationToolMockRecord" } } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Simulation job not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1SimulationJobByJobIdTool-mock", "tags": [ "Simulation Job" ], "summary": "List mocked tool invocations", "description": "Every guarded tool invocation Roark answered during this simulation: what the agent tried to call, with what arguments, and the simulated response it received. Use this to assert tool behavior in CI after a test call, with zero real side effects. Empty when the agent's tools are not guarded (see the tool guard docs).", "parameters": [ { "in": "path", "name": "jobId", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "Simulation job ID" } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationJobToolMocks = await client.simulationJobToolMock.list(\n '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n);\n\nconsole.log(simulationJobToolMocks.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_job_tool_mocks = client.simulation_job_tool_mock.list(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(simulation_job_tool_mocks.data)" } ] } }, "/v1/simulation/tool-mock": { "post": { "responses": { "200": { "description": "The simulated tool response. Return `result` from your tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SimulationToolMockResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "No simulation with this id is known to this project." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "The simulation has ended. Do not execute the real tool; use your static fallback." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1SimulationTool-mock", "tags": [ "Simulation" ], "summary": "Mock a tool call during a test call", "description": "The server half of the tool guard for code-first agents. When a guarded tool fires during a Roark test call, send the invocation here instead of executing it: Roark answers with a simulated backend response that is valid JSON, shaped by the tool contract you pass, consistent with the test scenario, and consistent with earlier mocked responses in the same call. Real callers are never affected: the guard only diverts when the agent-config resolve response identified the session as a Roark simulation, and this endpoint independently re-validates the simulation before answering.\n\nFailure contract for your wrapper: `404` means the simulation id is unknown to this project (treat the session as real). `409` means the simulation has already ended (stale session state: do NOT execute the real tool; return your static fallback). `5xx` means generation failed (return your static fallback).\n\nIdentical retries (same tool, same arguments) within a few minutes return the stored response, so double-fired handlers stay consistent.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulationToolMockRequest" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.simulation.mockTool({\n simulationJobId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n toolName: 'book_appointment',\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.simulation.mock_tool(\n simulation_job_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n tool_name=\"book_appointment\",\n)\nprint(response.data)" } ] } }, "/v1/simulation/tool-fixture": { "get": { "responses": { "200": { "description": "The fixtures.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationToolFixture" } } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1SimulationTool-fixture", "tags": [ "Simulation" ], "summary": "List tool fixtures", "description": "All deterministic tool responses configured for this project, optionally filtered by tool.", "parameters": [ { "name": "toolName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only fixtures for this tool." } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationToolFixtures = await client.simulationToolFixture.list();\n\nconsole.log(simulationToolFixtures.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_tool_fixtures = client.simulation_tool_fixture.list()\nprint(simulation_tool_fixtures.data)" } ] }, "post": { "responses": { "200": { "description": "The fixture as stored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SimulationToolFixture" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "The referenced flow variant does not exist in this project." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1SimulationTool-fixture", "tags": [ "Simulation" ], "summary": "Set a tool fixture", "description": "Create-or-replace by scope: one fixture per tool project-wide, plus one per (tool, flow variant). Setting the same scope twice replaces the response, so CI can apply fixtures idempotently. During Roark test calls the tool guard answers with the fixture verbatim instead of generating a response; real callers are never affected.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertSimulationToolFixtureRequest" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationToolFixture = await client.simulationToolFixture.create({\n toolName: 'lookup_availability',\n});\n\nconsole.log(simulationToolFixture.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_tool_fixture = client.simulation_tool_fixture.create(\n tool_name=\"lookup_availability\",\n)\nprint(simulation_tool_fixture.data)" } ] } }, "/v1/simulation/tool-fixture/{fixtureId}": { "put": { "responses": { "200": { "description": "The updated fixture.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SimulationToolFixture" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1SimulationTool-fixtureByFixtureId", "tags": [ "Simulation" ], "summary": "Update a tool fixture", "description": "Change the response, description, or enabled state of an existing fixture.", "parameters": [ { "name": "fixtureId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSimulationToolFixtureRequest" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationToolFixture = await client.simulationToolFixture.update(\n '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n);\n\nconsole.log(simulationToolFixture.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_tool_fixture = client.simulation_tool_fixture.update(\n fixture_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(simulation_tool_fixture.data)" } ] }, "delete": { "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1SimulationTool-fixtureByFixtureId", "tags": [ "Simulation" ], "summary": "Delete a tool fixture", "description": "The tool goes back to scenario-aware generated responses in test calls.", "parameters": [ { "name": "fixtureId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst simulationToolFixture = await client.simulationToolFixture.delete(\n '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n);\n\nconsole.log(simulationToolFixture.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nsimulation_tool_fixture = client.simulation_tool_fixture.delete(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(simulation_tool_fixture.data)" } ] } }, "/v1/customer-flow": { "get": { "responses": { "200": { "description": "List of customer flows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCustomerFlowsResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Customer-flow", "tags": [ "Customer Flow" ], "summary": "List customer flows", "description": "Returns a paginated list of customer flows with their agents, expectations, happy path and edge cases. The step graph is the one field omitted: reading it walks the project's whole step graph, so it comes back from the single-flow endpoint instead. Customer flows are how a project describes what to test; they replace the older simulation scenarios.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "in": "query", "name": "after", "schema": { "type": "string" } }, { "in": "query", "name": "searchText", "schema": { "type": "string" } }, { "in": "query", "name": "type", "schema": { "type": "string", "enum": [ "SCRIPTED", "IMPROV", "VOICEMAIL" ] } }, { "in": "query", "name": "includeSystem", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst customerFlows = await client.customerFlow.list();\n\nconsole.log(customerFlows.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\ncustomer_flows = client.customer_flow.list()\nprint(customer_flows.data)" } ] }, "post": { "responses": { "201": { "description": "The created customer flow", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomerFlow" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1Customer-flow", "tags": [ "Customer Flow" ], "summary": "Create a customer flow", "description": "Creates a customer flow. A SCRIPTED flow carries a step graph and gets one way of running it per path through the graph; an IMPROV flow carries the briefs you send. Customer flows replace the older simulation scenarios, so build a flow for anything new.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerFlowInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst customerFlow = await client.customerFlow.create({\n graph: [{ type: 'AGENT_TURN' }],\n title: 'Reschedule an appointment',\n type: 'SCRIPTED',\n});\n\nconsole.log(customerFlow.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\ncustomer_flow = client.customer_flow.create(\n graph=[{\n \"type\": \"AGENT_TURN\"\n }],\n title=\"Reschedule an appointment\",\n type=\"SCRIPTED\",\n)\nprint(customer_flow.data)" } ] } }, "/v1/customer-flow/{flowId}": { "get": { "responses": { "200": { "description": "The requested customer flow", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomerFlow" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Customer-flowByFlowId", "tags": [ "Customer Flow" ], "summary": "Get customer flow by ID", "description": "Returns a customer flow with its happy path, edge cases, expectations and linked agents. Scripted flows also carry their step graph.", "parameters": [ { "in": "path", "name": "flowId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.customerFlow.getByID('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.customer_flow.get_by_id(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] }, "put": { "responses": { "200": { "description": "The updated customer flow", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomerFlow" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1Customer-flowByFlowId", "tags": [ "Customer Flow" ], "summary": "Update a customer flow", "description": "Updates a flow's title, description, branching mode, linked agents or flow-level expectations. The step graph is replaced through PUT /graph.", "parameters": [ { "in": "path", "name": "flowId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerFlowInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst customerFlow = await client.customerFlow.update('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(customerFlow.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\ncustomer_flow = client.customer_flow.update(\n flow_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(customer_flow.data)" } ] }, "delete": { "responses": { "200": { "description": "Customer flow deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "description": "Whether the flow was deleted" } }, "required": [ "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1Customer-flowByFlowId", "tags": [ "Customer Flow" ], "summary": "Delete a customer flow", "description": "Soft-deletes a customer flow along with its edge cases, expectations and (for scripted flows) its step graph. Run plans that linked it drop it from their test cases.", "parameters": [ { "in": "path", "name": "flowId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst customerFlow = await client.customerFlow.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(customerFlow.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\ncustomer_flow = client.customer_flow.delete(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(customer_flow.data)" } ] } }, "/v1/customer-flow/{flowId}/graph": { "put": { "responses": { "200": { "description": "The flow graph after the write", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReplaceFlowStepsResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "The write drops branches that currently rejoin. Set allowUnmerge to confirm." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1Customer-flowByFlowIdGraph", "tags": [ "Customer Flow" ], "summary": "Replace a scripted flow's steps", "description": "Replaces a scripted flow's conversation graph with the tree you send. This is a full replace, not a merge:\na step you omit is removed.\n\nInclude `nodeId` on a step to update the existing one, omit it to create a new step. Where two branches\nrejoin, keep the `mergeIntoNodeIds` references a read gave you. Dropping them un-merges those branches\nand is refused unless `allowUnmerge` is set.\n\nA change to the set of paths re-seeds how the flow runs, which the response reports as\n`variantsReshaped` along with the resulting happy path and edge cases.", "parameters": [ { "in": "path", "name": "flowId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceFlowStepsInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.customerFlow.replaceGraph('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n graph: [{ type: 'AGENT_TURN' }],\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.customer_flow.replace_graph(\n flow_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n graph=[{\n \"type\": \"AGENT_TURN\"\n }],\n)\nprint(response.data)" } ] } }, "/v1/customer-flow/{flowId}/happy-path": { "put": { "responses": { "200": { "description": "The updated happy path", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FlowVariant" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1Customer-flowByFlowIdHappy-path", "tags": [ "Customer Flow" ], "summary": "Update a flow's happy path", "description": "Updates the happy path's title, persona, environment, brief or expectations. Omitted fields are left\nalone; `additionalExpectations` replaces the set wholesale rather than appending.\n\nIts persona and environment are what the edge cases inherit, so changing them here changes every edge\ncase that does not name its own.", "parameters": [ { "in": "path", "name": "flowId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFlowVariantInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.customerFlow.updateHappyPath('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.customer_flow.update_happy_path(\n flow_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] } }, "/v1/customer-flow/{flowId}/duplicate": { "post": { "responses": { "201": { "description": "The duplicated customer flow", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomerFlow" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1Customer-flowByFlowIdDuplicate", "tags": [ "Customer Flow" ], "summary": "Duplicate a customer flow", "description": "Deep-copies a flow into a new project-owned flow. The copy carries the source's description, branching mode, linked agents, flow-level expectations and flow-owned metrics. A scripted flow copies its whole step graph; an improv flow copies its variants (personas, briefs, expectations). Duplicating a Roark-managed flow is how you customise it. Voicemail flows are Roark-managed and cannot be duplicated.", "parameters": [ { "in": "path", "name": "flowId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateCustomerFlowInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.customerFlow.duplicate('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.customer_flow.duplicate(\n flow_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] } }, "/v1/customer-flow/{flowId}/edge-case": { "post": { "responses": { "201": { "description": "The edge case that was added", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FlowVariant" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1Customer-flowByFlowIdEdge-case", "tags": [ "Customer Flow Edge Case" ], "summary": "Add an edge case", "description": "Adds a variant to an IMPROV flow.\n\nA scripted flow's variants are owned by the path engine, one per path through the graph, so they are\ncreated by editing the graph through PUT /v1/customer-flow/{flowId}/graph rather than here.\n\nLeave personaOverrideId or environmentId unset to inherit the happy path's.", "parameters": [ { "in": "path", "name": "flowId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddFlowEdgeCaseInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.customerFlowEdgeCase.add('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n title: 'x',\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.customer_flow_edge_case.add(\n flow_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n title=\"x\",\n)\nprint(response.data)" } ] } }, "/v1/customer-flow/{flowId}/edge-case/{edgeCaseId}": { "put": { "responses": { "200": { "description": "The updated edge case", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FlowVariant" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1Customer-flowByFlowIdEdge-caseByEdgeCaseId", "tags": [ "Customer Flow Edge Case" ], "summary": "Update an edge case", "description": "Updates an edge case's title, persona, environment, brief, preceded-by link or expectations. Omitted fields are left alone; `additionalExpectations` replaces the set wholesale rather than appending. Promoting it to the happy path is a separate call, since that also demotes the incumbent.", "parameters": [ { "in": "path", "name": "flowId", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "edgeCaseId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFlowVariantInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst customerFlowEdgeCase = await client.customerFlowEdgeCase.update(\n '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n { flowId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' },\n);\n\nconsole.log(customerFlowEdgeCase.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\ncustomer_flow_edge_case = client.customer_flow_edge_case.update(\n edge_case_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n flow_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(customer_flow_edge_case.data)" } ] }, "delete": { "responses": { "200": { "description": "Edge case removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "description": "Whether the variant was deleted" } }, "required": [ "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1Customer-flowByFlowIdEdge-caseByEdgeCaseId", "tags": [ "Customer Flow Edge Case" ], "summary": "Remove an edge case", "description": "Soft-deletes a variant. On a scripted flow the path engine re-creates a variant for any path still in the graph, so remove the path through PUT /graph instead if that is what you meant.", "parameters": [ { "in": "path", "name": "flowId", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "edgeCaseId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst customerFlowEdgeCase = await client.customerFlowEdgeCase.remove(\n '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n { flowId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' },\n);\n\nconsole.log(customerFlowEdgeCase.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\ncustomer_flow_edge_case = client.customer_flow_edge_case.remove(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n flow_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(customer_flow_edge_case.data)" } ] } }, "/v1/customer-flow/{flowId}/edge-case/{edgeCaseId}/promote": { "post": { "responses": { "200": { "description": "The edge case, now the happy path", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FlowVariant" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1Customer-flowByFlowIdEdge-caseByEdgeCaseIdPromote", "tags": [ "Customer Flow Edge Case" ], "summary": "Promote an edge case to the happy path", "description": "Makes this edge case the flow's happy path, and the outgoing happy path an edge case. Its persona and environment are baked into it first, so edge cases that were inheriting keep the configuration they had.", "parameters": [ { "in": "path", "name": "flowId", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "edgeCaseId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.customerFlowEdgeCase.promote('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n flowId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.customer_flow_edge_case.promote(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n flow_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] } }, "/v1/http-request-definition": { "get": { "responses": { "200": { "description": "List of HTTP request definitions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HttpRequestDefinitionResponse" } }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of items" }, "hasMore": { "type": "boolean", "description": "Whether there are more items to fetch" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page of items" } }, "required": [ "total", "hasMore", "nextCursor" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Http-request-definition", "tags": [ "HTTP Request Definition" ], "summary": "List HTTP request definitions", "description": "Returns a paginated list of HTTP request definitions for the authenticated project.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20, "description": "Maximum number of definitions to return (default: 20, max: 50)" } }, { "in": "query", "name": "after", "schema": { "type": "string", "description": "Cursor for pagination - definition ID to start after" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst httpRequestDefinitions = await client.httpRequestDefinition.list();\n\nconsole.log(httpRequestDefinitions.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nhttp_request_definitions = client.http_request_definition.list()\nprint(http_request_definitions.data)" } ] }, "post": { "responses": { "201": { "description": "The created HTTP request definition with signing secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HttpRequestDefinitionCreateResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1Http-request-definition", "tags": [ "HTTP Request Definition" ], "summary": "Create HTTP request definition", "description": "Creates a new HTTP request definition. The signing secret is only returned in this response and cannot be retrieved later.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHttpRequestDefinitionInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst httpRequestDefinition = await client.httpRequestDefinition.create({\n scope: 'AGENT_OUTBOUND_DIAL',\n url: 'https://example.com',\n});\n\nconsole.log(httpRequestDefinition.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nhttp_request_definition = client.http_request_definition.create(\n scope=\"AGENT_OUTBOUND_DIAL\",\n url=\"https://example.com\",\n)\nprint(http_request_definition.data)" } ] } }, "/v1/http-request-definition/{definitionId}": { "get": { "responses": { "200": { "description": "The requested HTTP request definition", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HttpRequestDefinitionResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Http-request-definitionByDefinitionId", "tags": [ "HTTP Request Definition" ], "summary": "Get HTTP request definition by ID", "description": "Returns a specific HTTP request definition by its ID.", "parameters": [ { "name": "definitionId", "in": "path", "required": true, "description": "The ID of the HTTP request definition to retrieve", "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.httpRequestDefinition.getByID('definitionId');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.http_request_definition.get_by_id(\n \"definitionId\",\n)\nprint(response.data)" } ] }, "put": { "responses": { "200": { "description": "The updated HTTP request definition", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HttpRequestDefinitionResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1Http-request-definitionByDefinitionId", "tags": [ "HTTP Request Definition" ], "summary": "Update HTTP request definition", "description": "Updates an existing HTTP request definition.", "parameters": [ { "name": "definitionId", "in": "path", "required": true, "description": "The ID of the HTTP request definition to update", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateHttpRequestDefinitionInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst httpRequestDefinition = await client.httpRequestDefinition.update('definitionId');\n\nconsole.log(httpRequestDefinition.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nhttp_request_definition = client.http_request_definition.update(\n definition_id=\"definitionId\",\n)\nprint(http_request_definition.data)" } ] } }, "/v1/webhook": { "get": { "responses": { "200": { "description": "List of webhooks with their event subscriptions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookResponse" } }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of items" }, "hasMore": { "type": "boolean", "description": "Whether there are more items to fetch" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page of items" } }, "required": [ "total", "hasMore", "nextCursor" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Webhook", "tags": [ "Webhook" ], "summary": "List webhooks", "description": "Returns a paginated list of webhooks with their event subscriptions.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20, "description": "Maximum number of webhooks to return (default: 20, max: 50)" } }, { "in": "query", "name": "after", "schema": { "type": "string", "description": "Cursor for pagination - webhook ID to start after" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst webhooks = await client.webhook.list();\n\nconsole.log(webhooks.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nwebhooks = client.webhook.list()\nprint(webhooks.data)" } ] }, "post": { "responses": { "201": { "description": "The created webhook with signing secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateWebhookResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1Webhook", "tags": [ "Webhook" ], "summary": "Create webhook", "description": "Creates a new webhook with event subscriptions. The signing secret is only returned in this response.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst webhook = await client.webhook.create({\n events: ['CALL_ANALYSIS_COMPLETED'],\n url: 'https://example.com',\n});\n\nconsole.log(webhook.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nwebhook = client.webhook.create(\n events=[\"CALL_ANALYSIS_COMPLETED\"],\n url=\"https://example.com\",\n)\nprint(webhook.data)" } ] } }, "/v1/webhook/{webhookId}": { "get": { "responses": { "200": { "description": "The requested webhook with its event subscriptions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1WebhookByWebhookId", "tags": [ "Webhook" ], "summary": "Get webhook by ID", "description": "Returns a specific webhook with its event subscriptions.", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "The ID of the webhook to retrieve", "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.webhook.getByID('webhookId');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.webhook.get_by_id(\n \"webhookId\",\n)\nprint(response.data)" } ] }, "delete": { "responses": { "200": { "description": "Webhook deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the deletion was successful" } }, "required": [ "success" ] } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1WebhookByWebhookId", "tags": [ "Webhook" ], "summary": "Delete webhook", "description": "Deletes a webhook and all its event subscriptions.", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "The ID of the webhook to delete", "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst webhook = await client.webhook.delete('webhookId');\n\nconsole.log(webhook.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nwebhook = client.webhook.delete(\n \"webhookId\",\n)\nprint(webhook.data)" } ] } }, "/v1/issue": { "get": { "responses": { "200": { "description": "List of issues", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "offset", "hasMore" ] } }, "required": [ "data", "pagination" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Issue", "tags": [ "Issue" ], "summary": "List issues", "description": "Returns the project’s issues, ordered newest-first. Supports filtering by status, source, and severity, with offset pagination.", "parameters": [ { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "OPEN", "ACKED", "RESOLVED" ], "description": "Lifecycle state" } }, { "in": "query", "name": "source", "schema": { "type": "string", "enum": [ "TREND_ALERT", "SINGLE_CALL_ALERT", "TRACE_FAILURE", "MANUAL", "API", "AGENT" ], "description": "Who opened the issue" } }, { "in": "query", "name": "severity", "schema": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "Coarse priority — LOW / MEDIUM / HIGH / CRITICAL" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of issues to return (default: 20, max: 100)" } }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "default": 0, "description": "Pagination offset" } } ] }, "post": { "responses": { "201": { "description": "The created issue", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Issue" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1Issue", "tags": [ "Issue" ], "summary": "Create issue", "description": "Opens a new issue with `source: API`. The supplied evidence (calls / chats) is attached in the same transaction; an invalid reference fails the whole request rather than leaving a half-created issue.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIssueInput" } } } } } }, "/v1/issue/{issueId}": { "get": { "responses": { "200": { "description": "The requested issue", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Issue" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1IssueByIssueId", "tags": [ "Issue" ], "summary": "Get issue by ID", "description": "Returns a single issue with its evidence rows.", "parameters": [ { "name": "issueId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/autoimprove/job": { "get": { "responses": { "200": { "description": "The jobs, most recent first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutoimproveJob" } } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1AutoimproveJob", "tags": [ "Autoimprove" ], "summary": "List Autoimprove jobs", "description": "List the Autoimprove jobs in this project, most recent first, capped at 100.\n\nA job is one autonomous engagement: Roark improving one agent toward one objective metric on a staging copy, with a human-gated promote to production at the end.", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst autoimproveJobs = await client.autoimproveJob.list();\n\nconsole.log(autoimproveJobs.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nautoimprove_jobs = client.autoimprove_job.list()\nprint(autoimprove_jobs.data)" } ] }, "post": { "responses": { "201": { "description": "The job was created and its loop started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AutoimproveJob" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "The integration does not allow agent config writes" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "A job is already live for this agent" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1AutoimproveJob", "tags": [ "Autoimprove" ], "summary": "Start an Autoimprove job", "description": "Commission Roark on an objective. It clones the agent into a staging shadow (or uses your designated staging agent), authors a validation suite of simulated callers, measures a baseline, changes the staging configuration, and re-tests until the objective metric passes its target. Production is never touched by the loop; verified changes wait for promotion.\n\nRequires an active provider integration (Vapi, Retell, or ElevenLabs) with agent config writes enabled. One live job per agent: starting a second returns a conflict.\n\nThe job runs asynchronously; poll GET /v1/autoimprove/job/{jobId} or watch it in the dashboard. When its status is NEEDS_INPUT, answer via the answer endpoint; when AWAITING_PROMOTE, promote or dismiss.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAutoimproveJobInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst autoimproveJob = await client.autoimproveJob.create({\n agentId: 'b3b0c8e2-4c1d-4f6a-9e2b-1a2b3c4d5e6f',\n objectiveLabel: 'Consent collection should pass',\n objectiveMetricDefinitionId: 'f2f0c8e2-4c1d-4f6a-9e2b-1a2b3c4d5e6f',\n});\n\nconsole.log(autoimproveJob.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nautoimprove_job = client.autoimprove_job.create(\n agent_id=\"b3b0c8e2-4c1d-4f6a-9e2b-1a2b3c4d5e6f\",\n objective_label=\"Consent collection should pass\",\n objective_metric_definition_id=\"f2f0c8e2-4c1d-4f6a-9e2b-1a2b3c4d5e6f\",\n)\nprint(autoimprove_job.data)" } ] } }, "/v1/autoimprove/job/{jobId}": { "get": { "responses": { "200": { "description": "The job with its worklog.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AutoimproveJobDetail" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Autoimprove job not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1AutoimproveJobByJobId", "tags": [ "Autoimprove" ], "summary": "Get an Autoimprove job", "description": "Fetch one job with its full worklog: every step Roark took, the validation batches with their pass-rate movement, any question it is waiting on, and its final report once concluded.", "parameters": [ { "in": "path", "name": "jobId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.autoimproveJob.getByID('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.autoimprove_job.get_by_id(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] } }, "/v1/autoimprove/job/{jobId}/guidance": { "post": { "responses": { "200": { "description": "The guidance was queued for the next decision.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "accepted": { "type": "boolean", "const": true } }, "required": [ "accepted" ] } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Autoimprove job not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "The job has concluded and no longer takes guidance" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1AutoimproveJobByJobIdGuidance", "tags": [ "Autoimprove" ], "summary": "Send guidance to a running job", "description": "Steer Roark mid-job. The message is folded into its next decision and is binding. Accepted while the job is live (RUNNING, NEEDS_INPUT, or PAUSED); a concluded job returns a conflict.", "parameters": [ { "in": "path", "name": "jobId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoimproveTextInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.autoimproveJob.sendGuidance('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {\n text: 'Keep the current voice; focus on the closing confirmation.',\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.autoimprove_job.send_guidance(\n job_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n text=\"Keep the current voice; focus on the closing confirmation.\",\n)\nprint(response.data)" } ] } }, "/v1/autoimprove/job/{jobId}/answer": { "post": { "responses": { "200": { "description": "The answer was delivered; the job resumes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "accepted": { "type": "boolean", "const": true } }, "required": [ "accepted" ] } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Autoimprove job not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "Roark is not waiting on an answer right now" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1AutoimproveJobByJobIdAnswer", "tags": [ "Autoimprove" ], "summary": "Answer Roark's question", "description": "Answer the question a job is blocked on. Only meaningful while the job status is NEEDS_INPUT (the open QUESTION entry carries the offered options; free text is also accepted). Otherwise returns a conflict.", "parameters": [ { "in": "path", "name": "jobId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoimproveTextInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.autoimproveJob.answerQuestion(\n '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n { text: 'Keep the current voice; focus on the closing confirmation.' },\n);\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.autoimprove_job.answer_question(\n job_id=\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n text=\"Keep the current voice; focus on the closing confirmation.\",\n)\nprint(response.data)" } ] } }, "/v1/autoimprove/job/{jobId}/cancel": { "post": { "responses": { "200": { "description": "The cancel was requested; cleanup follows.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "accepted": { "type": "boolean", "const": true } }, "required": [ "accepted" ] } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Autoimprove job not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "The job has already concluded" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1AutoimproveJobByJobIdCancel", "tags": [ "Autoimprove" ], "summary": "Cancel a job", "description": "Stop a live job. Production is never changed by a cancel; everything the job set up (the shadow agent, its phone number, authored test flows and run plan) is cleaned up automatically.", "parameters": [ { "in": "path", "name": "jobId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.autoimproveJob.cancel('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.autoimprove_job.cancel(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] } }, "/v1/autoimprove/job/{jobId}/promote": { "post": { "responses": { "200": { "description": "The verified changes are live on production.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AutoimproveJob" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Autoimprove job not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "Only a verified job awaiting review can be promoted" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1AutoimproveJobByJobIdPromote", "tags": [ "Autoimprove" ], "summary": "Promote a verified job to production", "description": "Apply the verified staging changes to the PRODUCTION agent. Only a job in AWAITING_PROMOTE can be promoted.\n\nA snapshot of the production configuration is taken immediately before the write, so the promote is fully rollbackable. After the promote the staging shadow and its phone number are cleaned up.", "parameters": [ { "in": "path", "name": "jobId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.autoimproveJob.promote('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.autoimprove_job.promote(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] } }, "/v1/autoimprove/job/{jobId}/dismiss": { "post": { "responses": { "200": { "description": "The job was dismissed; production was never changed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AutoimproveJob" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Autoimprove job not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "Only a fix awaiting review can be dismissed" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1AutoimproveJobByJobIdDismiss", "tags": [ "Autoimprove" ], "summary": "Dismiss a verified job", "description": "Discard a verified job without promoting: production stays untouched and the staging resources are cleaned up. Only a job in AWAITING_PROMOTE can be dismissed.", "parameters": [ { "in": "path", "name": "jobId", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.autoimproveJob.dismiss('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.autoimprove_job.dismiss(\n \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n)\nprint(response.data)" } ] } }, "/v1/agent-config/{key}/resolve": { "post": { "responses": { "200": { "description": "The resolved config for this session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ResolveManagedConfigResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Unknown key and no defaults were provided" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1Agent-configByKeyResolve", "tags": [ "Agent Config" ], "summary": "Resolve config for a session", "description": "The call your agent makes at session start. Returns the config JSON for this session, with per-session simulation recognition built in: when the session was originated by a Roark simulation (matched by caller number against the calls Roark has in flight), the STAGING revision is served for that session only, so Autoimprove candidates are tested on your real deployment. Real traffic always resolves to production; any recognition miss degrades to production too.\n\nOn the first fetch of an unknown key, pass `defaults` (your baked-in config): the key is registered and the defaults become revision 1. That makes integration a single call.\n\nCache the response per session; do not fetch per turn.", "parameters": [ { "in": "path", "name": "key", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$", "minLength": 1, "maxLength": 120 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveManagedConfigRequest" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.agentConfig.resolve('x');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.agent_config.resolve(\n key=\"x\",\n)\nprint(response.data)" } ] } }, "/v1/agent-config": { "get": { "responses": { "200": { "description": "The configs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentConfig" } } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Agent-config", "tags": [ "Agent Config" ], "summary": "List managed configs", "description": "List the managed agent configs in this project, most recent first.", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst agentConfigs = await client.agentConfig.list();\n\nconsole.log(agentConfigs.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nagent_configs = client.agent_config.list()\nprint(agent_configs.data)" } ] } }, "/v1/agent-config/{key}": { "get": { "responses": { "200": { "description": "The config with recent revisions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ManagedAgentConfigDetail" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Managed config not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Agent-configByKey", "tags": [ "Agent Config" ], "summary": "Get a managed config", "description": "Fetch one managed config with its channel pointers and recent revisions, newest first.", "parameters": [ { "in": "path", "name": "key", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$", "minLength": 1, "maxLength": 120 }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.agentConfig.getByID('x');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.agent_config.get_by_id(\n \"x\",\n)\nprint(response.data)" } ] }, "put": { "responses": { "200": { "description": "The config with its updated channel pointers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ManagedAgentConfig" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Staging write on an unknown key" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1Agent-configByKey", "tags": [ "Agent Config" ], "summary": "Write a config revision", "description": "Write a new revision onto a channel. Writing production creates the key when it does not exist; writing staging stages a candidate that only Roark-recognized simulation sessions will read. Every write is a new revision; nothing is overwritten.", "parameters": [ { "in": "path", "name": "key", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$", "minLength": 1, "maxLength": 120 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WriteManagedConfigRequest" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst agentConfig = await client.agentConfig.update('x', {\n channel: 'production',\n document: { foo: 'string' },\n});\n\nconsole.log(agentConfig.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nagent_config = client.agent_config.update(\n key=\"x\",\n channel=\"production\",\n document={\n \"foo\": \"string\",\n },\n)\nprint(agent_config.data)" } ] } }, "/v1/agent-config/{key}/promote": { "post": { "responses": { "200": { "description": "The config with production now on the promoted revision.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ManagedAgentConfig" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Managed config not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "No staging revision to promote" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1Agent-configByKeyPromote", "tags": [ "Agent Config" ], "summary": "Promote staging to production", "description": "Point the production channel at the staging revision. Real traffic reads it from the next session onward; roll back by writing the prior revision id to production (the chain preserves every state).", "parameters": [ { "in": "path", "name": "key", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$", "minLength": 1, "maxLength": 120 }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.agentConfig.promote('x');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.agent_config.promote(\n \"x\",\n)\nprint(response.data)" } ] } }, "/v1/agent-config/{key}/staging": { "delete": { "responses": { "200": { "description": "The config with staging cleared.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ManagedAgentConfig" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Managed config not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1Agent-configByKeyStaging", "tags": [ "Agent Config" ], "summary": "Discard the staging revision", "description": "Clear the staging channel. Production is untouched; recognized simulation sessions go back to reading production.", "parameters": [ { "in": "path", "name": "key", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$", "minLength": 1, "maxLength": 120 }, "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.agentConfig.deleteStaging('x');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.agent_config.delete_staging(\n \"x\",\n)\nprint(response.data)" } ] } }, "/v1/knowledge-base": { "get": { "responses": { "200": { "description": "A page of knowledge bases.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the knowledge base." }, "name": { "type": "string", "description": "Customer-supplied name. Unique within the project." }, "description": { "type": [ "string", "null" ], "description": "Optional customer-supplied description." }, "sourceType": { "type": "string", "enum": [ "TEXT", "FILE", "JSON", "URL" ], "description": "How the knowledge base content was provided. TEXT/JSON are stored as-is; FILE was uploaded and its text content extracted (PDF → text); URL was scraped from a webpage into markdown." }, "status": { "type": "string", "enum": [ "READY", "PROCESSING", "PENDING_UPLOAD", "FAILED" ], "description": "Lifecycle of the knowledge base. READY means the content is available to metrics. PROCESSING is set during PDF text extraction. FAILED means extraction errored — see `errorMessage`." }, "originalFilename": { "type": [ "string", "null" ], "description": "For FILE source: the customer-supplied filename. Null for TEXT/JSON/URL." }, "mimeType": { "type": [ "string", "null" ], "description": "For FILE source: the mime type of the uploaded file. Null for TEXT/JSON/URL." }, "sourceUrl": { "type": [ "string", "null" ], "description": "For URL source: the page that was scraped into markdown. Null for TEXT/JSON/FILE." }, "byteSize": { "type": "integer", "minimum": 0, "description": "Size of the content the model will read at evaluation time. For FILE this is the EXTRACTED text size, not the original PDF size." }, "contentHash": { "type": [ "string", "null" ], "description": "SHA-256 of the content. Stable across whitespace-equivalent edits for JSON (pretty-printed before hashing). Use it to detect change without diffing the content." }, "errorMessage": { "type": [ "string", "null" ], "description": "When `status` is FAILED, the reason. Null otherwise." }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format." }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format." } }, "required": [ "id", "name", "description", "sourceType", "status", "originalFilename", "mimeType", "sourceUrl", "byteSize", "contentHash", "errorMessage", "createdAt", "updatedAt" ], "title": "KnowledgeBase", "description": "A customer-uploaded reference document attached to custom metrics as ground truth at evaluation time." } }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of items" }, "hasMore": { "type": "boolean", "description": "Whether there are more items to fetch" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page of items" } }, "required": [ "total", "hasMore", "nextCursor" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Knowledge-base", "tags": [ "Knowledge Base" ], "summary": "List knowledge bases", "description": "Returns a cursor-paginated list of knowledge bases for the authenticated project. Soft-deleted knowledge bases are excluded.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "in": "query", "name": "after", "schema": { "type": "string" } }, { "in": "query", "name": "searchText", "schema": { "type": "string" } }, { "in": "query", "name": "sourceType", "schema": { "type": "string", "enum": [ "TEXT", "FILE", "JSON", "URL" ], "description": "How the knowledge base content was provided. TEXT/JSON are stored as-is; FILE was uploaded and its text content extracted (PDF → text); URL was scraped from a webpage into markdown." } } ] }, "post": { "responses": { "201": { "description": "The created knowledge base.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the knowledge base." }, "name": { "type": "string", "description": "Customer-supplied name. Unique within the project." }, "description": { "type": [ "string", "null" ], "description": "Optional customer-supplied description." }, "sourceType": { "type": "string", "enum": [ "TEXT", "FILE", "JSON", "URL" ], "description": "How the knowledge base content was provided. TEXT/JSON are stored as-is; FILE was uploaded and its text content extracted (PDF → text); URL was scraped from a webpage into markdown." }, "status": { "type": "string", "enum": [ "READY", "PROCESSING", "PENDING_UPLOAD", "FAILED" ], "description": "Lifecycle of the knowledge base. READY means the content is available to metrics. PROCESSING is set during PDF text extraction. FAILED means extraction errored — see `errorMessage`." }, "originalFilename": { "type": [ "string", "null" ], "description": "For FILE source: the customer-supplied filename. Null for TEXT/JSON/URL." }, "mimeType": { "type": [ "string", "null" ], "description": "For FILE source: the mime type of the uploaded file. Null for TEXT/JSON/URL." }, "sourceUrl": { "type": [ "string", "null" ], "description": "For URL source: the page that was scraped into markdown. Null for TEXT/JSON/FILE." }, "byteSize": { "type": "integer", "minimum": 0, "description": "Size of the content the model will read at evaluation time. For FILE this is the EXTRACTED text size, not the original PDF size." }, "contentHash": { "type": [ "string", "null" ], "description": "SHA-256 of the content. Stable across whitespace-equivalent edits for JSON (pretty-printed before hashing). Use it to detect change without diffing the content." }, "errorMessage": { "type": [ "string", "null" ], "description": "When `status` is FAILED, the reason. Null otherwise." }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format." }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format." } }, "required": [ "id", "name", "description", "sourceType", "status", "originalFilename", "mimeType", "sourceUrl", "byteSize", "contentHash", "errorMessage", "createdAt", "updatedAt" ], "title": "KnowledgeBase", "description": "A customer-uploaded reference document attached to custom metrics as ground truth at evaluation time." } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1Knowledge-base", "tags": [ "Knowledge Base" ], "summary": "Create a knowledge base", "description": "Creates a knowledge base. TEXT and JSON sources accept inline `content`. FILE sources require `filename`, `mimeType`, and base64-encoded `contentBase64` — the file is decoded server-side, stored in S3, and (for PDFs) text-extracted inline before the response returns.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Customer-facing name. Unique within the project. Required." }, "description": { "type": [ "string", "null" ], "maxLength": 500, "description": "Optional short blurb shown in pickers." }, "sourceType": { "type": "string", "enum": [ "TEXT", "FILE", "JSON" ], "description": "Source types accepted via the public create endpoint. URL ingestion is currently only available in the platform UI." }, "content": { "type": [ "string", "null" ], "description": "For TEXT: raw markdown/text. For JSON: a JSON string (validated server-side and re-formatted with stable whitespace). Required for TEXT and JSON; omit for FILE." }, "filename": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 255, "description": "For FILE: customer-supplied filename (informational only — used for download links)." }, "mimeType": { "type": [ "string", "null" ], "enum": [ "application/pdf", "text/plain", "text/markdown" ], "description": "For FILE: mime type of the uploaded file. Only `application/pdf`, `text/plain`, and `text/markdown` are accepted." }, "contentBase64": { "type": [ "string", "null" ], "description": "For FILE: base64-encoded file bytes. Required for FILE. Max 10 MB after decoding. PDFs are text-extracted server-side; image-only PDFs are rejected." } }, "required": [ "name", "sourceType" ], "title": "CreateKnowledgeBaseInput", "description": "Input for creating a knowledge base. See `sourceType` for which fields are required." } } } } } }, "/v1/knowledge-base/{id}": { "get": { "responses": { "200": { "description": "The requested knowledge base.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the knowledge base." }, "name": { "type": "string", "description": "Customer-supplied name. Unique within the project." }, "description": { "type": [ "string", "null" ], "description": "Optional customer-supplied description." }, "sourceType": { "type": "string", "enum": [ "TEXT", "FILE", "JSON", "URL" ], "description": "How the knowledge base content was provided. TEXT/JSON are stored as-is; FILE was uploaded and its text content extracted (PDF → text); URL was scraped from a webpage into markdown." }, "status": { "type": "string", "enum": [ "READY", "PROCESSING", "PENDING_UPLOAD", "FAILED" ], "description": "Lifecycle of the knowledge base. READY means the content is available to metrics. PROCESSING is set during PDF text extraction. FAILED means extraction errored — see `errorMessage`." }, "originalFilename": { "type": [ "string", "null" ], "description": "For FILE source: the customer-supplied filename. Null for TEXT/JSON/URL." }, "mimeType": { "type": [ "string", "null" ], "description": "For FILE source: the mime type of the uploaded file. Null for TEXT/JSON/URL." }, "sourceUrl": { "type": [ "string", "null" ], "description": "For URL source: the page that was scraped into markdown. Null for TEXT/JSON/FILE." }, "byteSize": { "type": "integer", "minimum": 0, "description": "Size of the content the model will read at evaluation time. For FILE this is the EXTRACTED text size, not the original PDF size." }, "contentHash": { "type": [ "string", "null" ], "description": "SHA-256 of the content. Stable across whitespace-equivalent edits for JSON (pretty-printed before hashing). Use it to detect change without diffing the content." }, "errorMessage": { "type": [ "string", "null" ], "description": "When `status` is FAILED, the reason. Null otherwise." }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format." }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format." } }, "required": [ "id", "name", "description", "sourceType", "status", "originalFilename", "mimeType", "sourceUrl", "byteSize", "contentHash", "errorMessage", "createdAt", "updatedAt" ], "title": "KnowledgeBase", "description": "A customer-uploaded reference document attached to custom metrics as ground truth at evaluation time." } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Knowledge-baseById", "tags": [ "Knowledge Base" ], "summary": "Get a knowledge base by ID", "description": "Returns metadata for a single knowledge base. Does not include content — content is read by metrics at evaluation time and is not exposed over the public API.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Knowledge base ID" } ] } }, "/v1/analytics/schema": { "get": { "responses": { "200": { "description": "The analytics schema", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AnalyticsSchema" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1AnalyticsSchema", "tags": [ "Analytics" ], "summary": "Get the analytics schema", "description": "Lists what can go into an analytics query for this project: every metric by slug with its output\ntype, default aggregation and the aggregations it supports; the measure types; the filter and\nbreakdown types with the properties each accepts; and the custom call properties seen in the project.\nRead this first when building a query.", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.analytics.getSchema();\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.analytics.get_schema()\nprint(response.data)" } ] } }, "/v1/analytics/query": { "post": { "responses": { "200": { "description": "The query result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AnalyticsResult" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Invalid or unsupported query" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "A metric was not found in this project" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1AnalyticsQuery", "tags": [ "Analytics" ], "summary": "Run an analytics query", "description": "Aggregates metric values and conversation counts over a time window and returns one series per\nmeasure, with a total for the window and per-interval buckets. The same query a dashboard widget\nruns, without saving anything.\n\n- `measures`: what to aggregate. A METRIC measure names its metric by slug; CONVERSATION counts\n conversations; UPTIME reads health checks. The aggregation defaults by the metric's output type.\n- `timeRange`: LAST n DAYS/WEEKS/MONTHS, a CALENDAR_ALIGNED period (TODAY, THIS_MONTH, ...), FIXED\n from/to, or SINCE. Defaults to the last 30 days; at most 731 days. Calendar periods and buckets\n align to `timezone` (IANA, default UTC).\n- `filters` apply to every measure; a measure's own `filters` add to them.\n- `breakdown` on a measure returns one series per value (largest 50 kept).\n- `comparisonGroups` (2 to 5) run every measure once per named filter set;\n `comparisonMode: PREVIOUS_PERIOD` adds the preceding window's values.\n\nValues are in the metric's display units. A PASS_RATE is a 0 to 1 share; `sampleSize` 0 means no data.\nA query the analytics store cannot answer returns 400 naming the unsupported part.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsQuery" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.analytics.query({ measures: [{}] });\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.analytics.query(\n measures=[{}],\n)\nprint(response.data)" } ] } }, "/v1/dashboard": { "get": { "responses": { "200": { "description": "The dashboards", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardSummary" } } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Dashboard or widget not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Dashboard", "tags": [ "Dashboard" ], "summary": "List dashboards", "description": "Lists the project's dashboards, the default first. GET /v1/dashboard/{dashboardId} returns the widgets.", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst dashboards = await client.dashboard.list();\n\nconsole.log(dashboards.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\ndashboards = client.dashboard.list()\nprint(dashboards.data)" } ] }, "post": { "responses": { "201": { "description": "The created dashboard", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Dashboard" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Invalid dashboard, or a widget the analytics store cannot answer" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Dashboard, widget or a referenced metric not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "The dashboard is managed by config as code" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1Dashboard", "tags": [ "Dashboard" ], "summary": "Create a dashboard", "description": "Creates a dashboard with its widgets. Each widget is an analytics query (see POST /v1/analytics/query)\nwith a name unique on the dashboard, a `display` (LINE, NUMBER, RADAR, STACKED_BAR, TABLE) and a\n`size` (SMALL, MEDIUM, LARGE, EXTRA_LARGE). Widgets render top to bottom in the order given.\n\nDashboard `filters` apply over every widget and must be conversation-level: AGENT_PROPERTY,\nCALL_PROPERTY, MODALITY, DATASET or METRIC_VALUE. On a field a widget already filters, the dashboard's wins.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst dashboard = await client.dashboard.create({ name: 'x' });\n\nconsole.log(dashboard.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\ndashboard = client.dashboard.create(\n name=\"x\",\n)\nprint(dashboard.data)" } ] } }, "/v1/dashboard/{dashboardId}": { "get": { "responses": { "200": { "description": "The dashboard", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Dashboard" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Dashboard or widget not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1DashboardByDashboardId", "tags": [ "Dashboard" ], "summary": "Get a dashboard", "description": "Returns a dashboard with its widgets top to bottom, each in the shape POST /v1/dashboard accepts, so a dashboard can be read, edited and written back.", "parameters": [ { "name": "dashboardId", "in": "path", "required": true, "description": "The dashboard ID", "schema": { "type": "string", "format": "uuid" }, "example": "6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b" } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.dashboard.getByID('6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.dashboard.get_by_id(\n \"6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b\",\n)\nprint(response.data)" } ] }, "put": { "responses": { "200": { "description": "The updated dashboard", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Dashboard" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Invalid dashboard, or a widget the analytics store cannot answer" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Dashboard, widget or a referenced metric not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "The dashboard is managed by config as code" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1DashboardByDashboardId", "tags": [ "Dashboard" ], "summary": "Update a dashboard", "description": "Edits a dashboard. Omitted fields keep their current value. `widgets`, when sent, replaces the list:\nwidgets are matched by name, so a widget that keeps its name keeps its id; a new name adds a widget and\na name no longer listed removes it. To change one widget, PUT /v1/dashboard/{dashboardId}/widget/{widgetId}.", "parameters": [ { "name": "dashboardId", "in": "path", "required": true, "description": "The dashboard ID", "schema": { "type": "string", "format": "uuid" }, "example": "6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDashboardInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst dashboard = await client.dashboard.update('6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b');\n\nconsole.log(dashboard.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\ndashboard = client.dashboard.update(\n dashboard_id=\"6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b\",\n)\nprint(dashboard.data)" } ] }, "delete": { "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Dashboard or widget not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "The dashboard is managed by config as code" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1DashboardByDashboardId", "tags": [ "Dashboard" ], "summary": "Delete a dashboard", "description": "Deletes a dashboard and its widgets. If it was the default, another dashboard becomes the default. A dashboard managed by config as code returns 409.", "parameters": [ { "name": "dashboardId", "in": "path", "required": true, "description": "The dashboard ID", "schema": { "type": "string", "format": "uuid" }, "example": "6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b" } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst dashboard = await client.dashboard.delete('6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b');\n\nconsole.log(dashboard.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\ndashboard = client.dashboard.delete(\n \"6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b\",\n)\nprint(dashboard.data)" } ] } }, "/v1/dashboard/{dashboardId}/data": { "get": { "responses": { "200": { "description": "The dashboard's data", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DashboardData" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Dashboard or widget not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1DashboardByDashboardIdData", "tags": [ "Dashboard" ], "summary": "Get dashboard data", "description": "Runs every widget on the dashboard and returns each one's series, exactly as the dashboard shows them:\nover the dashboard's saved window and with its filters applied. Pass `from` (and optionally `to`) to\nread a different window, and `timezone` to align buckets to a zone.", "parameters": [ { "in": "query", "name": "from", "schema": { "type": "string", "format": "date-time", "description": "ISO 8601 start. Overrides the saved window; without `to`, runs until now." } }, { "in": "query", "name": "to", "schema": { "type": "string", "format": "date-time", "description": "ISO 8601 end. Requires `from`." } }, { "in": "query", "name": "timezone", "schema": { "type": "string", "minLength": 1, "description": "IANA zone buckets and calendar periods align to. Default UTC." } }, { "schema": { "type": "string" }, "in": "path", "name": "dashboardId", "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.dashboard.getData('dashboardId');\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.dashboard.get_data(\n dashboard_id=\"dashboardId\",\n)\nprint(response.data)" } ] } }, "/v1/dashboard/{dashboardId}/widget": { "post": { "responses": { "201": { "description": "The created widget", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DashboardWidget" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Invalid dashboard, or a widget the analytics store cannot answer" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Dashboard, widget or a referenced metric not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "The dashboard is managed by config as code" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1DashboardByDashboardIdWidget", "tags": [ "Dashboard" ], "summary": "Add a widget", "description": "Adds a widget to the top of a dashboard. Its name must be unique on the dashboard.", "parameters": [ { "name": "dashboardId", "in": "path", "required": true, "description": "The dashboard ID", "schema": { "type": "string", "format": "uuid" }, "example": "6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardWidgetInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.dashboard.createWidget('6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b', {\n measures: [{}],\n name: 'x',\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.dashboard.create_widget(\n dashboard_id=\"6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b\",\n measures=[{}],\n name=\"x\",\n)\nprint(response.data)" } ] } }, "/v1/dashboard/{dashboardId}/widget/{widgetId}": { "put": { "responses": { "200": { "description": "The updated widget", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DashboardWidget" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Invalid dashboard, or a widget the analytics store cannot answer" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Dashboard, widget or a referenced metric not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "The dashboard is managed by config as code" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1DashboardByDashboardIdWidgetByWidgetId", "tags": [ "Dashboard" ], "summary": "Replace a widget", "description": "Replaces a widget's definition. It keeps its id and its place on the dashboard.", "parameters": [ { "name": "dashboardId", "in": "path", "required": true, "description": "The dashboard ID", "schema": { "type": "string", "format": "uuid" }, "example": "6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b" }, { "name": "widgetId", "in": "path", "required": true, "description": "The widget ID", "schema": { "type": "string", "format": "uuid" }, "example": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardWidgetInput" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.dashboard.updateWidget('7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d', {\n dashboardId: '6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b',\n measures: [{}],\n name: 'x',\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.dashboard.update_widget(\n widget_id=\"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d\",\n dashboard_id=\"6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b\",\n measures=[{}],\n name=\"x\",\n)\nprint(response.data)" } ] }, "delete": { "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Dashboard or widget not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "The dashboard is managed by config as code" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1DashboardByDashboardIdWidgetByWidgetId", "tags": [ "Dashboard" ], "summary": "Remove a widget", "description": "Removes a widget from a dashboard.", "parameters": [ { "name": "dashboardId", "in": "path", "required": true, "description": "The dashboard ID", "schema": { "type": "string", "format": "uuid" }, "example": "6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b" }, { "name": "widgetId", "in": "path", "required": true, "description": "The widget ID", "schema": { "type": "string", "format": "uuid" }, "example": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d" } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.dashboard.deleteWidget('7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d', {\n dashboardId: '6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b',\n});\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.dashboard.delete_widget(\n \"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d\",\n dashboard_id=\"6f1d2c3b-4a5e-4f60-8b71-9c0d1e2f3a4b\",\n)\nprint(response.data)" } ] } }, "/v1/dashboard/{dashboardId}/widget/{widgetId}/data": { "get": { "responses": { "200": { "description": "The widget's data", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DashboardWidgetData" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Dashboard or widget not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1DashboardByDashboardIdWidgetByWidgetIdData", "tags": [ "Dashboard" ], "summary": "Get widget data", "description": "Runs one widget and returns its series, as it reads on its dashboard (the dashboard's window and filters). Accepts the same `from` / `to` / `timezone` overrides as GET /v1/dashboard/{dashboardId}/data.", "parameters": [ { "in": "query", "name": "from", "schema": { "type": "string", "format": "date-time", "description": "ISO 8601 start. Overrides the saved window; without `to`, runs until now." } }, { "in": "query", "name": "to", "schema": { "type": "string", "format": "date-time", "description": "ISO 8601 end. Requires `from`." } }, { "in": "query", "name": "timezone", "schema": { "type": "string", "minLength": 1, "description": "IANA zone buckets and calendar periods align to. Default UTC." } }, { "schema": { "type": "string" }, "in": "path", "name": "dashboardId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "widgetId", "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.dashboard.getWidgetData('widgetId', { dashboardId: 'dashboardId' });\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.dashboard.get_widget_data(\n widget_id=\"widgetId\",\n dashboard_id=\"dashboardId\",\n)\nprint(response.data)" } ] } }, "/v1/config/diff": { "post": { "responses": { "200": { "description": "The projected changes", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConfigDiffResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1ConfigDiff", "tags": [ "Config" ], "summary": "Diff a config bundle", "description": "Dry run for an apply: returns the projected changes (create / update / delete) for the submitted bundle without writing anything. Works for both project and organization keys.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigBundle" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.config.diff({ resources: [{ kind: 'agent', name: 'x' }] });\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.config.diff(\n resources=[{\n \"kind\": \"agent\",\n \"name\": \"x\",\n }],\n)\nprint(response.data)" } ] } }, "/v1/config/apply": { "post": { "responses": { "200": { "description": "The applied changes", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConfigApplyResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Rate limit error" }, "example": { "type": "rate_limit", "code": "too_many_requests", "message": "Rate limit exceeded" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1ConfigApply", "tags": [ "Config" ], "summary": "Apply a config bundle", "description": "Reconcile a config-as-code bundle. With a PROJECT API key, submit project-scoped resources (agents, personas, flows, collectors, metrics, ...). With an ORGANIZATION API key, submit `kind: project` resources, each optionally carrying its members and its own nested `resources`. Submit the full desired set; managed resources are updated, new ones created, and (unless prune is false) managed resources absent from the bundle are deleted. Identity is by name.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigBundle" } } } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.config.apply({ resources: [{ kind: 'agent', name: 'x' }] });\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.config.apply(\n resources=[{\n \"kind\": \"agent\",\n \"name\": \"x\",\n }],\n)\nprint(response.data)" } ] } }, "/v1/org/project": { "get": { "responses": { "200": { "description": "A page of organization projects", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgProjectsResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1OrgProject", "tags": [ "Organization Project" ], "summary": "List projects", "description": "List projects in the organization the API key belongs to. Paginated (max 101 per page): pass `page`/`limit` and keep paging until a page returns fewer than `limit` items.", "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1, "description": "Page number (1-based, default 1)" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 101, "description": "Page size (max 101, default 20)" } } ] }, "post": { "responses": { "200": { "description": "The created project", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OrgProject" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1OrgProject", "tags": [ "Organization Project" ], "summary": "Create a project", "description": "Create a new project in the organization. The project is provisioned with the default analysis packages, dashboard, and alerts, exactly as a UI-created project would be. The user who minted the API key becomes the initial project owner.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgProjectInput" } } } } } }, "/v1/org/project/{projectId}": { "get": { "responses": { "200": { "description": "The project", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OrgProject" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1OrgProjectByProjectId", "tags": [ "Organization Project" ], "summary": "Get a project", "description": "Get a single project by id (must belong to the organization).", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "projectId", "required": true } ] }, "put": { "responses": { "200": { "description": "The updated project", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OrgProject" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1OrgProjectByProjectId", "tags": [ "Organization Project" ], "summary": "Update a project", "description": "Update a project name, description, or category.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgProjectInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "projectId", "required": true } ] }, "delete": { "responses": { "200": { "description": "Deletion result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeleteOrgResourceResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1OrgProjectByProjectId", "tags": [ "Organization Project" ], "summary": "Delete a project", "description": "Soft-delete a project and pause its active schedules. Returns 409 when the project is the last one in the organization, has an active agent connection, or has a simulation running.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "projectId", "required": true } ] } }, "/v1/org/project/{projectId}/member": { "get": { "responses": { "200": { "description": "The project members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgProjectMembersResponse" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1OrgProjectByProjectIdMember", "tags": [ "Organization Project Member" ], "summary": "List project members", "description": "List active and pending-invite members of a project.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "projectId", "required": true } ] }, "post": { "responses": { "200": { "description": "The created membership", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OrgProjectMember" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1OrgProjectByProjectIdMember", "tags": [ "Organization Project Member" ], "summary": "Invite a member", "description": "Invite a user to the project by email with a role. If the user has no Roark account yet, an invite email is sent and the membership is INVITED until they accept; existing users are added directly. Use this for onboarding and for assigning users to projects.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteOrgProjectMemberInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "projectId", "required": true } ] } }, "/v1/org/project/{projectId}/member/{memberId}": { "put": { "responses": { "200": { "description": "The updated membership", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OrgProjectMember" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "putV1OrgProjectByProjectIdMemberByMemberId", "tags": [ "Organization Project Member" ], "summary": "Update a member role", "description": "Change a project member role.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgProjectMemberInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "memberId", "required": true } ] }, "delete": { "responses": { "200": { "description": "Removal result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeleteOrgResourceResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Conflict error" }, "example": { "type": "conflict", "code": "resource_in_use", "message": "The resource is in use and cannot be deleted" } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1OrgProjectByProjectIdMemberByMemberId", "tags": [ "Organization Project Member" ], "summary": "Remove a member", "description": "Remove a member from the project. The last owner/admin cannot be removed (409).", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "memberId", "required": true } ] } }, "/v1/org/project/{projectId}/api-key": { "get": { "responses": { "200": { "description": "The project API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgProjectApiKeysResponse" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1OrgProjectByProjectIdApi-key", "tags": [ "Organization Project API Key" ], "summary": "List project API keys", "description": "List API keys for a project (key values are never returned after creation).", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "projectId", "required": true } ] }, "post": { "responses": { "200": { "description": "The created key (value returned once)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateOrgProjectApiKeyResponse" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "postV1OrgProjectByProjectIdApi-key", "tags": [ "Organization Project API Key" ], "summary": "Generate a project API key", "description": "Mint a new project-scoped API key. The raw key value is returned exactly once in the `key` field: capture it now, it is unreadable afterwards. Defaults to full project access with READ + WRITE scope; narrow with `permissions` / `scopes`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgProjectApiKeyInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "projectId", "required": true } ] } }, "/v1/org/project/{projectId}/api-key/{keyId}": { "delete": { "responses": { "200": { "description": "Revocation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeleteOrgResourceResponse" } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "deleteV1OrgProjectByProjectIdApi-keyByKeyId", "tags": [ "Organization Project API Key" ], "summary": "Revoke a project API key", "description": "Revoke (deactivate) a project API key. Idempotent from the caller perspective.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "keyId", "required": true } ] } }, "/v1/usage": { "get": { "responses": { "200": { "description": "The usage & cost report for the window", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UsageReport" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Permission error" }, "example": { "type": "forbidden", "code": "permission_denied", "message": "You do not have permission to access this resource" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1Usage", "tags": [ "Usage" ], "summary": "Get usage & cost", "description": "Report billable usage and cost for the organization over a time window, broken down by project (highest spend first). Pass `from`/`to` as ISO 8601 timestamps; optionally pass `projectId` to scope the report to one project. Amounts are billable spend only (what we absorb is never included). Authenticated by either an organization API key with the `usage:read` permission (any project in the organization), or a project API key with the `billing:read` permission (that key's own project only; any other `projectId` is a 403).", "parameters": [ { "in": "query", "name": "from", "schema": { "type": "string", "format": "date-time", "description": "Start of the window (inclusive), ISO 8601.", "example": "2026-09-01T00:00:00Z" }, "required": true }, { "in": "query", "name": "to", "schema": { "type": "string", "format": "date-time", "description": "End of the window (exclusive), ISO 8601. Must be after `from`, and the window may not exceed 366 days.", "example": "2026-10-01T00:00:00Z" }, "required": true }, { "in": "query", "name": "projectId", "schema": { "type": "string", "format": "uuid", "description": "Limit the report to a single project. Omit for the whole organization." }, "required": false } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst usage = await client.usage.get({ from: '2026-09-01T00:00:00Z', to: '2026-10-01T00:00:00Z' });\n\nconsole.log(usage.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nusage = client.usage.get(\n from_=\"2026-09-01T00:00:00Z\",\n to=\"2026-10-01T00:00:00Z\",\n)\nprint(usage.data)" } ] } }, "/v1/benchmark/suite": { "get": { "responses": { "200": { "description": "Published suites", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkSuite" } } }, "required": [ "data" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1BenchmarkSuite", "tags": [ "Benchmark" ], "summary": "List benchmark suites", "description": "Returns every benchmark suite with published results, along with the suite version the other endpoints default to. Start here: the suite name is a required parameter everywhere else and there is no other way to discover it.", "parameters": [], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.benchmark.listSuites();\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.benchmark.list_suites()\nprint(response.data)" } ] } }, "/v1/benchmark/metric": { "get": { "responses": { "200": { "description": "Published metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkMetric" } }, "suite": { "type": "string" }, "suiteVersion": { "type": "string" } }, "required": [ "data", "suite", "suiteVersion" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1BenchmarkMetric", "tags": [ "Benchmark" ], "summary": "List benchmark metrics", "description": "Returns the metrics a suite version published, each with the direction that counts as better. Use it to pick a valid `sortBy` for the leaderboard: a metric key outside this list is rejected rather than silently ranking every target null.", "parameters": [ { "in": "query", "name": "suite", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "query", "name": "suiteVersion", "schema": { "type": "string", "minLength": 1 }, "required": false } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.benchmark.listMetrics({ suite: 'x' });\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.benchmark.list_metrics(\n suite=\"x\",\n)\nprint(response.data)" } ] } }, "/v1/benchmark/leaderboard": { "get": { "responses": { "200": { "description": "One ranked page of the leaderboard", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkLeaderboardRow" } }, "suite": { "type": "string" }, "suiteVersion": { "type": "string", "description": "The version actually read, after defaulting." }, "conditionKey": { "type": "string" }, "sortedBy": { "$ref": "#/components/schemas/BenchmarkSortDescriptor" }, "pagination": { "$ref": "#/components/schemas/BenchmarkPagination" } }, "required": [ "data", "suite", "suiteVersion", "conditionKey", "sortedBy", "pagination" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1BenchmarkLeaderboard", "tags": [ "Benchmark" ], "summary": "Get the benchmark leaderboard", "description": "Returns one ranked page of a suite version’s published targets, each with the metric cells it is judged on. Ranking happens in the database, so paging through the board is consistent. Every default the server applies (suite version, condition, sort metric, sort direction) is echoed on the response, so a page can be cited without guessing how it was ordered.", "parameters": [ { "in": "query", "name": "suite", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "query", "name": "suiteVersion", "schema": { "type": "string", "minLength": 1 }, "required": false }, { "in": "query", "name": "conditionKey", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "sortBy", "schema": { "type": "string", "minLength": 1 }, "required": false }, { "in": "query", "name": "order", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "required": false }, { "in": "query", "name": "metrics", "schema": { "type": "string", "description": "Comma-separated metric keys to project per row. Defaults to the headline set." }, "required": false }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of records to return (default: 20, max: 100)" }, "required": false }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "default": 0, "description": "Pagination offset" }, "required": false } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.benchmark.getLeaderboard({ suite: 'x' });\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.benchmark.get_leaderboard(\n suite=\"x\",\n)\nprint(response.data)" } ] } }, "/v1/benchmark/target/{targetKey}/score-sample": { "get": { "responses": { "200": { "description": "One page of score samples", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkScoreSample" } }, "target": { "$ref": "#/components/schemas/BenchmarkTarget" }, "pagination": { "$ref": "#/components/schemas/BenchmarkPagination" } }, "required": [ "data", "target", "pagination" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1BenchmarkTargetByTargetKeyScore-sample", "tags": [ "Benchmark" ], "summary": "List score samples for a target", "description": "Returns the individual scored calls behind a target’s aggregate cells, each with the scorer’s rationale — the \"why is this number what it is\" read. Filter to one cell with `conditionKey` and `metricKey`. Metrics computed without a rationale (latencies, counts) contribute no samples. Returns reasoning only: no transcript and no audio.", "parameters": [ { "in": "query", "name": "suite", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "query", "name": "suiteVersion", "schema": { "type": "string", "minLength": 1 }, "required": false }, { "in": "query", "name": "conditionKey", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "metricKey", "schema": { "type": "string", "minLength": 1 }, "required": false }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of records to return (default: 20, max: 100)" }, "required": false }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "default": 0, "description": "Pagination offset" }, "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "targetKey", "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.benchmark.listTargetScoreSamples('targetKey', { suite: 'x' });\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.benchmark.list_target_score_samples(\n target_key=\"targetKey\",\n suite=\"x\",\n)\nprint(response.data)" } ] } }, "/v1/benchmark/target/{targetKey}/history": { "get": { "responses": { "200": { "description": "One page of published generations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkGeneration" } }, "pagination": { "$ref": "#/components/schemas/BenchmarkPagination" } }, "required": [ "data", "pagination" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1BenchmarkTargetByTargetKeyHistory", "tags": [ "Benchmark" ], "summary": "List a target’s published generations", "description": "Returns every sweep published for a target, newest first, including superseded ones. This is the trend read: it answers \"did this model regress?\" from Roark’s own published record. Metadata only — pass a row’s `publicationId` to GET /v1/benchmark/target/{targetKey} for that generation’s numbers.", "parameters": [ { "in": "query", "name": "suite", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "query", "name": "suiteVersion", "schema": { "type": "string", "minLength": 1 }, "required": false }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of records to return (default: 20, max: 100)" }, "required": false }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "default": 0, "description": "Pagination offset" }, "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "targetKey", "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.benchmark.listTargetHistory('targetKey', { suite: 'x' });\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.benchmark.list_target_history(\n target_key=\"targetKey\",\n suite=\"x\",\n)\nprint(response.data)" } ] } }, "/v1/benchmark/target/{targetKey}": { "get": { "responses": { "200": { "description": "The target and all of its published cells", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BenchmarkTargetDetail" } }, "required": [ "data" ] } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Validation error" }, "example": { "type": "validation", "code": "invalid_parameter", "message": "The request was invalid", "param": "email" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Authentication error" }, "example": { "type": "authentication", "code": "unauthorized", "message": "Authentication required" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Not found error" }, "example": { "type": "not_found", "code": "resource_not_found", "message": "The requested resource could not be found" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "description": "Server error" }, "example": { "type": "internal", "code": "internal_error", "message": "Internal server error" } } }, "description": "Internal Server Error" } }, "operationId": "getV1BenchmarkTargetByTargetKey", "tags": [ "Benchmark" ], "summary": "Get a benchmark target", "description": "Returns a target’s published sweep and every one of its aggregate cells: the overall rollup plus a set per condition. Defaults to the current sweep; pass `publicationId` from the history endpoint to read a superseded one, which is how a regression is compared generation to generation. Numbers only — no transcript and no audio.", "parameters": [ { "in": "query", "name": "suite", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "query", "name": "suiteVersion", "schema": { "type": "string", "minLength": 1 }, "required": false }, { "in": "query", "name": "publicationId", "schema": { "type": "string", "format": "uuid" }, "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "targetKey", "required": true } ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Roark from '@roarkanalytics/sdk';\n\nconst client = new Roark({\n bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted\n});\n\nconst response = await client.benchmark.getTarget('targetKey', { suite: 'x' });\n\nconsole.log(response.data);" }, { "lang": "Python", "source": "import os\nfrom roark_analytics import Roark\n\nclient = Roark(\n bearer_token=os.environ.get(\"ROARK_API_BEARER_TOKEN\"), # This is the default and can be omitted\n)\nresponse = client.benchmark.get_target(\n target_key=\"targetKey\",\n suite=\"x\",\n)\nprint(response.data)" } ] } } } }