> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the API

> Run agents, manage state, and operate AgentOS through its REST API.

The AgentOS API exposes agents, teams, workflows, and runtime state over REST. Call it from a product frontend or any HTTP client.

```bash theme={null}
curl http://localhost:7777/agents/support-agent/runs \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "message=Where is my order?" \
  -d "user_id=customer-42" \
  -d "session_id=order-support-42" \
  -d "stream=false"
```

The response includes the run output, `run_id`, and `session_id`. Reuse the same `session_id` to group later runs in the same thread. Configure [chat history](https://agno-v2.mintlify.site/history/overview.md) when the model needs messages from earlier runs.

Teams and workflows use the same run pattern:

| Component | Run endpoint |
| - | - |
| Agent | `POST /agents/{agent_id}/runs` |
| Team | `POST /teams/{team_id}/runs` |
| Workflow | `POST /workflows/{workflow_id}/runs` |

## Discover an Instance

`GET /info` returns the metadata a client needs before making authenticated calls. The endpoint is public.

```bash theme={null}
curl http://localhost:7777/info
```

| Field | Description |
| - | - |
| `auth_mode` | Active authentication mode: `none`, `security_key`, or `jwt` |
| `agent_count`, `team_count`, `workflow_count` | Number of registered runtime components |
| `mcp.enabled` | Whether the MCP server is mounted |
| `mcp.path` | MCP mount path when enabled |
| `mcp.oauth` | OAuth discovery details when the MCP endpoint uses OAuth |
| `agno_version` | Agno version running on the instance |

Use `GET /config` to retrieve component IDs, database IDs, interfaces, and domain configuration. Send credentials when `auth_mode` requires them.

## API Surfaces

| Task | Resources |
| - | - |
| Execute application logic | Agents, teams, workflows, runs |
| Manage conversation and user state | Sessions, memories, learnings |
| Manage retrieval content | Knowledge, content sources, search |
| Measure behavior | Evaluations, metrics, traces |
| Control sensitive operations | Approvals, run continuation, cancellation |
| Automate recurring work | Schedules and schedule runs |
| Operate the runtime | Configuration, models, databases, service accounts |

See the [API reference](https://agno-v2.mintlify.site/reference-api/overview.md) for every path and schema.

## Stream Run Events

Run endpoints stream Server-Sent Events by default. Use `curl -N` to print events as they arrive:

```bash theme={null}
curl -N http://localhost:7777/agents/support-agent/runs \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "message=Investigate this account" \
  -d "stream=true"
```

Set `stream=false` when the caller needs one JSON response after the run completes.

## Pass Runtime Context

Run endpoints accept JSON-encoded form fields alongside the message:

| Field | Use |
| - | - |
| `dependencies` | Values available to tools and runtime functions |
| `session_state` | State carried through the current session |
| `metadata` | Application metadata stored with the run |
| `knowledge_filters` | Filters applied during knowledge retrieval |
| `output_schema` | JSON Schema for structured output |

```bash theme={null}
curl http://localhost:7777/agents/story-writer/runs \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "message=Write a short story" \
  -d 'dependencies={"reader_age":10}' \
  -d 'metadata={"source":"reading-app"}' \
  -d 'output_schema={"type":"object","properties":{"title":{"type":"string"},"story":{"type":"string"}},"required":["title","story"]}' \
  -d "stream=false"
```

## Authenticate Requests

Read `auth_mode` from `GET /info`, then send the matching credential:

| `auth_mode` | Credential |
| - | - |
| `none` | No authorization header |
| `security_key` | `Authorization: Bearer <OS_SECURITY_KEY>` |
| `jwt` | `Authorization: Bearer <jwt-token>` |

```bash theme={null}
curl http://localhost:7777/agents/support-agent/runs \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "message=Summarize my open tickets" \
  -d "stream=false"
```

Service-account tokens beginning with `agno_pat_` are bearer credentials for machine callers. They are available when the AgentOS instance has a database.

## REST or Python Client

| Client | Use when |
| - | - |
| REST API | The application uses another language, needs direct HTTP control, or calls a small set of endpoints |
| `AgentOSClient` | A Python application needs typed run outputs and helpers for sessions, memory, knowledge, and configuration |

```python theme={null}
import asyncio

from agno.client import AgentOSClient


async def main():
    client = AgentOSClient(base_url="http://localhost:7777")
    response = await client.run_agent(
        agent_id="support-agent",
        message="Where is my order?",
        user_id="customer-42",
        session_id="order-support-42",
    )
    print(response.content)


asyncio.run(main())
```

## Next Steps

| Task | Guide |
| - | - |
| Browse every endpoint | [API reference](https://agno-v2.mintlify.site/reference-api/overview.md) |
| Use the Python client | [AgentOS Client](https://agno-v2.mintlify.site/agent-os/client/agentos-client.md) |
| Configure authentication | [Security & Auth](https://agno-v2.mintlify.site/agent-os/security/overview.md) |
| Manage sessions | [Session management example](https://agno-v2.mintlify.site/agent-os/usage/client/session-management.md) |
| Run AgentOS as an MCP server | [AgentOS as MCP Server](https://agno-v2.mintlify.site/agent-os/mcp/mcp.md) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.