API Overview¶

The RunAgents API lets you programmatically deploy agents, register tools, manage model providers, validate and apply action plans, orchestrate runs, and handle approvals.

Base URL¶

RunAgents API clients use the URL they receive for their trial, company, or workspace.

https://1406e38143ac0e57.try.runagents.io/api/v1

https://acme.runagents.io/api/v1

https://acme.runagents.io/api/v1/workspaces/revops

The base URL carries tenant and workspace context. Kubernetes namespaces remain internal to RunAgents.

Authentication¶

Every programmatic control-plane API request should include a workspace API key:

X-RunAgents-API-Key: <ra_ws_...>

Workspace API keys authorize access to the tenant/workspace carried by the base URL. Do not send ra_ws_... keys as Authorization: Bearer tokens on hosted trial or company URLs; that header is reserved for connected OIDC/JWT identity flows.

You can create and rotate workspace API keys from Settings in the RunAgents Console or programmatically through the auth endpoints documented in the canonical OpenAPI contract.

curl https://acme.runagents.io/api/v1/workspaces/revops/agents \
  -H "X-RunAgents-API-Key: ra_ws_abc123..."

import requests

headers = {"X-RunAgents-API-Key": "ra_ws_abc123..."}
resp = requests.get(
    "https://acme.runagents.io/api/v1/workspaces/revops/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.

OpenAPI Contract¶

The canonical machine-readable contract for the public programmatic API is maintained at openapi/openapi.yaml and mirrored into the docs site:

• Full OpenAPI contract (openapi.yaml)
• Focused action plans fragment (action-plans-openapi.yaml)

Use the full contract as the source for generated SDK, CLI, and assistant artifacts. The action plans fragment is kept as a focused reference for the deterministic validate/apply flow.

API Endpoints at a Glance¶