Developer Portal & REST APIs

API Overview & Authentication

Orcha Agent OS exposes production REST and JSON-RPC APIs for programmatic query execution, tool discovery, and telemetry.

Developer Portal

Manage your organization's API keys in the Developer Portal (/developers). Administrators can issue keys with granular database access scopes, custom rate limits, and CORS origin whitelisting.

Authentication Methods

Requests can authenticate using either an Authorization: Bearer header or a custom x-api-key header:

bash

# Using Bearer Authorization Header
curl -X POST http://localhost:3000/api/chat \
  -H "Authorization: Bearer orcha_live_sk_9f82b7c4..." \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "How many orders in 2024?"}]}'

# Or using x-api-key Header
curl -X POST http://localhost:3000/api/chat \
  -H "x-api-key: orcha_live_sk_9f82b7c4..." \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "How many orders in 2024?"}]}'

Multi-Database Scoping & Security

CORS Origin Enforcement

Keys can be restricted to specific frontend domains (e.g. https://analytics.mycompany.com). Requests originating from unlisted domains will be rejected with HTTP 403 Forbidden.

Token Bucket Rate Limiting

Each API key is assigned an hourly or per-minute request quota (default: 60 RPM). Exceeding the rate limit returns HTTP 429 Too Many Requests with retry-after headers.