ReferenceAPI Reference

API Reference

Automate management tasks from scripts and CI: create agents, install MCP servers, change policies, and export costs and logs. Management endpoints check the same permissions as the web app.

These topic pages also include the LLM Proxy and MCP Gateway transport endpoints. Their authentication differs from management requests; check each operation before calling it.

Authentication

For management requests, send an API key in the Authorization header, without a Bearer prefix:

bash
curl -H "Authorization: arch_..." https://archestra.example.com/api/agents

A management request without a valid key returns 401. A key whose role lacks the endpoint's permission returns 403.

Use one of two kinds of key:

  • Personal API key: acts as you, with your current permissions. Use it for your own scripts.
  • Service account key: belongs to the organization, so it keeps working after the person who made it leaves. Use it for CI, scheduled jobs, and shared integrations.

Personal API Keys

Click your name in the sidebar, go to API Keys, and click Create API Key. Copy the key right away. You cannot view it again.

Service Accounts

  1. Go to Settings → Service Accounts and click Create service account.
  2. Give it a role that holds only the permissions the job needs.
  3. On the account's API Keys tab, click Create key.
  • To export organization-wide costs, the role needs llmCost:read. Add member:read to break costs down by person, agent, or virtual key; without it, those breakdowns cover only the account's own usage.
  • To export every log, the role needs log:read and log:admin.
  • To rotate a key, create a new one, move your clients to it, and delete the old one. Disabling or deleting the account stops all its keys.
  • For CI that can get an OIDC token, such as GitHub Actions, skip the key: use Workload Identity Federation.

Explore the API

Choose a topic below to find the endpoints, parameters, permissions, and response fields for your task. The OpenAPI document remains available for code generation.

Explore