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

# API Reference

> Polos Orchestrator REST API

The Polos Orchestrator API provides programmatic access to manage agents, workflows, executions, events, and more.

## Base URL

```
http://localhost:8080/api/v1
```

For production deployments, replace with your orchestrator URL.

## Authentication

All API requests require:

* **Bearer token**: Your API key for authentication
* **Project ID header**: The project to operate on

```bash theme={null}
Authorization: Bearer your-api-key
X-Project-ID: your-project-id
```

Example request:

```bash theme={null}
curl -X GET "http://localhost:8080/api/v1/workflows" \
  -H "Authorization: Bearer your-api-key" \
  -H "X-Project-ID: your-project-id"
```

## Core Resources

<CardGroup cols={2}>
  <Card title="Workflows" icon="diagram-project" href="/api-reference/endpoints/workflows/get-all-workflows-for-a-project">
    Submit, query, and manage workflow executions
  </Card>

  <Card title="Agents" icon="robot" href="/api-reference/endpoints/agents/get-all-agents-for-a-project">
    Register and query agent definitions
  </Card>

  <Card title="Executions" icon="play" href="/api-reference/endpoints/executions/submit-a-workflow-for-execution">
    Submit workflows and manage running executions
  </Card>

  <Card title="Events" icon="bolt" href="/api-reference/endpoints/events/publish-events-to-a-topic">
    Publish and subscribe to events
  </Card>

  <Card title="Schedules" icon="clock" href="/api-reference/endpoints/schedules/create-a-schedule-for-a-workflow">
    Create and manage workflow schedules
  </Card>

  <Card title="Traces" icon="magnifying-glass" href="/api-reference/endpoints/traces/get-traces-with-optional-filters">
    Query execution traces and spans
  </Card>
</CardGroup>

## Common Operations

### Submit a workflow

```bash theme={null}
curl -X POST "http://localhost:8080/api/v1/workflows/my_workflow/run" \
  -H "Authorization: Bearer your-api-key" \
  -H "X-Project-ID: your-project-id" \
  -H "Content-Type: application/json" \
  -d '{"input": {"key": "value"}}'
```

### Resume a suspended execution

```bash theme={null}
curl -X POST "http://localhost:8080/api/v1/executions/{execution_id}/resume" \
  -H "Authorization: Bearer your-api-key" \
  -H "X-Project-ID: your-project-id" \
  -H "Content-Type: application/json" \
  -d '{"data": {"approved": true}}'
```

### Publish an event

```bash theme={null}
curl -X POST "http://localhost:8080/api/v1/events/publish" \
  -H "Authorization: Bearer your-api-key" \
  -H "X-Project-ID: your-project-id" \
  -H "Content-Type: application/json" \
  -d '{"topic": "orders/created", "data": {"order_id": "123"}}'
```