REST · Pulse v1
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.
GEThttps://axoapp.ai/api/pulse/v1/…
Key scopes
| 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).
GET/api/pulse/v1/profileread
Query (exactly one)
| 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.
GET/api/pulse/v1/segment/{segmentId}/membersread
curl -sS "https://axoapp.ai/api/pulse/v1/segment/deliberator/members?limit=100" \
-H "Authorization: Bearer pls_live_YOUR_KEY"Errors
Error responses
| 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). |
OpenAPIA machine-readable OpenAPI 3.1 spec is served at
/api/pulse/v1/openapi.json — point Postman or an SDK generator at it.