Roark · Schema
AgentVersionResponse
One version of a Roark-hosted agent's configuration. Null settings use the runtime default.
CompanyVoice AITestingEvaluationBenchmarking
Properties
| Name | Type | Description |
|---|---|---|
| id | string | |
| agentId | string | |
| status | string | DRAFT while being edited, PUBLISHED once it has been live. |
| versionNumber | integernull | v1, v2, ... assigned on publish; null on a draft. |
| revision | integer | Increases with every edit to a draft. Send it back as expectedRevision when you publish. |
| baseVersionId | stringnull | The published version a draft started from. |
| rolledBackFromVersionId | stringnull | Set when this version rolls the agent back to an older one. |
| summary | stringnull | What changed, written on publish. |
| createdByType | string | |
| createdById | stringnull | |
| publishedAt | stringnull | ISO 8601. |
| publishedByType | stringnull | |
| publishedById | stringnull | |
| createdAt | string | ISO 8601. |
| updatedAt | string | ISO 8601. |
| modalities | array | Whether the agent takes calls, chats, or both. |
| language | stringnull | ISO 639-1, e.g. en. |
| firstMessageMode | stringnull | |
| firstMessage | stringnull | What the agent says first, with firstMessageMode SPEAK_TEXT. |
| firstMessageAudioUrl | stringnull | The audio a call opens with, with firstMessageMode PLAY_AUDIO. |
| llmProvider | stringnull | |
| llmModel | stringnull | Any model id the provider accepts. One model serves every speaker. |
| llmTemperature | numbernull | 0 to 2. |
| llmMaxTokens | integernull | |
| llmBackendModel | stringnull | OpenAI Live models only: the text model they delegate to. |
| llmVoice | stringnull | Speech-to-speech models only: the model's own voice. |
| sttProvider | stringnull | |
| sttModel | stringnull | |
| sttKeyterms | array | Words and phrases the transcriber should listen for. |
| sttSmartFormat | booleannull | |
| sttEndpointingMs | integernull | |
| sttTurnDetection | stringnull | |
| interruptionMode | stringnull | |
| vadStartSecs | numbernull | |
| vadStopSecs | numbernull | |
| callMaxDurationSeconds | integernull | |
| callSilenceTimeoutSeconds | integernull | |
| idleTimeoutSeconds | integernull | |
| idleMaxCount | integernull | |
| idleMessages | array | |
| endDetectionPhrases | array | Phrases that end the call when the caller says them, matched anywhere in what they say. |
| endDetectionReasons | array | When the agent may decide to end the call itself. |
| endCallGoodbyeMessage | stringnull | |
| backgroundNoise | stringnull | A background preset. |
| backgroundNoiseUrl | stringnull | A custom background recording, instead of a preset. |
| backgroundNoiseVolume | numbernull | 0 to 1. |
| chatMaxDurationSeconds | integernull | |
| chatInactivityTimeoutSeconds | integernull | |
| subAgents | array | The main agent (key `main`) first, then the sub-agents it can hand the call to. |
| issues | array | Why this version cannot run; empty when it can be published. Returned when reading one version. |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/roark/json-schema/roark-agent-version-response-schema.json",
"title": "AgentVersionResponse",
"description": "One version of a Roark-hosted agent's configuration. Null settings use the runtime default.",
"x-generated": "2026-11-10",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/roark-agent-api-openapi.yml#/components/schemas/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."
},
"llmProvider": {
"type": [
"string",
"null"
],
"enum": [
"OPENAI",
"ANTHROPIC",
"GOOGLE",
"XAI",
"ULTRAVOX",
"AWS",
"ELEVENLABS"
]
},
"llmModel": {
"type": [
"string",
"null"
],
"description": "Any model id the provider accepts. One model serves every speaker."
},
"llmTemperature": {
"type": [
"number",
"null"
],
"description": "0 to 2."
},
"llmMaxTokens": {
"type": [
"integer",
"null"
]
},
"llmBackendModel": {
"type": [
"string",
"null"
],
"description": "OpenAI Live models only: the text model they delegate to."
},
"llmVoice": {
"type": [
"string",
"null"
],
"description": "Speech-to-speech models only: the model's own voice."
},
"sttProvider": {
"type": [
"string",
"null"
],
"enum": [
"DEEPGRAM",
"OPENAI_WHISPER",
"SPEECHMATICS",
"ASSEMBLYAI",
"ELEVENLABS"
]
},
"sttModel": {
"type": [
"string",
"null"
]
},
"sttKeyterms": {
"type": "array",
"items": {
"type": "string"
},
"description": "Words and phrases the transcriber should listen for."
},
"sttSmartFormat": {
"type": [
"boolean",
"null"
]
},
"sttEndpointingMs": {
"type": [
"integer",
"null"
]
},
"sttTurnDetection": {
"type": [
"string",
"null"
],
"enum": [
"pipeline",
"provider"
]
},
"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": "#/$defs/AgentVersionSubAgent"
},
"description": "The main agent (key `main`) first, then the sub-agents it can hand the call to."
},
"issues": {
"type": "array",
"items": {
"$ref": "#/$defs/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",
"llmProvider",
"llmModel",
"llmTemperature",
"llmMaxTokens",
"llmBackendModel",
"llmVoice",
"sttProvider",
"sttModel",
"sttKeyterms",
"sttSmartFormat",
"sttEndpointingMs",
"sttTurnDetection",
"interruptionMode",
"vadStartSecs",
"vadStopSecs",
"callMaxDurationSeconds",
"callSilenceTimeoutSeconds",
"idleTimeoutSeconds",
"idleMaxCount",
"idleMessages",
"endDetectionPhrases",
"endDetectionReasons",
"endCallGoodbyeMessage",
"backgroundNoise",
"backgroundNoiseUrl",
"backgroundNoiseVolume",
"chatMaxDurationSeconds",
"chatInactivityTimeoutSeconds",
"subAgents"
],
"$defs": {
"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."
},
"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."
},
"ttsProvider": {
"type": [
"string",
"null"
],
"enum": [
"CARTESIA",
"ELEVENLABS",
"OPENAI",
"RIME"
]
},
"ttsModel": {
"type": [
"string",
"null"
]
},
"ttsVoiceId": {
"type": [
"string",
"null"
],
"description": "Any voice id the provider accepts, including your own voices."
},
"ttsSpeed": {
"type": [
"number",
"null"
],
"description": "0.5 to 2."
},
"ttsStability": {
"type": [
"number",
"null"
],
"description": "0 to 1, ElevenLabs."
},
"ttsSimilarityBoost": {
"type": [
"number",
"null"
],
"description": "0 to 1, ElevenLabs."
},
"tools": {
"type": "array",
"items": {
"$ref": "#/$defs/AgentVersionTool"
}
},
"handoffs": {
"type": "array",
"items": {
"$ref": "#/$defs/AgentVersionHandoff"
}
}
},
"required": [
"key",
"name",
"systemPrompt",
"isInitial",
"ttsProvider",
"ttsModel",
"ttsVoiceId",
"ttsSpeed",
"ttsStability",
"ttsSimilarityBoost",
"tools",
"handoffs"
],
"description": "A speaker in the conversation. On a sub-agent, null voice settings use the main agent's."
},
"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"
]
}
}
}
Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/roark-agent-version-response"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.