API Reference

AgentOS automatically generates RESTful API endpoints for all your agents, teams, and workflows. This reference covers all available endpoints, request/response formats, and examples.

Base URL

All API endpoints are relative to your AgentOS server:

http://localhost:7777

In production, replace with your actual domain:

https://api.yourdomain.com

Authentication

All endpoints (except /health) require authentication when security is enabled:

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:7777/agents

See the Authentication Guide for details on JWT tokens and RBAC.

Core Endpoints

Get Configuration

Retrieve the complete AgentOS configuration.

GET /config

endpoint

Returns OS configuration including available models, databases, agents, teams, workflows, and domain settings.

Required Scopes: system:read

curl http://localhost:7777/config

Response:

{
  "id": "my-agent-os",
  "description": "Production AI Assistant",
  "available_models": ["gpt-4o", "gpt-4.1"],
  "databases": ["9c884dc4-9066-448c-9074-ef49ec7eb73c"],
  "agents": [
    {
      "id": "research-agent",
      "name": "Research Agent",
      "model": "openai:gpt-4o"
    }
  ],
  "teams": [
    {
      "id": "research-team",
      "name": "Research Team"
    }
  ],
  "workflows": [],
  "session": {
    "dbs": [
      {
        "db_id": "9c884dc4-9066-448c-9074-ef49ec7eb73c",
        "domain_config": {"display_name": "Sessions"}
      }
    ]
  },
  "knowledge": {
    "knowledge_instances": [
      {
        "id": "agno_docs",
        "name": "Agno Docs",
        "db_id": "9c884dc4-9066-448c-9074-ef49ec7eb73c"
      }
    ]
  }
}

Health Check

Check if the AgentOS is running and healthy.

GET /health

endpoint

Returns health status. No authentication required.

Required Scopes: None (public endpoint)

curl http://localhost:7777/health

Response:

{
  "status": "healthy"
}

Agent Endpoints

List Agents

Get all available agents (filtered by user permissions).

GET /agents

endpoint

Returns list of agents the authenticated user has access to.

Required Scopes: agents:read

curl http://localhost:7777/agents

Response:

{
  "agents": [
    {
      "id": "research-agent",
      "name": "Research Agent",
      "description": "Agent for web research",
      "model": "openai:gpt-4o",
      "tools": ["WebSearchTools"],
      "has_knowledge": true,
      "has_memory": true
    }
  ]
}

Get Agent Details

Retrieve detailed information about a specific agent.

GET /agents/{agent_id}

endpoint

Returns complete agent configuration and capabilities.

Path Parameters:

agent_id (string, required) - The unique identifier of the agent

Required Scopes: agents:read or agents:{agent_id}:read

curl http://localhost:7777/agents/research-agent

Run Agent

Execute an agent with a message.

POST /agents/{agent_id}/runs

endpoint

Creates a new agent run with the provided message and optional media.

Path Parameters:

agent_id (string, required) - The unique identifier of the agent

Form Data Parameters:

message

string

required

The input message or prompt for the agent

session_id

string

Session ID for conversation continuity. If not provided, a new session is created.

user_id

string

User identifier for tracking and personalization

stream

boolean

default:"false"

Enable streaming responses via Server-Sent Events (SSE)

images

file[]

Image files to include in the request

audio

file[]

Audio files to include in the request

videos

file[]

Video files to include in the request

files

file[]

Document files to include in the request

Required Scopes: agents:run or agents:{agent_id}:run

curl -X POST http://localhost:7777/agents/research-agent/runs \
  -F "message=What is quantum computing?"

Response:

{
  "run_id": "run_abc123",
  "session_id": "session_xyz789",
  "agent_id": "research-agent",
  "content": "Quantum computing is a type of computing that uses quantum-mechanical phenomena...",
  "messages": [
    {
      "role": "user",
      "content": "What is quantum computing?"
    },
    {
      "role": "assistant",
      "content": "Quantum computing is..."
    }
  ],
  "metrics": {
    "time": 2.5,
    "input_tokens": 12,
    "output_tokens": 150
  },
  "model": "gpt-4o"
}

Get Agent Run

Retrieve details of a specific agent run.

GET /agents/{agent_id}/runs/{run_id}

endpoint

Returns the complete run details including messages and metrics.

Path Parameters:

agent_id (string, required) - The agent identifier
run_id (string, required) - The run identifier

Required Scopes: agents:read or agents:{agent_id}:read

curl http://localhost:7777/agents/research-agent/runs/run_abc123

Team Endpoints

List Teams

Get all available teams.

GET /teams

endpoint

Returns list of teams the authenticated user has access to.

Required Scopes: teams:read

curl http://localhost:7777/teams

Response:

{
  "teams": [
    {
      "id": "research-team",
      "name": "Research Team",
      "description": "Team for collaborative research",
      "model": "openai:gpt-4o",
      "members": [
        {"id": "researcher", "name": "Researcher"},
        {"id": "analyst", "name": "Analyst"}
      ]
    }
  ]
}

Run Team

Execute a team with a message.

POST /teams/{team_id}/runs

endpoint

Creates a new team run. Team coordinates member agents to complete the task.

Path Parameters:

team_id (string, required) - The unique identifier of the team

Form Data: Same as agent runs (message, session_id, user_id, etc.) Required Scopes: teams:run or teams:{team_id}:run

curl -X POST http://localhost:7777/teams/research-team/runs \
  -F "message=Research and summarize quantum computing"

Workflow Endpoints

List Workflows

Get all available workflows.

GET /workflows

endpoint

Returns list of workflows the authenticated user has access to.

Required Scopes: workflows:read

curl http://localhost:7777/workflows

Response:

{
  "workflows": [
    {
      "id": "content-workflow",
      "name": "Content Creation Workflow",
      "description": "Research and write content",
      "steps": [
        {"name": "research", "agent": "researcher"},
        {"name": "write", "agent": "writer"}
      ]
    }
  ]
}

Run Workflow

Execute a workflow.

POST /workflows/{workflow_id}/runs

endpoint

Creates a new workflow run. Executes all steps in sequence.

Path Parameters:

workflow_id (string, required) - The unique identifier of the workflow

Form Data: Same as agent runs (message, session_id, user_id, etc.) Required Scopes: workflows:run or workflows:{workflow_id}:run

curl -X POST http://localhost:7777/workflows/content-workflow/runs \
  -F "message=Create an article about AI"

Session Endpoints

List Sessions

Retrieve all sessions for a user or agent.

GET /sessions

endpoint

Returns list of conversation sessions.

Query Parameters:

user_id

string

Filter sessions by user ID

agent_id

string

Filter sessions by agent ID

limit

integer

default:"100"

Maximum number of sessions to return

Required Scopes: sessions:read

curl "http://localhost:7777/sessions?user_id=user-123&limit=10"

Response:

{
  "sessions": [
    {
      "session_id": "session_xyz789",
      "user_id": "user-123",
      "agent_id": "research-agent",
      "created_at": "2026-03-04T10:30:00Z",
      "updated_at": "2026-03-04T10:35:00Z",
      "message_count": 6
    }
  ]
}

Get Session

Retrieve complete session history.

GET /sessions/{session_id}

endpoint

Returns all messages and metadata for a session.

Path Parameters:

session_id (string, required) - The session identifier

Required Scopes: sessions:read

curl http://localhost:7777/sessions/session_xyz789

Response:

{
  "session_id": "session_xyz789",
  "user_id": "user-123",
  "agent_id": "research-agent",
  "messages": [
    {
      "role": "user",
      "content": "What is quantum computing?",
      "timestamp": "2026-03-04T10:30:00Z"
    },
    {
      "role": "assistant",
      "content": "Quantum computing is...",
      "timestamp": "2026-03-04T10:30:05Z"
    }
  ],
  "memory": {
    "topics": ["quantum computing", "technology"],
    "summary": "User learning about quantum computing"
  }
}

Delete Session

Delete a session and its history.

DELETE /sessions/{session_id}

endpoint

Permanently deletes the session and all associated data.

Path Parameters:

session_id (string, required) - The session identifier

Required Scopes: sessions:delete

curl -X DELETE http://localhost:7777/sessions/session_xyz789

Knowledge Endpoints

List Knowledge Bases

Get all available knowledge bases.

GET /knowledge

endpoint

Returns list of knowledge bases and their configurations.

Required Scopes: knowledge:read

curl http://localhost:7777/knowledge

Response:

{
  "knowledge_instances": [
    {
      "id": "agno_docs",
      "name": "Agno Docs",
      "description": "Agno framework documentation",
      "db_id": "9c884dc4-9066-448c-9074-ef49ec7eb73c",
      "table": "agno_knowledge",
      "document_count": 150
    }
  ]
}

Memory Endpoints

Get User Memory

Retrieve memory for a specific user.

GET /memory

endpoint

Returns user memory including facts, preferences, and conversation summaries.

Query Parameters:

user_id

string

required

User identifier

Required Scopes: memory:read

curl "http://localhost:7777/memory?user_id=user-123"

Metrics & Traces

Get Metrics

Retrieve execution metrics.

GET /metrics

endpoint

Returns performance metrics for agents, teams, and workflows.

Required Scopes: metrics:read

curl http://localhost:7777/metrics

Get Traces

Retrieve execution traces for debugging.

GET /traces

endpoint

Returns OpenTelemetry traces for agent executions.

Query Parameters:

run_id

string

Filter traces by run ID

limit

integer

default:"100"

Maximum number of traces to return

Required Scopes: traces:read

curl "http://localhost:7777/traces?run_id=run_abc123"

WebSocket Endpoints

Stream Agent Responses

Connect via WebSocket for real-time streaming.

WS /ws/agents/{agent_id}

endpoint

WebSocket endpoint for streaming agent responses.

Path Parameters:

agent_id (string, required) - The agent identifier

Query Parameters:

token

string

required

JWT authentication token

Example:

const ws = new WebSocket(
  'ws://localhost:7777/ws/agents/research-agent?token=YOUR_JWT_TOKEN'
);

ws.onopen = () => {
  ws.send(JSON.stringify({
    message: 'What is quantum computing?',
    session_id: 'session_xyz789'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Agent response:', data.content);
};

Error Responses

All endpoints return standard HTTP status codes:

Status Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid token
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn’t exist
422	Validation Error - Invalid request format
500	Internal Server Error
503	Service Unavailable - Feature not enabled

Error Response Format:

{
  "detail": "Error message describing what went wrong"
}

Examples:

// 401 Unauthorized
{
  "detail": "Invalid or expired token"
}

// 403 Forbidden
{
  "detail": "Access denied to run this agent"
}

// 404 Not Found
{
  "detail": "Agent with id 'unknown-agent' not found"
}

// 422 Validation Error
{
  "detail": [
    {
      "loc": ["body", "message"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Rate Limiting

AgentOS does not implement rate limiting by default. For production deployments, consider adding rate limiting via:

Nginx: Use limit_req module
API Gateway: AWS API Gateway, Kong, etc.
Application-level: FastAPI middleware like slowapi

Interactive Documentation

AgentOS automatically generates interactive API documentation:

Swagger UI: http://localhost:7777/docs
ReDoc: http://localhost:7777/redoc
OpenAPI JSON: http://localhost:7777/openapi.json

Use these for testing endpoints and exploring the API.

Next Steps

Getting Started

Build your first AgentOS application

Authentication

Secure your API with JWT and RBAC

Get Started

Core Building Blocks

Production Runtime

Memory & State

Knowledge & RAG

Advanced Features

Models

Tools & Integrations

​Base URL

​Authentication

​Core Endpoints

​Get Configuration

​Health Check

​Agent Endpoints

​List Agents

​Get Agent Details

​Run Agent

​Get Agent Run

​Team Endpoints

​List Teams

​Run Team

​Workflow Endpoints

​List Workflows

​Run Workflow

​Session Endpoints

​List Sessions

​Get Session

​Delete Session

​Knowledge Endpoints

​List Knowledge Bases

​Memory Endpoints

​Get User Memory

​Metrics & Traces

​Get Metrics

​Get Traces

​WebSocket Endpoints

​Stream Agent Responses

​Error Responses

​Rate Limiting

​Interactive Documentation

​Next Steps

Getting Started

Authentication

Build docs developers (and LLMs) love

Base URL

Authentication

Core Endpoints

Get Configuration

Health Check

Agent Endpoints

List Agents

Get Agent Details

Run Agent

Get Agent Run

Team Endpoints

List Teams

Run Team

Workflow Endpoints

List Workflows

Run Workflow

Session Endpoints

List Sessions

Get Session

Delete Session

Knowledge Endpoints

List Knowledge Bases

Memory Endpoints

Get User Memory

Metrics & Traces

Get Metrics

Get Traces

WebSocket Endpoints

Stream Agent Responses

Error Responses

Rate Limiting

Interactive Documentation

Next Steps