Roark · Schema

ChatCreate

Chat creation payload. Supports singular (agent/customer) or plural (agents/customers) formats.

CompanyVoice AITestingEvaluationBenchmarking

Properties

Name Type Description
startTimestamp string When the chat started (ISO 8601 format)
endTimestamp string When the chat ended (ISO 8601 format)
messages array Ordered list of messages exchanged during the chat
toolInvocations array List of tool invocations made during the chat
properties object Custom properties to include with the chat. These can be used for filtering and will show in the chat details page
traceId stringnull Optional OpenTelemetry trace ID for the chat. Surfaces the chat in the tracing tab.
externalId string A stable identifier from your own system (e.g. session ID, conversation ID) used to correlate this chat with OpenTelemetry traces. Set the same value as a `roark.external_id` span or resource attribut
agent object Single agent participating in the chat. Use this for the simpler API when you have only one agent.
agents array Agents participating in the chat. Each agent requires identification and prompt information.
customer object Single customer participating in the chat. Use this for the simpler API when you have only one customer.
customers array Customers participating in the chat.
View JSON Schema on GitHub

JSON Schema

roark-chat-create-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/roark/json-schema/roark-chat-create-schema.json",
  "title": "ChatCreate",
  "description": "Chat 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-chat-api-openapi.yml#/components/schemas/ChatCreate",
  "type": "object",
  "properties": {
    "startTimestamp": {
      "type": "string",
      "description": "When the chat started (ISO 8601 format)"
    },
    "endTimestamp": {
      "type": "string",
      "description": "When the chat ended (ISO 8601 format)"
    },
    "messages": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "$ref": "#/$defs/ChatMessageAgent"
          },
          {
            "$ref": "#/$defs/ChatMessageCustomer"
          }
        ]
      },
      "description": "Ordered list of messages exchanged during the chat"
    },
    "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"
          },
          "startTimestamp": {
            "type": "string",
            "description": "When the tool was invoked (ISO 8601). Must fall within the chat time range."
          },
          "endTimestamp": {
            "type": "string",
            "description": "When the tool execution completed (ISO 8601). 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",
          "startTimestamp"
        ]
      },
      "description": "List of tool invocations made during the chat"
    },
    "properties": {
      "type": "object",
      "additionalProperties": {},
      "description": "Custom properties to include with the chat. These can be used for filtering and will show in the chat details page"
    },
    "traceId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional OpenTelemetry trace ID for the chat. Surfaces the chat in the tracing tab."
    },
    "externalId": {
      "type": "string",
      "maxLength": 255,
      "description": "A stable identifier from your own system (e.g. session ID, conversation ID) used to correlate this chat 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/ChatAgentIdentificationByRoarkId"
            },
            {
              "$ref": "#/$defs/ChatAgentIdentificationByName"
            },
            {
              "$ref": "#/$defs/ChatAgentIdentificationByCustomId"
            }
          ]
        },
        {
          "type": "object",
          "properties": {
            "prompt": {
              "type": "object",
              "properties": {
                "resolvedPrompt": {
                  "type": "string",
                  "description": "The agent's system prompt used during this chat"
                }
              },
              "required": [
                "resolvedPrompt"
              ],
              "description": "Agent's prompt configuration (optional)"
            }
          }
        }
      ],
      "description": "Single agent participating in the chat. Use this for the simpler API when you have only one agent."
    },
    "agents": {
      "type": "array",
      "items": {
        "allOf": [
          {
            "anyOf": [
              {
                "$ref": "#/$defs/ChatAgentIdentificationByRoarkId"
              },
              {
                "$ref": "#/$defs/ChatAgentIdentificationByName"
              },
              {
                "$ref": "#/$defs/ChatAgentIdentificationByCustomId"
              }
            ]
          },
          {
            "type": "object",
            "properties": {
              "prompt": {
                "type": "object",
                "properties": {
                  "resolvedPrompt": {
                    "type": "string",
                    "description": "The agent's system prompt used during this chat"
                  }
                },
                "required": [
                  "resolvedPrompt"
                ],
                "description": "Agent's prompt configuration (optional)"
              }
            }
          }
        ],
        "description": "Agent participating in the chat with their identification and prompt"
      },
      "description": "Agents participating in the chat. Each agent requires identification and prompt information."
    },
    "customer": {
      "type": "object",
      "properties": {
        "label": {
          "type": [
            "string",
            "null"
          ],
          "description": "Label to identify this customer in the chat (e.g., \"user-01\", \"anonymous-visitor\")"
        },
        "phoneNumberE164": {
          "type": [
            "string",
            "null"
          ],
          "description": "Customer phone number in E.164 format (e.g., +14155551234), optional for chat customers"
        }
      },
      "required": [
        "phoneNumberE164"
      ],
      "description": "Single customer participating in the chat. Use this for the 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 chat (e.g., \"user-01\", \"anonymous-visitor\")"
          },
          "phoneNumberE164": {
            "type": [
              "string",
              "null"
            ],
            "description": "Customer phone number in E.164 format (e.g., +14155551234), optional for chat customers"
          }
        },
        "required": [
          "phoneNumberE164"
        ],
        "description": "Customer participating in the chat"
      },
      "description": "Customers participating in the chat."
    }
  },
  "required": [
    "startTimestamp",
    "endTimestamp",
    "messages"
  ],
  "$defs": {
    "ChatAgentIdentificationByCustomId": {
      "type": "object",
      "properties": {
        "customId": {
          "type": "string",
          "description": "Existing custom ID for a Roark agent"
        }
      },
      "required": [
        "customId"
      ]
    },
    "ChatAgentIdentificationByName": {
      "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"
    },
    "ChatAgentIdentificationByRoarkId": {
      "type": "object",
      "properties": {
        "roarkId": {
          "type": "string",
          "format": "uuid",
          "description": "Existing Roark agent ID"
        }
      },
      "required": [
        "roarkId"
      ]
    },
    "ChatMessageAgent": {
      "type": "object",
      "properties": {
        "role": {
          "type": "string",
          "const": "AGENT",
          "description": "The agent sent this message"
        },
        "text": {
          "type": "string",
          "minLength": 1,
          "description": "Message content"
        },
        "languageCode": {
          "type": "string",
          "description": "ISO language code (e.g., \"en\")"
        },
        "startTimestamp": {
          "type": "string",
          "description": "When the message was sent (ISO 8601). Must fall within the chat time range."
        },
        "endTimestamp": {
          "type": "string",
          "description": "When the message finished sending (ISO 8601). For instant messages, can equal startTimestamp."
        },
        "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 sent this message - used to match which agent from the agents array this message belongs to"
        }
      },
      "required": [
        "role",
        "text",
        "startTimestamp"
      ]
    },
    "ChatMessageCustomer": {
      "type": "object",
      "properties": {
        "role": {
          "type": "string",
          "const": "CUSTOMER",
          "description": "The customer sent this message"
        },
        "text": {
          "type": "string",
          "minLength": 1,
          "description": "Message content"
        },
        "languageCode": {
          "type": "string",
          "description": "ISO language code (e.g., \"en\")"
        },
        "startTimestamp": {
          "type": "string",
          "description": "When the message was sent (ISO 8601). Must fall within the chat time range."
        },
        "endTimestamp": {
          "type": "string",
          "description": "When the message finished sending (ISO 8601). For instant messages, can equal startTimestamp."
        },
        "customer": {
          "type": "object",
          "properties": {
            "phoneNumberE164": {
              "type": "string",
              "description": "Customer phone number in E.164 format"
            },
            "label": {
              "type": "string",
              "description": "Customer label"
            }
          },
          "description": "Metadata about the customer that sent this message - used to match which customer from the customers array this message belongs to"
        }
      },
      "required": [
        "role",
        "text",
        "startTimestamp"
      ]
    }
  }
}

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-chat-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.