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

# API Overview

> Talk to your Apollo-1 agents and manage them programmatically — one API, two surfaces.

<div style={{ display: 'flex', gap: '8px', marginBottom: '16px' }}>
  <span style={{ background: '#22C55E', color: '#fff', padding: '2px 10px', borderRadius: '12px', fontSize: '13px', fontWeight: 500 }}>v1</span>
  <span style={{ background: 'rgba(129,105,255,0.15)', color: '#8169FF', padding: '2px 10px', borderRadius: '12px', fontSize: '13px', fontWeight: 500 }}>Stable</span>
</div>

The Apollo API is how your product talks to your agents. It has two surfaces
that share one base URL and one authentication flow:

<CardGroup cols={2}>
  <Card title="Messaging" icon="paper-plane" href="/api/messaging/send-messages">
    Run conversations: send messages (with SSE or WebSocket streaming), read
    transcripts, rerun interactions, inspect reasoning traces, and reach users
    on WhatsApp or SMS.
  </Card>

  <Card title="Management" icon="gear" href="/api/management/projects">
    Operate your workspace: projects, agents, versions and their configuration,
    conversation threads, and usage metrics.
  </Card>
</CardGroup>

## Base URL

```
https://api-v3.aui.io/apollo-api
```

Messaging endpoints live under `/messaging/v1`, management endpoints under
`/management/v1`. The WebSocket session shares the same host:
`wss://api-v3.aui.io/apollo-api/messaging/v1/session`.

## Authentication in one minute

Exchange your **publishable key** for a short-lived access token, then send it
as a Bearer token:

```bash theme={"dark"}
curl -X POST "https://api-v3.aui.io/apollo-api/management/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{ "grant_type": "publishable_key", "publishable_key": "pk_..." }'
```

The token identifies your agent — messaging calls never carry an `agent_id` in
the body. Management endpoints also accept an **organization API key** as an
alternative. See [Authentication](/api/authentication) for the full flow.

## A conversation in three calls

```bash Get a token theme={"dark"}
curl -X POST "https://api-v3.aui.io/apollo-api/management/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{ "grant_type": "publishable_key", "publishable_key": "pk_..." }'
```

```bash Send the first message theme={"dark"}
curl -X POST "https://api-v3.aui.io/apollo-api/messaging/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{ "text": "I want to dispute a charge", "user_id": "my-user-123" }'
```

The response includes a `thread_id` — a new thread was created for you. Pass
it back to continue the same conversation:

```bash Continue the conversation theme={"dark"}
curl -X POST "https://api-v3.aui.io/apollo-api/messaging/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{ "text": "It was from May 30th", "user_id": "my-user-123", "thread_id": "<thread_id>" }'
```

## Core concepts

<CardGroup cols={2}>
  <Card title="Threads" icon="message" href="/api/messaging/threads">
    A thread is one conversation with an agent. Threads are created
    automatically on the first message — no separate create call.
  </Card>

  <Card title="Interactions" icon="arrows-rotate">
    Each user message and its agent reply form an interaction. Interactions can
    be rerun with edited text, and every one produces a reasoning trace.
  </Card>

  <Card title="Traces" icon="code" href="/api/messaging/traces">
    The agent's reasoning, step by step: what it understood, which rules fired,
    and the decisions it took.
  </Card>

  <Card title="Agents, versions & projects" icon="robot" href="/api/management/agents">
    Agents live in projects. An agent's behavior is defined by its versions;
    exactly one version is live at a time.
  </Card>
</CardGroup>

## Explore

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Publishable keys, access tokens, and organization API keys.
  </Card>

  <Card title="Send messages" icon="paper-plane" href="/api/messaging/send-messages">
    REST, server-sent events, and reruns.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Every endpoint, schema, and error — generated from the live API.
  </Card>

  <Card title="Errors" icon="circle-exclamation" href="/api/errors">
    One error envelope with stable, machine-readable codes.
  </Card>
</CardGroup>