> ## 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 Overview

> orchagent REST API reference

The orchagent API lets you call agents, manage API keys, and track usage programmatically.

## Base URL

```
https://api.orchagent.io
```

## Authentication

Most endpoints require an API key:

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

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

## OpenAPI Specification

The full OpenAPI spec is available at:

```
https://docs.orchagent.io/api-reference/openapi.json
```

You can import this into tools like Postman, Insomnia, or use it to generate client libraries.

## Endpoint Categories

### Public (No Auth Required)

| Endpoint                                              | Description                           |
| ----------------------------------------------------- | ------------------------------------- |
| `GET /public/agents`                                  | List all public agents                |
| `GET /public/agents/{org}/{agent}/{version}`          | Get agent details                     |
| `GET /public/agents/{org}/{agent}/{version}/download` | Get download info for local execution |

### Agent Calls (Auth Required)

| Endpoint                                   | Description   |
| ------------------------------------------ | ------------- |
| `POST /{org}/{agent}/{version}/{endpoint}` | Call an agent |

### Usage Tracking (Auth Required)

| Endpoint                | Description        |
| ----------------------- | ------------------ |
| `GET /usage`            | Usage summary      |
| `GET /usage/timeseries` | Usage over time    |
| `GET /usage/breakdown`  | Usage by agent     |
| `GET /usage/tenants`    | Usage by tenant    |
| `GET /usage/logs`       | Detailed call logs |

### Author Usage (Auth Required)

| Endpoint                       | Description                  |
| ------------------------------ | ---------------------------- |
| `GET /author-usage`            | Usage of your agents         |
| `GET /author-usage/timeseries` | Your agents' usage over time |
| `GET /author-usage/breakdown`  | Your agents' usage breakdown |
| `GET /author-usage/logs`       | Your agents' call logs       |

### Agent Management (Auth Required)

| Endpoint                        | Description                                                                                                  |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `GET /agents`                   | List your agents                                                                                             |
| `POST /agents`                  | Register new agent (accepts `type`, `run_mode`, `runtime`, `loop`, `callable`)                               |
| `GET /agents/{id}`              | Get agent details (includes canonical `type`, `run_mode`, `execution_engine`, `callable`)                    |
| `PATCH /agents/{id}`            | Update agent (note: `run_mode`, `runtime`, `loop`, `callable` are immutable — publish new version to change) |
| `GET /agents/{id}/delete-check` | Check what confirmation is needed before deletion                                                            |
| `DELETE /agents/{id}`           | Delete an agent (soft delete, 30-day retention)                                                              |
| `POST /agents/{id}/fork`        | Fork a public agent into your workspace                                                                      |

The delete endpoint accepts an optional `mode=all_versions` query parameter to soft-delete every version of an agent at once. Without it, only the specified version is deleted.

The fork endpoint accepts an optional JSON body with `workspace_id` (target workspace) and `new_name` (rename the copy). Source must be public and source-available.

### Schedules (Auth Required)

| Endpoint                                                | Description                                    |
| ------------------------------------------------------- | ---------------------------------------------- |
| `GET /workspaces/{id}/schedules`                        | List schedules                                 |
| `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                                |
| `DELETE /workspaces/{id}/schedules/{schedule_id}`       | Delete schedule                                |
| `POST /workspaces/{id}/schedules/{schedule_id}/trigger` | Manually trigger execution                     |
| `POST /webhooks/{schedule_id}/{secret}`                 | Webhook trigger (no auth, URL contains secret) |

### Services (Auth Required)

| 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   |
| `PATCH /workspaces/{id}/services/{service_id}`        | Update service config |
| `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      |

### Workspaces (Auth Required)

| Endpoint                       | Description                |
| ------------------------------ | -------------------------- |
| `GET /workspaces`              | List your workspaces       |
| `POST /workspaces`             | Create a workspace         |
| `GET /workspaces/{id}/members` | List workspace members     |
| `POST /workspaces/{id}/invite` | Invite member to workspace |

### Secrets (Auth Required)

| Endpoint                                 | Description                               |
| ---------------------------------------- | ----------------------------------------- |
| `GET /workspaces/{id}/secrets`           | List secret names (values never returned) |
| `PUT /workspaces/{id}/secrets`           | Create or update a secret                 |
| `DELETE /workspaces/{id}/secrets/{name}` | Delete a secret                           |

### Billing (Auth Required)

| Endpoint                 | Description                                   |
| ------------------------ | --------------------------------------------- |
| `GET /billing/balance`   | Get credit balance                            |
| `POST /billing/checkout` | Create Stripe Checkout session to add credits |
| `GET /billing/history`   | Get transaction history                       |

### API Keys (Auth Required)

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

## Response Format

### Success

```json theme={null}
{
  "data": { ... },
  "metadata": {
    "request_id": "req_abc123"
  }
}
```

### Error

```json theme={null}
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "is_retryable": false
  },
  "metadata": {
    "request_id": "req_abc123"
  }
}
```

## Rate Limits

* **Free tier:** 1,000 calls/day
* **Pro tier:** 10,000 calls/day

See rate limit headers in responses:

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

## SDKs

| Language   | Package          | Install                         |
| ---------- | ---------------- | ------------------------------- |
| Python     | `orchagent-sdk`  | `pip install orchagent-sdk`     |
| JavaScript | `orchagent-sdk`  | `npm install orchagent-sdk`     |
| CLI        | `@orchagent/cli` | `npm install -g @orchagent/cli` |

See the [SDK Reference](/building-agents/sdk) for full documentation.

## Need Help?

* [API Reference](/using-agents/api-reference) - Detailed endpoint documentation
* [Code Snippets](/using-agents/code-snippets) - Copy-paste examples
* [CLI Commands](/using-agents/cli-commands) - Command-line interface