API Reference - Docs Octanist

Base URL

https://octanist.com/api

All endpoints are relative to this base URL.

Response Format

All responses use a consistent envelope format.

/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.

Success Response

{
  "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

{
  "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

{
  "meta": {
    "pagination": {
      "limit": 50,
      "page": 2,
      "totalPages": 5,
      "total": 234,
      "hasMore": true
    }
  }
}

Iterating Through Pages

# 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

​Base URL

​Response Format

​Success Response

​Error Response

​Error Codes

​Pagination

​Pagination Response

​Iterating Through Pages

​Rate Limiting

​Compatibility

​Changelog

Base URL

Response Format

Success Response

Error Response

Error Codes

Pagination

Pagination Response

Iterating Through Pages

Rate Limiting

Compatibility

Changelog