API reference overview

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:

https://api.runtype.com/v1

Authentication

Most endpoints authenticate with a Runtype API key:

Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your Runtype API key. For steps to create an API key, see 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. To call a Product’s API Surface with a product API key, see 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:

Core resources

Use these endpoints to create and manage core resources:

Tools and integrations

Use these endpoints to configure Tools, Secrets, Model Configs, and Integrations:

Testing and automation

Use these endpoints to test Agents and Flows and to run them on a timetable:

Access and product delivery

Use these endpoints to issue client tokens, run client sessions, and manage conversations:

Common patterns

Pagination

Use the limit and cursor query parameters to paginate list responses:

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:

{
  "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:

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": "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. For fixes to common failures, see Common errors and solutions and 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:

{
  "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 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 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: send your first API request.
• Working with tools: configure and call Tools.
• Runtime tools: define tools inside a dispatch request.
• Calling your API endpoints: call a Product’s API Surface.
• Run flows and agents with dispatch: run a Flow or Agent through the dispatch API, with streaming and async execution.
• API error reference: look up error codes, status codes, and limit responses.
• Runtype CLI reference: install the runtype CLI and look up each command group.