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

# API Reference

> Apollo Space HTTP endpoints for programmatic integrations — auth conventions, pagination, dates, and identifiers.

<Note>
  **Public API under construction.** Apollo Space exposes a complete HTTP
  surface internally (consumed by the app itself), but the curation of what
  becomes a **stable public endpoint** is still in progress. This section
  will be filled in endpoint by endpoint as each one is ratified for external
  integration. If you need a specific endpoint before it appears here,
  reach out to **[support@apollospace.ai](mailto:support@apollospace.ai)**.
</Note>

## General conventions

### Authentication

All HTTP calls carry a **Bearer token** in the header:

```http theme={null}
Authorization: Bearer <id_token>
```

The `id_token` is the Cognito token issued after login. It has a short
expiration window (hours) — use the refresh token to renew it.

### Organization identity

Since the same user can belong to multiple organizations, every call must
specify **which org** is the context for the operation:

```http theme={null}
X-Organization-Id: <org-uuid>
```

Without this header (or with a UUID that does not belong to the user), the
call is rejected with 403.

### Versioning

Public endpoints live under `/v1/...`. Breaking changes will move to
`/v2/...` in the future — `/v1` is maintained in parallel for a minimum
window of 6 months after announcement.

### Dates and timestamps

* **Timestamps**: ISO 8601 with timezone — e.g. `"2026-06-26T17:45:13Z"`
* **Dates (no time)**: `YYYY-MM-DD` — e.g. `"2026-06-26"`
* **Timezone**: always UTC in responses. In queries, you may send with a
  timezone (Apollo Space converts to UTC internally).

### Identifiers

* Resource IDs (lead, conversation, pipeline, etc.) are **version 4 UUIDs**
* No auto-incremental IDs are exposed publicly — always UUID

### Pagination

Endpoints that return lists use **cursor-based pagination**:

```json theme={null}
{
  "items": [ ... ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAy..."
}
```

* For the next page: `?cursor=<next_cursor>`
* `next_cursor: null` means end of list
* Cursors **are not stable URLs** — do not persist them; use only for
  sequential navigation

### Error handling

All errors return JSON with a consistent shape:

```json theme={null}
{
  "error": {
    "code": "lead_not_found",
    "message": "No lead with the given id in this organization.",
    "request_id": "req_abc123"
  }
}
```

* `code`: stable identifier for the error family (use in your client)
* `message`: human-readable description, **not stable** across versions
* `request_id`: support ID — include it in your support request so the
  team can locate the log

### HTTP codes

| Code  | Meaning                                                       |
| ----- | ------------------------------------------------------------- |
| `200` | Success (response includes data)                              |
| `201` | Created (successful POST)                                     |
| `204` | Success with no response body (typical for DELETE)            |
| `400` | Client error (invalid body, missing parameter)                |
| `401` | Not authenticated or token expired                            |
| `403` | Authenticated but lacking permission for this action/resource |
| `404` | Resource does not exist (or does not belong to your org)      |
| `409` | Conflict (e.g. duplicate, race condition)                     |
| `429` | Rate limit                                                    |
| `500` | Internal error (includes request\_id for investigation)       |

### Rate limits

Endpoints have limits per **organization + operation type**. When you hit
the limit:

* Response `429 Too Many Requests`
* Header `Retry-After: <seconds>` indicates when to retry
* For sustained load above the default limit, contact support —
  we can raise the ceiling

### Idempotency

Billable `POST` operations support an optional idempotency header:

```http theme={null}
Idempotency-Key: <your-unique-uuid-for-this-operation>
```

If the call fails and you retry with the same key, Apollo Space **does not
duplicate** the effect (no double billing, no double email sends, etc.).
Recommended for any serious integration.

## Surfaces coming to this section

Endpoints **planned** for publication (as they stabilize):

* **Leads**: CRUD + filters + bulk import
* **Pipelines**: read + create + stage reordering
* **Agents**: programmatic invocation + reading traces from previous runs
* **Stars**: query balance, history, configure caps
* **Webhooks**: subscribe to events (lead created, new activity, reply
  detected)

Each will get its own page with schema + cURL example.

## Next steps

<CardGroup cols={2}>
  <Card title="Platform concepts" icon="book" href="/en/concepts/organizations">
    Before integrating, understand the org + agent model.
  </Card>

  <Card title="Support" icon="envelope">
    The endpoint you need isn't here yet? Send us a message at
    **[support@apollospace.ai](mailto:support@apollospace.ai)** with your use case.
  </Card>
</CardGroup>