Skip to main content
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.

​
General conventions

​
Authentication

All HTTP calls carry a Bearer token in the header: 
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: 
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: 
{
  "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: 
{
  "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

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

Platform concepts

Before integrating, understand the org + agent model.

Support

The endpoint you need isn’t here yet? Send us a message at support@apollospace.ai with your use case.