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

JSON Schema

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

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.