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

# AgentOS API

> Learn how to use the AgentOS API to interact with your agentic system

AgentOS is a RESTful API that provides access to your agentic system.

It allows you to:

* **Run Agents / Teams / Workflows**: Create new runs for your agents, teams and workflows, either with a new session or a existing one.
* **Manage Sessions**: Retrieve, update and delete sessions.
* **Manage Memories**: Retrieve, update and delete memories.
* **Manage Knowledge**: Manage the content of your knowledge base.
* **Manage Evals**: Retrieve, create, delete and update evals.

<Note>
  This is the same API that powers the AgentOS Control Plane. However, the same endpoints can be used to power your own application!
</Note>

See the full [API reference](/reference-api/overview) for more details.

## Authentication

AgentOS supports bearer-token authentication to secure your instance.
When a Security Key is configured, all API routes require an `Authorization: Bearer <token>` header for access. Without a key configured, authentication is disabled.

For more details, see the [AgentOS Security](/agent-os/security) guide.

## Running your Agent / Team / Workflow

The AgentOS API provides endpoints:

* **Run an Agent**: `POST /agents/{agent_id}/runs`  (See the [API reference](/reference-api/schema/agents/create-agent-run))
* **Run a Team**: `POST /teams/{team_id}/runs`  (See the [API reference](/reference-api/schema/teams/create-team-run))
* **Run a Workflow**: `POST /workflows/{workflow_id}/runs`  (See the [API reference](/reference-api/schema/workflows/execute-workflow))

These endpoints support form-based input. Below is an example of how to run an agent with the API:

```bash theme={null}
curl --location 'http://localhost:7777/agents/agno-agent/runs' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'message=Tell me about Agno.' \
    --data-urlencode 'stream=True' \
    --data-urlencode 'user_id=john@example.com' \
    --data-urlencode 'session_id=session_123'
```

### Passing agent parameters

Agent, Team and Workflow `run()` and `arun()` endpoints all support additional parameters. See the [Agent arun schema](/reference/agents/agent#arun), [Team arun schema](/reference/teams/team#arun), [Workflow arun schema](/reference/workflows/workflow#arun) for more details.

To pass these parameters to your agent, team or workflow, via the AgentOS API, you can simply specify them as form-based parameters.

Below is an example where `dependencies` are passed to the agent:

```python dependencies_to_agent.py theme={null}
from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.os import AgentOS

# Setup the database
db = PostgresDb(id="basic-db", db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

# Setup basic agents, teams and workflows
story_writer = Agent(
    id="story-writer-agent",
    name="Story Writer Agent",
    db=db,
    markdown=True,
    instructions="You are a story writer. You are asked to write a story about a robot. Always name the robot {robot_name}",
)

# Setup our AgentOS app
agent_os = AgentOS(
    description="Example AgentOS to show how to pass dependencies to an agent",
    agents=[story_writer],
)
app = agent_os.get_app()


if __name__ == "__main__":
    agent_os.serve(app="dependencies_to_agent:app", reload=True)
```

Then to test it, you can run the following command:

```bash theme={null}
curl --location 'http://localhost:7777/agents/story-writer-agent/runs' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'message=Write me a 5 line story.' \
    --data-urlencode 'dependencies={"robot_name": "Anna"}'
```

### Cancelling a Run

You can cancel a running agent, team or workflow by using the appropriate endpoint.

For example, to cancel an agent run:

```bash theme={null}
curl --location 'http://localhost:7777/agents/story-writer-agent/runs/123/cancel'
```

* [Agent API reference](/reference-api/schema/agents/cancel-agent-run)
* [Team API reference](/reference-api/schema/teams/cancel-team-run)
* [Workflow API reference](/reference-api/schema/workflows/cancel-workflow-run)