API reference overview

Use the Runtype API to manage Flows, Agents, Tools, Records, Products, API keys, Model Configs, and Secrets.

Base URL

Send requests to the following base URL:

https://api.runtype.com/v1

Authentication

Authenticate each request with an API key:

1
Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your Runtype API key. For steps to create an API key, see Authentication.

Endpoints by category

Use the following categories to find the endpoints that you need.

Core resources

Use these endpoints to create and manage core resources:

Tools and integrations

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

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 cursor from an earlier response.

The API returns pagination metadata in the response:

1
{
2
  "data": [],
3
  "pagination": {
4
    "nextCursor": "YOUR_NEXT_CURSOR",
5
    "prevCursor": null,
6
    "hasMore": true,
7
    "hasPrev": false,
8
    "limit": 50,
9
    "currentOffset": 0
10
  }
11
}

Replace YOUR_NEXT_CURSOR with the cursor that the API returns. When hasMore is true, send that cursor as YOUR_CURSOR in the next request.

Error handling

The API returns a JSON error body with standard HTTP status codes. Use the following status codes to identify common errors:

• 400 Bad Request: Invalid parameters.
• 401 Unauthorized: Invalid API key.
• 403 Forbidden: Insufficient permissions.
• 404 Not Found: Resource does not exist.
• 429 Too Many Requests: Rate limit exceeded.
• 500 Internal Server Error: Server error.

Validation errors (400)

When the API rejects a request for schema validation, it can return 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:

1
{
2
  "error": "Validation error",
3
  "details": [
4
    {
5
      "code": "MISSING_REQUIRED_FIELD",
6
      "message": "Invalid input: expected string, received undefined",
7
      "path": "name"
8
    },
9
    {
10
      "code": "INVALID_ENUM",
11
      "message": "Invalid option",
12
      "path": "kind",
13
      "suggestion": "Expected one of: OPTION_A, OPTION_B."
14
    }
15
  ]
16
}

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 offending field. An empty string identifies the request root.
• suggestion: An actionable hint, such as the allowed values or accepted range.

OpenAPI specification

Download the full OpenAPI JSON specification and import it into your API client or code-generation tool.

The TypeScript SDK derives its core response and streaming types from this specification. The Python, Ruby, and Java SDKs also include hand-written client layers. The Fern-generated clients are available through the following properties:

• Python: RuntypeClient.api.
• Ruby: client.api.
• Java: runtype.api().

Use fields that appear in the OpenAPI contract. Do not depend on fields that the contract does not define.

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.