# Agent API (/features/api)



Agent-backed products need an API that covers the state and controls around every run. AgentOS provides REST endpoints for agents, teams, and workflows, plus sessions, memory, knowledge, traces, evaluations, schedules, approvals, and versioned components.

AgentOS registers run routes for your agents, teams, and workflows. Database-backed routes and opt-in features such as scheduling, tracing, and MCP depend on the AgentOS configuration. Browse the live API at `/docs` or fetch the spec from `/openapi.json`.

<video className="w-full rounded-lg" src="/videos/agentos-api-scroll.mp4" />

## Interfaces [#interfaces]

AgentOS can expose the same registered component through several interfaces. REST and SSE are on by default; add an MCP server, A2A, or a Slack interface as needed. Each interface uses the same registered agent.

## The surface area [#the-surface-area]

| Group                | What you can do                                                                                                                                                |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Runs**             | Create, list, cancel, continue paused runs, resume disconnected streams. Stream over SSE or run as background jobs.                                            |
| **Sessions**         | Create, list, rename, update, delete. Pull every run in a session. Enforce per-user scoping with user isolation.                                               |
| **Memory**           | Create, update, delete user memories. Search content, filter by topic, view per-user stats. Run optimization to compact token usage.                           |
| **Learnings**        | Create, list, update, delete learnings captured from runs. List the users they belong to.                                                                      |
| **Knowledge**        | Upload files, text, URLs, or content from S3, GCS, SharePoint, GitHub. Search via vector, keyword, or hybrid. List sources, files in a source, content status. |
| **Evals**            | Run accuracy, agent-as-judge, performance, and reliability evals. List, update, delete eval runs.                                                              |
| **Traces**           | List, search with a filter DSL, view full span trees, group by session. Inspect individual LLM calls and tool invocations.                                     |
| **Metrics**          | Daily aggregated runs, sessions, users, token usage, model breakdown. Refresh on demand.                                                                       |
| **Schedules**        | CRUD, enable, disable, trigger now. List historical runs of a schedule.                                                                                        |
| **Approvals**        | List pending approvals, resolve them, count by user.                                                                                                           |
| **Components**       | Version your agents, teams, and workflows. Manage drafts, publish, roll back to a previous version.                                                            |
| **Service Accounts** | Mint a service account token (returned once), list accounts, revoke them.                                                                                      |
| **Database**         | Migrate one or all database schemas to a target version.                                                                                                       |

## How a request looks [#how-a-request-looks]

Run endpoints accept `multipart/form-data` so a single call can carry text, files, and media. Agents, teams, and workflows share this request pattern; each response identifies the component type that ran. An agent request looks like this:

```bash
curl -X POST http://localhost:7777/agents/my-agent/runs \
  -F "message=Hello" \
  -F "user_id=alice" \
  -F "session_id=thread-42" \
  -F "stream=false"
```

```json
{
  "run_id": "run_abc123",
  "session_id": "thread-42",
  "user_id": "alice",
  "agent_id": "my-agent",
  "status": "COMPLETED",
  "content": "Hi Alice!",
  "created_at": 1777061700
}
```

Pass `stream=true` for Server-Sent Events. For background submission and polling, pass both `background=true` and `stream=false`, and configure the component with a database. AgentOS returns `202 Accepted` with the run and session IDs. See [Background Execution](/agent-os/background-execution/overview) for persistence and worker configuration.

## Adding your own routes [#adding-your-own-routes]

AgentOS is built on FastAPI. Register additional routes for webhooks, dashboards, and integrations. This dispatch example omits provider-specific request verification; verify a webhook’s signature before processing its event:

```python
# `agent_os` is your AgentOS instance; `agent` is an Agent registered with it
app = agent_os.get_app()

@app.post("/webhooks/stripe")
async def handle_stripe(event: dict):
    response = await agent.arun(
        f"Process Stripe event: {event}",
        user_id="system",
    )
    return {"ok": True, "agent_response": response.content}
```

The agent is a regular Python object. Call `agent.run(...)` or `await agent.arun(...)` from anywhere.

## Auth [#auth]

With `authorization=True` and a verification key, protected central REST routes accept a verified JWT or a valid configured service-account token in `Authorization: Bearer ...` and enforce the credential’s scopes. Public discovery and API documentation routes are exempt. Self-authenticating interfaces such as Slack, Telegram, and WhatsApp verify requests through their own interface middleware. Custom REST routes need explicit scope mappings when they require permissions beyond authentication. See [Service Accounts](/agent-os/security/authorization/service-accounts) for machine credentials.

See [Security & Auth](/features/security-and-auth) for the details.

## Developer Resources [#developer-resources]

* [AgentOS API guide](/agent-os/using-the-api)
* [AgentOS API reference](/reference-api/overview)
* [AgentOS MCP interface](/agent-os/mcp/mcp)
* [AgentOS client](/agent-os/client/overview)