Roark · Schema

ListAgentVersionsResponse

CompanyVoice AITestingEvaluationBenchmarking

Properties

Name Type Description
data array
pagination object
View JSON Schema on GitHub

JSON Schema

roark-list-agent-versions-response-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/roark/json-schema/roark-list-agent-versions-response-schema.json",
  "title": "ListAgentVersionsResponse",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/roark-agent-api-openapi.yml#/components/schemas/ListAgentVersionsResponse",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/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"
  ],
  "$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."
    },
    "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"
      ],
      "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."
        },
        "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-list-agent-versions-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.