API Reference

Base URL: https://api.orchagent.io

OpenAPI Specification

The auto-generated OpenAPI spec is available at:

https://api.orchagent.io/openapi.json

Import this into Postman, Insomnia, or any OpenAPI-compatible tool to explore all endpoints interactively.

Authentication

All authenticated endpoints require an API key in the Authorization header:

Authorization: Bearer {api_key}

Get your API key from the orchagent Dashboard.

Calling an Agent

Request Format

POST /{org}/{agent}/{version}/{endpoint}
Host: api.orchagent.io
Authorization: Bearer {api_key}
Content-Type: application/json
Accept: application/json

URL Parameters

Parameter	Description	Example
`org`	Organization slug	`acme`
`agent`	Agent name	`invoice-scanner`
`version`	Agent version	`v1`
`endpoint`	Agent endpoint	`analyze`

Optional Headers

Header	Description
`X-Orchagent-Max-Hops`	Maximum call chain depth (for orchestrator agents)
`X-Orchagent-Tenant`	Tenant ID for multi-tenant usage attribution
`X-Orchagent-Skills`	Comma-separated skill refs to add (e.g., `org/skill@v1,org/other@v1`)
`X-Orchagent-Skills-Only`	Use only these skills, ignoring agent defaults
`X-Orchagent-No-Skills`	Set to `true` to disable all skills
`X-Orchagent-Deadline-Ms`	Request deadline as epoch milliseconds

Response Format

Success Response

{
  "data": {
    // Agent-specific response fields
  },
  "warnings": [
    {
      "code": "LOW_CONFIDENCE",
      "field": "amount",
      "message": "Amount extracted with low confidence"
    }
  ],
  "metadata": {
    "request_id": "req_abc123",
    "processing_time_ms": 1250,
    "version": "v1"
  }
}

Error Response

{
  "error": {
    "code": "DOCUMENT_TOO_LARGE",
    "message": "Document exceeds 25MB size limit",
    "is_retryable": false
  },
  "metadata": {
    "request_id": "req_abc123"
  }
}

Error Codes

Code	HTTP Status	Retryable	Description
`INVALID_INPUT`	400	No	Request doesn’t match input schema
`UNAUTHORIZED`	401	No	Invalid or missing API key
`FORBIDDEN`	403	No	Caller lacks permission for this agent
`NOT_FOUND`	404	No	Agent or version doesn’t exist
`DOCUMENT_TOO_LARGE`	413	No	File exceeds size limit
`UNSUPPORTED_TYPE`	415	No	File type not supported
`UNPROCESSABLE`	422	No	Valid format but cannot process content
`INSUFFICIENT_CREDITS`	402	No	Not enough credits to call this paid agent
`RATE_LIMITED`	429	Yes	Too many requests, retry after wait
`TIMEOUT`	504	Yes	Request exceeded configured timeout
`LLM_ERROR`	502	Yes	Upstream LLM provider error
`INTERNAL_ERROR`	500	Yes	Unexpected agent error

File Upload

For agents that accept files, use multipart form data:

POST /{org}/{agent}/{version}/analyze
Content-Type: multipart/form-data

------Boundary
Content-Disposition: form-data; name="file"; filename="invoice.pdf"
Content-Type: application/pdf

{binary data}
------Boundary--

Multiple Files

To send multiple files, use the files[] array format:

POST /{org}/{agent}/{version}/analyze
Content-Type: multipart/form-data

------Boundary
Content-Disposition: form-data; name="files[]"; filename="doc1.pdf"
Content-Type: application/pdf

{binary data}
------Boundary
Content-Disposition: form-data; name="files[]"; filename="doc2.pdf"
Content-Type: application/pdf

{binary data}
------Boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{"format":"detailed"}
------Boundary--

Code Runtime Agent Input Contract

When files are uploaded to a code runtime agent, the agent receives a JSON manifest via stdin:

{
  "files": [
    {
      "path": "/tmp/uploads/doc1.pdf",
      "original_name": "doc1.pdf",
      "content_type": "application/pdf",
      "size_bytes": 1234567
    },
    {
      "path": "/tmp/uploads/doc2.pdf",
      "original_name": "doc2.pdf",
      "content_type": "application/pdf",
      "size_bytes": 2345678
    }
  ],
  "metadata": {"format": "detailed"}
}

Field	Description
`files[].path`	Absolute path to the file in the sandbox
`files[].original_name`	Original filename from upload
`files[].content_type`	MIME type of the file
`files[].size_bytes`	File size in bytes
`metadata`	Optional JSON metadata from the request

Your code runtime agent reads the files from their path locations and processes them.

Rate Limit Headers

Response headers indicate your limit status:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1704067200

Public Endpoints

These endpoints don’t require authentication:

List Public Agents

GET /public/agents

Get Agent Details

GET /public/agents/{org}/{agent}/{version}

Download Agent (for local execution)

GET /public/agents/{org}/{agent}/{version}/download

Returns the full agent data needed for local execution. Only works for agents with allow_local_download enabled.

Server-only agents (allow_local_download=false): Returns 403 DOWNLOAD_DISABLED
Paid agents: Returns 403 PAID_AGENT_SERVER_ONLY
Source-available agents (allow_local_download=true): Returns full agent data including prompt, manifest, and schemas

Response (source-available agent):

{
  "type": "tool",
  "name": "leak-finder",
  "version": "v1",
  "description": "Finds leaked secrets in your codebase",
  "run_mode": "on_demand",
  "execution_engine": "code_runtime",
  "callable": false,
  "source_url": "git+https://github.com/user/repo.git#subdirectory=leak-finder",
  "runtime": {
    "command": "python3 -m leak_finder.cli"
  }
}

The public detail endpoint (GET /public/agents/{org}/{agent}/{version}) also redacts prompt, manifest, and skill_files for server-only and paid agents. Only metadata (name, description, schemas, tags) is visible.

Authenticated Endpoints

Usage

Endpoint	Description
`GET /usage`	Your usage summary
`GET /usage/timeseries`	Usage over time
`GET /usage/breakdown`	Usage by agent
`GET /usage/logs`	Detailed call logs

API Keys

Endpoint	Description
`GET /api-keys`	List your API keys
`POST /api-keys`	Create new API key
`DELETE /api-keys/{id}`	Delete API key

Agents

Endpoint	Description
`GET /agents`	List your agents
`POST /agents`	Register new agent
`GET /agents/{id}`	Get agent details
`PATCH /agents/{id}`	Update agent
`POST /agents/{id}/upload`	Upload code bundle (code runtime agents only)
`GET /agents/{id}/logs`	Get execution logs (owner only)

Schedules

Endpoint	Description
`GET /workspaces/{id}/schedules`	List schedules (filter by agent, type)
`POST /workspaces/{id}/schedules`	Create cron or webhook schedule
`GET /workspaces/{id}/schedules/{schedule_id}`	Get schedule details
`PATCH /workspaces/{id}/schedules/{schedule_id}`	Update schedule (cron, timezone, enable/disable, alerts)
`DELETE /workspaces/{id}/schedules/{schedule_id}`	Delete schedule
`POST /workspaces/{id}/schedules/{schedule_id}/trigger`	Manually trigger execution
`GET /workspaces/{id}/schedules/{schedule_id}/events`	Get schedule events timeline
`GET /workspaces/{id}/schedules/{schedule_id}/runs`	Get schedule run history
`POST /workspaces/{id}/schedules/{schedule_id}/test-alert`	Send test alert to configured webhook

Public webhook endpoint (no authentication — URL contains secret):

Endpoint	Description
`POST /webhooks/{schedule_id}/{webhook_secret}`	Trigger agent via webhook (supports `idempotency-key` header)

Services

Endpoint	Description
`GET /workspaces/{id}/services`	List services
`POST /workspaces/{id}/services`	Deploy a new service
`GET /workspaces/{id}/services/{service_id}`	Get service details and events
`PATCH /workspaces/{id}/services/{service_id}`	Update service config, env vars, and secrets
`POST /workspaces/{id}/services/{service_id}/restart`	Restart a service
`DELETE /workspaces/{id}/services/{service_id}`	Delete a service
`GET /workspaces/{id}/services/{service_id}/logs`	Get service logs

Billing & Credits

Endpoint	Description
`GET /billing/balance`	Get your credit balance
`POST /billing/checkout`	Create Stripe Checkout session to add credits
`GET /billing/transactions`	List credit transactions (top-ups, charges, refunds)

Compute Usage

Endpoint	Description
`GET /usage/compute`	Get compute usage for sandbox agents

Versioning

Agents use URL-based versioning:

https://api.orchagent.io/{org}/{agent}/v1/analyze
https://api.orchagent.io/{org}/{agent}/v2/analyze

Authors increment version for breaking changes
Old versions remain accessible during 60-day deprecation period
Pin to specific versions in production

Deprecation Headers

When an agent version is deprecated:

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 1 Mar 2025 00:00:00 GMT
Link: </{org}/{agent}/v2/{endpoint}>; rel="successor-version"

Warnings Array

Successful responses may include warnings:

{
  "data": { ... },
  "warnings": [
    {
      "code": "LOW_CONFIDENCE",
      "field": "amount",
      "message": "Amount extracted with 60% confidence"
    }
  ]
}

Standard warning codes:

Code	Description
`LOW_CONFIDENCE`	Field value uncertain
`TRUNCATED`	Data was truncated
`DEPRECATED_FIELD`	Field will be removed in next version
`VALIDATION_SKIPPED`	Couldn’t validate a field

Get Started

Using Agents

Building Agents

Guides

Concepts

API Reference

OpenAPI Specification

Authentication

Calling an Agent

Request Format

URL Parameters

Optional Headers

Response Format

Success Response

Error Response

Error Codes

File Upload

Multiple Files

Code Runtime Agent Input Contract

Rate Limit Headers

Public Endpoints

List Public Agents

Get Agent Details

Download Agent (for local execution)

Authenticated Endpoints

Usage

API Keys

Agents

Schedules

Services

Billing & Credits

Compute Usage

Versioning

Deprecation Headers

Warnings Array

​OpenAPI Specification

​Authentication

​Calling an Agent

​Request Format

​URL Parameters

​Optional Headers

​Response Format

​Success Response

​Error Response

​Error Codes

​File Upload

​Multiple Files

​Code Runtime Agent Input Contract

​Rate Limit Headers

​Public Endpoints

​List Public Agents

​Get Agent Details

​Download Agent (for local execution)

​Authenticated Endpoints

​Usage

​API Keys

​Agents

​Schedules

​Services

​Billing & Credits

​Compute Usage

​Versioning

​Deprecation Headers

​Warnings Array

OpenAPI Specification

Authentication

Calling an Agent

Request Format

URL Parameters

Optional Headers

Response Format

Success Response

Error Response

Error Codes

File Upload

Multiple Files

Code Runtime Agent Input Contract

Rate Limit Headers

Public Endpoints

List Public Agents

Get Agent Details

Download Agent (for local execution)

Authenticated Endpoints

Usage

API Keys

Agents

Schedules

Services

Billing & Credits

Compute Usage

Versioning

Deprecation Headers

Warnings Array