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.
View JSON Schema on GitHub

JSON Schema

roark-agent-version-response-schema.json Raw ↑
{
  "$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.
All 92 tools →

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.