API Overview

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:

Authorization: Bearer sk_live_xxx

Get your API key from the 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

{
  "data": { ... },
  "metadata": {
    "request_id": "req_abc123"
  }
}

Error

{
  "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:

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 for full documentation.

Need Help?

API Reference - Detailed endpoint documentation
Code Snippets - Copy-paste examples
CLI Commands - Command-line interface

Get Started

Using Agents

Building Agents

Guides

Concepts

API Reference

Base URL

Authentication

OpenAPI Specification

Endpoint Categories

Public (No Auth Required)

Agent Calls (Auth Required)

Usage Tracking (Auth Required)

Author Usage (Auth Required)

Agent Management (Auth Required)

Schedules (Auth Required)

Services (Auth Required)

Workspaces (Auth Required)

Secrets (Auth Required)

Billing (Auth Required)

API Keys (Auth Required)

Response Format

Success

Error

Rate Limits

SDKs

Need Help?

​Base URL

​Authentication

​OpenAPI Specification

​Endpoint Categories

​Public (No Auth Required)

​Agent Calls (Auth Required)

​Usage Tracking (Auth Required)

​Author Usage (Auth Required)

​Agent Management (Auth Required)

​Schedules (Auth Required)

​Services (Auth Required)

​Workspaces (Auth Required)

​Secrets (Auth Required)

​Billing (Auth Required)

​API Keys (Auth Required)

​Response Format

​Success

​Error

​Rate Limits

​SDKs

​Need Help?

Base URL

Authentication

OpenAPI Specification

Endpoint Categories

Public (No Auth Required)

Agent Calls (Auth Required)

Usage Tracking (Auth Required)

Author Usage (Auth Required)

Agent Management (Auth Required)

Schedules (Auth Required)

Services (Auth Required)

Workspaces (Auth Required)

Secrets (Auth Required)

Billing (Auth Required)

API Keys (Auth Required)

Response Format

Success

Error

Rate Limits

SDKs

Need Help?