API reference is being finalized. Request early access to get notified when it's ready.
REST API

OrchStack REST API

Everything you can do in Studio, you can do via API. Full CRUD for agents, workflows, runs, and knowledge.

Get API KeyOpenAPI Spec
Authentication

Secure by Default

Two authentication methods to fit your use case.

API Keys

Generate scoped API keys from the dashboard. Include in the Authorization header as a Bearer token. Best for server-to-server integrations.

Authorization: Bearer os_live_abc123...

OAuth 2.0

Standard OAuth 2.0 authorization code flow for user-facing applications. Supports PKCE for public clients and refresh tokens.

Authorization: Bearer <access_token>
Core Endpoints

Full CRUD API

Everything you can do in Studio, you can do via API.

MethodEndpointDescription
POST/v1/agentsCreate a new agent
GET/v1/agentsList all agents
GET/v1/agents/:idGet agent details
PATCH/v1/agents/:idUpdate an agent
DELETE/v1/agents/:idDelete an agent
POST/v1/agents/:id/runTrigger an agent run
GET/v1/runsList all runs with filters
GET/v1/runs/:idGet run details and trace
POST/v1/knowledgeCreate a knowledge base
POST/v1/knowledge/:id/uploadUpload documents
POST/v1/workflowsCreate a workflow
POST/v1/workflows/:id/executeExecute a workflow
Example

Request & Response

Trigger an agent run and get structured results.

Request
POST
POST /v1/agents/agt_abc123/run
Authorization: Bearer os_live_...
Content-Type: application/json

{
  "input": "Book a haircut for tomorrow at 3pm",
  "channel": "whatsapp",
  "user_id": "usr_xyz789"
}
Response
200 OK
{
  "run_id": "run_def456",
  "status": "completed",
  "output": "Booked! Haircut with Sarah at 3pm tomorrow.",
  "tokens": { "input": 142, "output": 38 },
  "duration_ms": 1240
}
Webhooks

Event-Driven Notifications

Subscribe to agent events and get real-time HTTP callbacks.

agent.run.completed

Fired when an agent run finishes successfully.

agent.run.failed

Fired when an agent run fails or times out.

agent.gate.pending

Fired when a human-in-the-loop gate is waiting for approval.

knowledge.indexed

Fired when a document finishes indexing.

Rate Limits

Tier-Based Limits

Generous defaults with clear upgrade paths.

TierRequestsBurstAgents
Free100/min20/sec3
Pro1,000/min100/sec25
Enterprise10,000/min1,000/secUnlimited
Capabilities

API Features

A modern API built for developer experience and reliability.

RESTful

Clean, predictable REST endpoints following standard HTTP conventions. JSON in, JSON out.

Webhooks

Subscribe to events and receive real-time HTTP callbacks when agent state changes.

Pagination & Filtering

Cursor-based pagination, field filtering, and sorting on all list endpoints.

Batch Operations

Create, update, or delete multiple resources in a single API call for efficiency.

Real-time Streaming

Stream agent responses token-by-token via Server-Sent Events for live UIs.

Idempotent Requests

Pass an Idempotency-Key header to safely retry requests without duplicate side effects.

Frequently Asked Questions

Start Integrating Today

Get your API key and make your first request in minutes.

Get API KeyView SDK

Now in early access · No credit card required