Endpoints

All endpoints require a JWT bearer token in the Authorization header. See Authentication for details.

Authorization: Bearer <token>

Agent Management

Method	Endpoint	Description
GET	/v1/agents/types	List supported agent types.
GET	/v1/agents	List all agents in the current tenant (includes global agents). Supports is_global filter.
POST	/v1/agents	Create a new agent with an initial version. Accepts optional versionLabel (max 128 chars). Pass validateOnly: true to validate the payload without persisting.
POST	/v1/agents/lookup	Look up an agent by name and optional version label.
PATCH	/v1/agents/{agent_id}	Update agent metadata (name, displayName, description). Pass validateOnly: true to validate without persisting.
DELETE	/v1/agents/{agent_id}	Delete an agent and corresponding versions and permissions.

Agent Versions

Method	Endpoint	Description
GET	/v1/agents/{agent_id}/versions	List all versions of an agent.
GET	/v1/agents/{agent_id}/versions/{version_id}	Get a specific agent version.
POST	/v1/agents/{agent_id}/versions	Add a new version to an existing agent. Pass validateOnly: true to validate the config without persisting.
POST	/v1/agents/versions/batch-get	Get multiple agents and versions in one request. Maximum 100 agent IDs per request.

Agent Invocation

Method	Endpoint	Description
POST	/v1/agents/{agent_id}/versions/{version_id}/invoke	Invoke a Tool or RAG agent.
POST	/v1/agents/{agent_id}/versions/{version_id}/invoke-stream	Invoke a Tool or RAG agent with streaming.
POST	/v1/agents/{agent_id}/versions/{version_id}/invoke-task	Invoke a Task agent.
POST	/v1/agents/{agent_id}/versions/{version_id}/invoke-task-stream	Invoke a Task agent with streaming.

tip

Use latest as the version_id to invoke the most recent version.

Runs (Async Invocation)

Method	Endpoint	Description
POST	/v1/agents/{agent_id}/runs	Create a run (async invocation). Returns immediately with status queued.
GET	/v1/agents/{agent_id}/runs	List runs for an agent. Supports status filter.
GET	/v1/agents/{agent_id}/runs/{run_id}	Get the current status of a run.
POST	/v1/agents/{agent_id}/runs/{run_id}/cancel	Cancel a run. Idempotent.
GET	/v1/agents/{agent_id}/runs/{run_id}:stream	Stream run output as SSE. Supports ?starting_after={streamId} for resumption.

info

Runs are the async alternative to the synchronous invoke endpoints. Submit a run, then poll GET .../runs/{run_id} or connect to the SSE stream for real-time output.

Run Statuses

Status	Description
queued	Run created, waiting for a worker to pick it up.
in_progress	Worker is executing the agent pipeline.
completed	Execution finished successfully. outputPayload is populated.
failed	Execution failed. error field contains details.
cancelling	Cancellation requested, worker is stopping.
cancelled	Run was cancelled before completion.

Create Run Request Body

{
  "invokeRequest": {
    "messages": [
      { "role": "user", "content": "Hello" }
    ]
  },
  "versionId": "optional-version-uuid"
}

Headers

Header	Required	Description
Idempotency-Key	No	UUID to prevent duplicate run creation on retries.

MCP Server Management

Method	Endpoint	Description
GET	/v1/mcp-servers	List all registered MCP servers.
POST	/v1/mcp-servers	Register a new MCP server.
GET	/v1/mcp-servers/{server_id}	Get details of a specific MCP server.
PUT	/v1/mcp-servers/{server_id}	Update an MCP server configuration.
DELETE	/v1/mcp-servers/{server_id}	Delete an MCP server.
POST	/v1/mcp-servers/{server_id}/validate	Trigger on-demand validation.
GET	/v1/mcp-servers/{server_id}/tools	List tools available on the server.

Files

Method	Endpoint	Description
POST	/v1/files	Request a presigned upload URL for Code Interpreter file uploads.

Models and Guardrails

Method	Endpoint	Description
GET	/v1/models	List supported LLM models. Supports filter[agentType].
GET	/v1/guardrails	List supported guardrails.

Service Health

Method	Endpoint	Description
GET	/health	Health check.

Query Parameters

Pagination

List endpoints support offset and limit query parameters:

Parameter	Type	Default	Description
offset	integer	0	Items to skip.
limit	integer	50	Max items to return.

Response includes:

{
  "pagination": {
    "totalItems": 42,
    "offset": 0,
    "limit": 50,
    "hasMore": false
  }
}

Filtering

Parameter	Endpoint	Type	Description
is_global	GET /v1/agents	boolean	Filter by global or tenant-specific agents.
filter[agentType]	GET /v1/models	string	Filter models by agent type.

OpenAPI Spec

Download the full spec: openapi.yaml