Roark · Schema
CallCreate
Call creation payload. Supports singular (agent/customer) or plural (agents/customers) formats.
CompanyVoice AITestingEvaluationBenchmarking
Properties
| Name | Type | Description |
|---|---|---|
| recordingUrl | string | URL of source recording (must be an accessible WAV, MP3, MP4, or OGG file). Can be a signed URL. |
| stereoRecordingUrl | string | URL of source stereo recording. Must be accessible. Can be a signed URL. Supported formats: WAV, MP3, MP4, OGG. |
| startedAt | string | When the call started (ISO 8601 format) |
| interfaceType | string | Interface type of the call (PHONE or WEB) |
| callDirection | string | Direction of the call (INBOUND or OUTBOUND) |
| endedStatus | string | High-level call end status, indicating how the call terminated |
| transcript | array | List of transcript entries made during the call |
| toolInvocations | array | List of tool invocations made during the call |
| properties | object | Custom properties to include with the call. These can be used for filtering and will show in the call details page |
| vapiCallId | string | The Vapi call ID (UUID) to link this call with OpenTelemetry trace data from Vapi. Used for matching calls with OTEL traces. |
| livekitRoomId | string | The LiveKit Cloud room ID to link this call with OpenTelemetry trace data from LiveKit. Used for matching calls with OTEL traces. |
| externalId | string | 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 attribut |
| agent | object | Single agent participating in the call. Use this for simpler API when you have only one agent. |
| agents | array | Agents participating in the call. Each agent requires identification and prompt information. |
| customer | object | Single customer participating in the call. Use this for simpler API when you have only one customer. |
| customers | array | Customers participating in the call. |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/roark/json-schema/roark-call-create-schema.json",
"title": "CallCreate",
"description": "Call creation payload. Supports singular (agent/customer) or plural (agents/customers) formats.",
"x-generated": "2026-11-10",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/roark-call-api-openapi.yml#/components/schemas/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": "#/$defs/TranscriptEntryAgent"
},
{
"$ref": "#/$defs/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": "#/$defs/AgentIdentificationByRoarkId"
},
{
"$ref": "#/$defs/AgentIdentificationByName"
},
{
"$ref": "#/$defs/AgentIdentificationByCustomId"
}
]
},
{
"type": "object",
"properties": {
"endpoint": {
"anyOf": [
{
"$ref": "#/$defs/AgentEndpointById"
},
{
"$ref": "#/$defs/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": "#/$defs/AgentIdentificationByRoarkId"
},
{
"$ref": "#/$defs/AgentIdentificationByName"
},
{
"$ref": "#/$defs/AgentIdentificationByCustomId"
}
]
},
{
"type": "object",
"properties": {
"endpoint": {
"anyOf": [
{
"$ref": "#/$defs/AgentEndpointById"
},
{
"$ref": "#/$defs/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"
],
"$defs": {
"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"
},
"AgentIdentificationByCustomId": {
"type": "object",
"properties": {
"customId": {
"type": "string",
"description": "Existing custom ID for a Roark agent"
}
},
"required": [
"customId"
]
},
"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"
},
"AgentIdentificationByRoarkId": {
"type": "object",
"properties": {
"roarkId": {
"type": "string",
"format": "uuid",
"description": "Existing Roark agent ID"
}
},
"required": [
"roarkId"
]
},
"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"
]
}
}
}
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-call-create"
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.