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

# API Reference

> Complete reference for the Octanist API

## Base URL

```
https://octanist.com/api
```

All endpoints are relative to this base URL.

## Response Format

All responses use a consistent envelope format.

<Info>
  `/api/check` is the only public endpoint that returns a minimal `{ "success": true }` response on success. Lead, stats, and ad spend endpoints use the full envelope shown below.
</Info>

### Success Response

```json theme={null}
{
  "success": true,
  "data": [...],
  "meta": {
    "pagination": {
      "limit": 50,
      "page": 1,
      "totalPages": 5,
      "total": 234,
      "hasMore": true
    },
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}
```

### Error Response

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable error message",
    "details": {}
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}
```

### Error Codes

| Code               | Description                          |
| ------------------ | ------------------------------------ |
| `UNAUTHORIZED`     | Missing or invalid API key           |
| `VALIDATION_ERROR` | Invalid request parameters or body   |
| `NOT_FOUND`        | Resource not found                   |
| `FORBIDDEN`        | Action is not allowed                |
| `CONFLICT`         | Resource conflict (e.g., duplicates) |
| `INVALID_DATE`     | Invalid date format                  |
| `INVALID_FILTER`   | Invalid filter parameter             |
| `INTERNAL_ERROR`   | Server error                         |

## Pagination

All list endpoints support pagination using `limit` and `page` parameters.

| Parameter | Type   | Default | Max                    | Description             |
| --------- | ------ | ------- | ---------------------- | ----------------------- |
| `limit`   | number | 50      | 100 (500 for ad-spend) | Results per page        |
| `page`    | number | 1       | -                      | Page number (1-indexed) |

### Pagination Response

```json theme={null}
{
  "meta": {
    "pagination": {
      "limit": 50,
      "page": 2,
      "totalPages": 5,
      "total": 234,
      "hasMore": true
    }
  }
}
```

### Iterating Through Pages

```bash theme={null}
# Page 1
curl "https://octanist.com/api/leads?limit=50&page=1"

# Page 2
curl "https://octanist.com/api/leads?limit=50&page=2"

# Continue while hasMore is true
```

## Rate Limiting

Currently, there are no rate limits on the API. This may change in the future.

## Compatibility

The current API keeps the old Octanist lead API behavior while adding pixel session support.

Existing integrations can keep using:

* `POST /api/leads` with lead fields, click IDs, UTM fields, consent fields, `website`, and `path`
* `PATCH /api/leads` with `changedTo` as the legacy alias for `status`, and `email` or `phone` as either a string or an ordered array of fallback identifiers
* `GET /api/leads?updated_after=...` as the legacy alias for `updatedAt[gte]`
* `sort=updated_at:desc` as the legacy alias for `sort=updatedAt:desc`

New integrations can also send `sessionId` to `POST /api/leads`. This links a backend-created lead to an existing Octanist pixel session.

## Changelog

| Version | Date    | Changes                                                                |
| ------- | ------- | ---------------------------------------------------------------------- |
| 2.2.0   | 2026-07 | Added ordered fallback email and phone identifiers to PATCH /api/leads |
| 2.1.0   | 2026-06 | Added pixel session attribution and kept legacy lead API compatibility |
| 1.1.0   | 2026-03 | Added POST /api/leads and PATCH /api/leads docs, fixed source values   |
| 1.0.0   | 2024-01 | Initial API release                                                    |