# API Reference

> Find Archestra API endpoints by task, with request and response fields alongside each operation

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](https://archestra.ai/docs/reference/permissions) as the web app.

These topic pages also include the [LLM Proxy](https://archestra.ai/docs/reference/api/llm-proxy) and [MCP Gateway](https://archestra.ai/docs/reference/api/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`](https://archestra.ai/docs/reference/permissions#llmCost:read). Add [`member:read`](https://archestra.ai/docs/reference/permissions#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`](https://archestra.ai/docs/reference/permissions#log:read) and [`log:admin`](https://archestra.ai/docs/reference/permissions#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](https://archestra.ai/docs/admin/identity/workload-identity).

<span id="leave-out-agent-tools"></span>
## Explore the API

Choose a topic below to find the endpoints, parameters, permissions, and response fields for your task. The [OpenAPI document](https://raw.githubusercontent.com/archestra-ai/archestra/main/docs/openapi.json) remains available for code generation.

## Explore

- [Agents and Runtime](https://archestra.ai/docs/reference/api/agents.md): Create agents, choose their tools, and manage skills, plugins, hooks, and scheduled runs
- [A2A](https://archestra.ai/docs/reference/api/a2a.md): Connect Archestra agents to remote agents and manage agent-to-agent communication
- [MCP Gateway](https://archestra.ai/docs/reference/api/mcp-gateway.md): Send MCP protocol requests and connect MCP Apps to clients
- [MCP Servers and Catalog](https://archestra.ai/docs/reference/api/mcp.md): Manage MCP servers, catalog entries, and OAuth clients
- [LLM Proxy](https://archestra.ai/docs/reference/api/llm-proxy.md): Configure model access, limits, routing, and provider credentials; inspect request logs
- [Organization and Access](https://archestra.ai/docs/reference/api/organization.md): Manage organizations, teams, members, roles, API keys, and identity settings
- [Apps and Connections](https://archestra.ai/docs/reference/api/apps.md): Manage apps, connectors, connection setups, and integration credentials
- [Projects and Chat](https://archestra.ai/docs/reference/api/projects-chat.md): Manage projects, conversations, ChatOps, webhooks, and incoming email
- [Knowledge](https://archestra.ai/docs/reference/api/knowledge.md): Manage knowledge bases and files used for retrieval
- [Operations](https://archestra.ai/docs/reference/api/operations.md): Retrieve audit records and statistics, and inspect operational endpoints
- [API Playground](https://archestra.ai/docs/reference/api/playground.md): Explore the complete OpenAPI document and try requests against your own backend
