REST API (Pulse v1)
Query AXO at decision time from your own systems — no ETL, no stale copies. Pulse is key-authenticated, scoped, and versioned, with a published OpenAPI 3.1 spec you can generate clients from.
Base URL & auth
All endpoints live under /api/pulse/v1/ and authenticate with a bearer key. Mint keys in Admin → Pulse; the pls_live_… plaintext is shown once. Each key carries scopes that determine what the endpoint returns.
| Scope | Type | Description |
|---|---|---|
| profile:read optional | scope | Read a profile snapshot: identity, segments, activity — no plaintext PII. |
| profile:read:pii optional | scope | Additionally return plaintext email / phone / name on profile reads. |
| segment:read optional | scope | List the profile IDs in a segment (cursor-paginated). |
Get a profile
Read one profile by exactly one identifier. Returns a ProfileSnapshot (identity, segments, activity, meta). Rate limit 60 req/min (burst 120).
| Parameter | Type | Description |
|---|---|---|
| profile_id optional | string | Look up by AXO profile ID. |
| visitor_id optional | string | Look up by first-party visitor ID. |
| email optional | string | Look up by plaintext email (requires profile:read:pii to return PII). |
| external_id optional | string | Look up by your own external identifier. |
| email_sha256 / phone_sha256 optional | string | Look up by a hashed identifier (privacy-preserving). |
curl -sS "https://axoapp.ai/api/pulse/v1/profile?email=customer@example.com" \
-H "Authorization: Bearer pls_live_YOUR_KEY"List segment members
Cursor-paginated profile IDs in a segment. Pass the returned next_cursor to page.
curl -sS "https://axoapp.ai/api/pulse/v1/segment/deliberator/members?limit=100" \
-H "Authorization: Bearer pls_live_YOUR_KEY"Errors
| Status | Type | Description |
|---|---|---|
| 400 optional | bad_request | Missing or conflicting query (supply exactly one identifier). |
| 401 optional | unauthorized | Missing or invalid bearer key. |
| 403 optional | insufficient_scope | The key lacks the scope the endpoint requires (e.g. PII without profile:read:pii). |
| 404 optional | not_found | No profile/segment matches the query. |
| 429 optional | rate_limited | Rate limit exceeded (60 req/min, burst 120). |
Also on Pulse
POST /api/pulse/v1/profiles/query evaluates a segment predicate (the same rule language as custom segments) and returns matching profile IDs, and /api/pulse/v1/webhooks manages key-scoped webhook subscriptions with a deliveries log. Neither is in the OpenAPI spec yet — ask AXO for the request shapes if you need them during an evaluation.
/api/pulse/v1/openapi.json — point Postman or an SDK generator at it.