> ## Documentation Index
> Fetch the complete documentation index at: https://phidatainc.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](/history/overview) 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](/reference-api/overview) 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](/reference-api/overview)                                |
| Use the Python client        | [AgentOS Client](/agent-os/client/agentos-client)                       |
| Configure authentication     | [Security & Auth](/agent-os/security/overview)                          |
| Manage sessions              | [Session management example](/agent-os/usage/client/session-management) |
| Run AgentOS as an MCP server | [AgentOS as MCP Server](/agent-os/mcp/mcp)                              |