> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.runtype.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server. # API reference overview > Base URL, authentication, endpoint categories, pagination, streaming, and errors for the Runtype REST API. Use the Runtype API to run Flows and Agents and to manage Flows, Agents, Tools, Records, Products, Surfaces, Model Configs, and Secrets. ## Base URL Send requests to the following base URL: **`Base URL`** ```text title="Base URL" https://api.runtype.com/v1 ``` ## Authentication Most endpoints authenticate with a Runtype API key: **`Authorization header`** ```http title="Authorization header" Authorization: Bearer YOUR_API_KEY ``` Replace `YOUR_API_KEY` with your Runtype API key. For steps to create an API key, see [Authentication](/developer-guides/getting-started/authentication). Client Runtime endpoints, such as `POST /client/init` and `POST /client/chat`, don't use an API key. `POST /client/init` exchanges a client token (`ct_live_` or `ct_test_`) for a session, and later calls such as `POST /client/chat` send that `sessionId`. You create client tokens with the Client Tokens endpoints. For details, see [Client tokens and domain restrictions](/user-guide/products-surfaces/client-tokens-and-domain-restrictions). To call a Product's API Surface with a product API key, see [Calling your API endpoints](/user-guide/products-surfaces/calling-your-api-endpoints). ## Endpoints by category The following tables list common starting points. The API reference sidebar lists every endpoint. ### Execution Use these endpoints to run Flows and Agents and to check their results: | Category | Description | Key endpoints | | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | [Dispatch](/api-reference/runtype-api/dispatch/execute-a-flow-or-agent) | Run a Flow or an Agent. | `POST /dispatch` | | [Executions](/api-reference/runtype-api/executions/poll-an-asynchronous-execution) | Poll or stream an execution that you started. | `GET /executions/{executionId}/status`, `GET /executions/{executionId}/events` | | [Runs](/api-reference/runtype-api/runs/list-runs) | Review past Flow and Agent runs. | `GET /runs`, `GET /runs/{executionId}` | | [Batch](/api-reference/runtype-api/batch/submit-a-batch-flow-execution) | Run a Flow over many Records. | `POST /batch/flow`, `GET /batch/status/{id}` | | [Events](/api-reference/runtype-api/events/poll-product-events) | Poll product events, such as failed runs and approval requests. For the polling loop, see [Watch product events](/developer-guides/guides/watch-product-events). | `GET /events`, `GET /events/types` | ### Core resources Use these endpoints to create and manage core resources: | Category | Description | Key endpoints | | ------------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------- | | [Flows](/api-reference/runtype-api/flows/list-flows) | Multi-step AI workflows. | `GET /flows`, `POST /flows` | | [Agents](/api-reference/runtype-api/agents/list-agents) | Tool-using AI agents. | `GET /agents`, `POST /agents` | | [Records](/api-reference/runtype-api/records/list-records) | Structured data that Agents and Flows can use. | `GET /records`, `POST /records` | | [Products](/api-reference/runtype-api/products/list-products) | Groups Capabilities and Surfaces for deployment. | `GET /products`, `POST /products` | | [Surfaces](/api-reference/runtype-api/surfaces/list-surfaces) | Channels where users reach a Product. | `GET /surfaces`, `GET /surfaces/{surfaceId}` | | [Skills](/api-reference/runtype-api/skills/list-skills) | Context bundles that Agents can load. | `GET /skills`, `POST /skills` | ### Tools and integrations Use these endpoints to configure Tools, Secrets, Model Configs, and Integrations: | Category | Description | Key endpoints | | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------- | | [Tools](/api-reference/runtype-api/tools/list-tools) | Custom and built-in Tools. | `GET /tools`, `POST /tools` | | [Secrets](/api-reference/runtype-api/secrets/list-secrets-metadata-only) | Store secrets and read their metadata. Values are never returned. | `GET /secrets`, `POST /secrets` | | [Model Configs](/api-reference/runtype-api/model-configs/list-model-configurations) | Model provider configuration. | `GET /model-configs`, `POST /model-configs` | | [Integrations](/api-reference/runtype-api/integrations/list-integrations) | Connected third-party accounts and services. | `GET /integrations`, `GET /integrations/connections` | ### Testing and automation Use these endpoints to test Agents and Flows and to run them on a timetable: | Category | Description | Key endpoints | | ---------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------ | | [Evals](/api-reference/runtype-api/evals/list-eval-suites) | Test suites that score Agent and Flow output. | `GET /eval/suites`, `POST /eval/suites/{id}/run` | | [Schedules](/api-reference/runtype-api/schedules/list-schedules) | Run Flows and Agents on a schedule. | `GET /schedules`, `POST /schedules` | ### Access and product delivery Use these endpoints to issue client tokens, run client sessions, and manage conversations: | Category | Description | Key endpoints | | --------------------------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | [Client Tokens](/api-reference/runtype-api/client-tokens/list-client-tokens) | Browser and client access tokens. | `GET /client-tokens`, `POST /client-tokens` | | [Client Runtime](/api-reference/runtype-api/client-runtime/initialize-a-client-session) | Browser chat sessions that use a client token. | `POST /client/init`, `POST /client/chat`, `POST /client/resume`, `POST /client/approve`, `POST /client/feedback` | | [Conversations](/api-reference/runtype-api/conversations/list-conversations) | Conversation state and messages. | `GET /conversations`, `POST /conversations` | ## Common patterns ### Pagination Use the `limit` and `cursor` query parameters to paginate list responses: **`List records`** ```bash title="List records" curl "https://api.runtype.com/v1/records?limit=50&cursor=YOUR_CURSOR" \ -H "Authorization: Bearer YOUR_API_KEY" ``` Replace `YOUR_API_KEY` with your Runtype API key and `YOUR_CURSOR` with the `nextCursor` value from the previous page. Omit `cursor` to get the first page. The API returns pagination metadata with each page: **`Pagination response`** ```json title="Pagination response" { "data": [], "pagination": { "nextCursor": "eyJpZCI6InJlY18wMWo...", "prevCursor": null, "hasMore": true, "hasPrev": false, "limit": 50, "currentOffset": 0 } } ``` To get the next page, pass `pagination.nextCursor` as `cursor`. Continue while `hasMore` is `true`. Treat cursors as opaque strings. List endpoints that accept a `direction` query parameter can also page backward: pass `prevCursor` as `cursor` and set `direction=prev`. Some list endpoints, such as `GET /runs`, page forward only and don't return `prevCursor`. ### Streaming and asynchronous responses Execution endpoints, such as `POST /dispatch` and `POST /agents/{id}/execute`, stream server-sent events (SSE) by default. To get a single JSON result instead, set `streamResponse` to `false`. For `POST /dispatch`, the field is inside `options`. For long-running work, send the `Prefer: respond-async` header. The API returns `202 Accepted` right away with an execution handle instead of waiting for the result: **`Start an asynchronous execution`** ```bash title="Start an asynchronous execution" curl https://api.runtype.com/v1/dispatch \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "Prefer: respond-async" \ -d '{ "agent": { "agentId": "agent_YOUR_AGENT_ID" }, "messages": [{ "role": "user", "content": "Summarize the orders from this week." }] }' ``` Replace `YOUR_API_KEY` with your Runtype API key and `agent_YOUR_AGENT_ID` with the ID of a saved Agent. The response includes `executionId` and `statusUrl`. Poll `GET /executions/{executionId}/status` until the execution reaches a final status, or stream its events from `GET /executions/{executionId}/events`. ### Safe retries Some write endpoints accept an `Idempotency-Key` header. When you repeat a request with the same key, the API returns the result of the first request instead of doing the work again. If you reuse a key for a different request, the API can return `409 Conflict`. Agent version publish and Agent alias updates support this header. `POST /dispatch` and `POST /agents/{id}/execute` also accept it for some saved Agents. For when it applies, see each endpoint's reference page. The same Agent version and alias endpoints accept an `If-Match` header with the revision that you expect. If the stored revision has changed, the API returns `412 Precondition Failed` and writes nothing. Updates to an existing `live` alias require `If-Match` and return `428 Precondition Required` without it. ### Error handling The API returns standard HTTP status codes. Most error responses have a JSON body with an `error` message: **`Error response`** ```json title="Error response" { "error": "Agent not found" } ``` Use the following status codes to identify common errors: * `400 Bad Request`: The request has invalid parameters. * `401 Unauthorized`: The API key or token is missing or invalid. * `402 Payment Required`: Your credit is exhausted, you reached your spend cap or a plan limit, or your plan doesn't include the feature. * `403 Forbidden`: The key doesn't have permission for this request. * `404 Not Found`: The resource doesn't exist. * `409 Conflict`: The request conflicts with the current state, such as a duplicate or an execution that can't be resumed. * `422 Unprocessable Content`: The request is well formed, but the API can't process it. * `429 Too Many Requests`: You exceeded a rate or usage limit, such as your plan's burst rate or a Test API key's execution limit. For a burst-rate `429`, wait for the number of seconds in the `Retry-After` header before you retry. * `500 Internal Server Error`: The server had an unexpected error. * `503 Service Unavailable`: The service is temporarily unavailable. Retry later. For the difference between `429` and `402`, see [Rate limits and usage](/user-guide/troubleshooting-faq/rate-limits-and-usage). For fixes to common failures, see [Common errors and solutions](/user-guide/troubleshooting-faq/common-errors-and-solutions) and [Authentication issues](/user-guide/troubleshooting-faq/authentication-issues). #### Validation errors When a request fails schema validation, the API returns `400` with an `error` string and a `details` array. Each detail can include a stable `code`, a `message`, a dotted `path`, and a `suggestion`. Use the following response shape for a validation error: **`Validation error`** ```json title="Validation error" { "error": "Validation error", "details": [ { "code": "MISSING_REQUIRED_FIELD", "message": "Invalid input: expected string, received undefined", "path": "name" }, { "code": "INVALID_ENUM", "message": "Invalid option", "path": "kind", "suggestion": "Expected one of: OPTION_A, OPTION_B." } ] } ``` In this example, `OPTION_A` and `OPTION_B` represent the allowed values for `kind`. Each detail uses the following fields: * `code`: A stable validation code, such as `MISSING_REQUIRED_FIELD`, `INVALID_TYPE`, `INVALID_ENUM`, `OUT_OF_RANGE`, `INVALID_FORMAT`, `UNRECOGNIZED_KEYS`, `INVALID_UNION`, `CUSTOM_VALIDATION`, or `VALIDATION_ERROR`. * `message`: A human-readable description of the problem. * `path`: A dotted path to the field with the problem. An empty string identifies the request root. * `suggestion`: An actionable hint, such as the allowed values or accepted range. The API returns at most 100 validation issues. If there are more, it adds one last detail with code `VALIDATION_ERROR`, an empty `path`, and a message with the number of issues that it omitted. ## OpenAPI specification Download the full [OpenAPI JSON](/openapi.json) specification and import it into your API client or code-generation tool. Use fields that appear in the OpenAPI specification. Don't depend on fields that the specification doesn't define. ## Client libraries The official SDKs call the same endpoints: * TypeScript: `npm install @runtypelabs/sdk`. The [Quickstart](/developer-guides/getting-started/quickstart) uses this SDK. * Python: `pip install runtype-sdk`. Call endpoints that have no convenience method through `client.api`. * Ruby: `gem install runtype`. Call endpoints that have no convenience method through `client.api`. * Java: call endpoints that have no convenience method through `runtype.api()`. ## Next steps Continue with one of these guides: * [Quickstart](/developer-guides/getting-started/quickstart): send your first API request. * [Working with tools](/developer-guides/guides/working-with-tools): configure and call Tools. * [Runtime tools](/developer-guides/guides/runtime-tools): define tools inside a dispatch request. * [Calling your API endpoints](/user-guide/products-surfaces/calling-your-api-endpoints): call a Product's API Surface. * [Run flows and agents with dispatch](/developer-guides/guides/dispatch): run a Flow or Agent through the dispatch API, with streaming and async execution. * [API error reference](/user-guide/troubleshooting-faq/api-error-reference): look up error codes, status codes, and limit responses. * [Runtype CLI reference](/developer-guides/getting-started/cli-reference): install the `runtype` CLI and look up each command group.