API Overview¶

The RunAgents API lets you programmatically deploy agents, register tools, manage model providers, orchestrate runs, and handle approvals. Everything you can do in the console is available via the API.

Base URL¶

All API requests are made to:

https://api.runagents.io

Authentication¶

Every API request must include an API key in the Authorization header:

Authorization: Bearer <api-key>

Obtain your API key from Settings in the RunAgents Console.

curl https://api.runagents.io/api/agents \
  -H "Authorization: Bearer ra_live_abc123..."

import requests

headers = {"Authorization": "Bearer ra_live_abc123..."}
resp = requests.get("https://api.runagents.io/api/agents", headers=headers)

Content Type¶

All request and response bodies use JSON:

Content-Type: application/json

Error Format¶

Errors return a JSON object with an error field and an appropriate HTTP status code:

{
  "error": "agent_name is required"
}

Standard Error Codes¶

Rate Limits¶

API requests are subject to rate limits. Current limits are configurable per account. If you exceed your rate limit, the API returns 429 Too Many Requests with a Retry-After header.

Pagination¶

List endpoints currently return all resources in a single response. Pagination will be introduced in a future API version for endpoints with large result sets.

Special Headers¶

RunAgents uses several special headers for identity propagation and run correlation:

These headers are primarily used by the agent runtime and SDK. You do not need to set them for standard API calls.

API Versioning¶

The RunAgents API is currently in v1alpha. While we aim for backward compatibility, breaking changes may occur before the stable v1 release.

Stable, versioned APIs (e.g., /v1/...) are planned for general availability. Subscribe for updates to be notified when versioned endpoints are available.

Interactive API Docs¶

API Endpoints at a Glance¶