Base URL
All endpoints are relative to this base URL.
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 |
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) |
{
"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 pathPATCH /api/leads with changedTo as the legacy alias for statusGET /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.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 |
