Skip to main content
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)

EndpointDescription
GET /public/agentsList all public agents
GET /public/agents/{org}/{agent}/{version}Get agent details
GET /public/agents/{org}/{agent}/{version}/downloadGet download info for local execution

​
Agent Calls (Auth Required)

EndpointDescription
POST /{org}/{agent}/{version}/{endpoint}Call an agent

​
Usage Tracking (Auth Required)

EndpointDescription
GET /usageUsage summary
GET /usage/timeseriesUsage over time
GET /usage/breakdownUsage by agent
GET /usage/tenantsUsage by tenant
GET /usage/logsDetailed call logs

​
Author Usage (Auth Required)

EndpointDescription
GET /author-usageUsage of your agents
GET /author-usage/timeseriesYour agents’ usage over time
GET /author-usage/breakdownYour agents’ usage breakdown
GET /author-usage/logsYour agents’ call logs

​
Agent Management (Auth Required)

EndpointDescription
GET /agentsList your agents
POST /agentsRegister 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-checkCheck what confirmation is needed before deletion
DELETE /agents/{id}Delete an agent (soft delete, 30-day retention)
POST /agents/{id}/forkFork 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)

EndpointDescription
GET /workspaces/{id}/schedulesList schedules
POST /workspaces/{id}/schedulesCreate 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}/triggerManually trigger execution
POST /webhooks/{schedule_id}/{secret}Webhook trigger (no auth, URL contains secret)

​
Services (Auth Required)

EndpointDescription
GET /workspaces/{id}/servicesList services
POST /workspaces/{id}/servicesDeploy 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}/restartRestart a service
DELETE /workspaces/{id}/services/{service_id}Delete a service
GET /workspaces/{id}/services/{service_id}/logsGet service logs

​
Workspaces (Auth Required)

EndpointDescription
GET /workspacesList your workspaces
POST /workspacesCreate a workspace
GET /workspaces/{id}/membersList workspace members
POST /workspaces/{id}/inviteInvite member to workspace

​
Secrets (Auth Required)

EndpointDescription
GET /workspaces/{id}/secretsList secret names (values never returned)
PUT /workspaces/{id}/secretsCreate or update a secret
DELETE /workspaces/{id}/secrets/{name}Delete a secret

​
Billing (Auth Required)

EndpointDescription
GET /billing/balanceGet credit balance
POST /billing/checkoutCreate Stripe Checkout session to add credits
GET /billing/historyGet transaction history

​
API Keys (Auth Required)

EndpointDescription
GET /api-keysList your API keys
POST /api-keysCreate 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

LanguagePackageInstall
Pythonorchagent-sdkpip install orchagent-sdk
JavaScriptorchagent-sdknpm install orchagent-sdk
CLI@orchagent/clinpm install -g @orchagent/cli
See the SDK Reference for full documentation.

​
Need Help?