> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orchagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Authentication, endpoints, request/response formats, and error handling

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:

```http theme={null}
Authorization: Bearer {api_key}
```

Get your API key from the [orchagent Dashboard](https://orchagent.io/dashboard).

## Calling an Agent

### Request Format

```http theme={null}
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

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```http theme={null}
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:

```http theme={null}
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:

```json theme={null}
{
  "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:

```http theme={null}
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1704067200
```

## Public Endpoints

These endpoints don't require authentication:

### List Public Agents

```http theme={null}
GET /public/agents
```

### Get Agent Details

```http theme={null}
GET /public/agents/{org}/{agent}/{version}
```

### Download Agent (for local execution)

```http theme={null}
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):

```json theme={null}
{
  "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"
  }
}
```

<Note>
  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.
</Note>

## 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 theme={null}
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:

```json theme={null}
{
  "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             |