You are viewing the docs for Archestra v1.4. View the latest docs
API Reference
Automate anything the web app does from scripts and CI: create agents, install MCP servers, change policies, and export costs and logs. The web app runs on this same API, and every endpoint checks the same permissions.
This API manages Archestra. To send model requests or call MCP tools, use the LLM Proxy or an MCP Gateway instead.
Authentication
Send an API key in the Authorization header, without a Bearer prefix:
curl -H "Authorization: arch_..." https://archestra.example.com/api/agents
A 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
- Go to Settings → Service Accounts and click Create service account.
- Give it a role that holds only the permissions the job needs.
- Open the account and click Create API key.
- To export organization-wide costs, the role needs
llmCost:read. Addmember:readto 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:readandlog: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.
Leave Out Agent Tools
Add includeTools=false to read agents without their tools. The tools are most of the response, because each one carries its name and description. These endpoints include them by default:
curl -H "Authorization: arch_..." "https://archestra.example.com/api/agents?includeTools=false"
toolsCountandsubagentsCountare always present.- With
includeTools=false,toolsis an empty array. It means "not requested", not "no tools assigned".