Public API reference

The public ingest API is served from https://api.engageapp.xyz. It is not the dashboard API and not the Actions Gateway. There are three authentication schemes depending on the endpoint.

Authentication

• Secret key — ingest endpoints only (contacts, events, enroll). Send X-API-Key: df_…. These keys do not grant campaign or dashboard access.
• Publishable key — client SDK (in-app) endpoints. Send X-Publishable-Key: pk_….
• Action key — Actions Gateway for bots. Send X-API-Key: act_…. Catalog: /api/v1/actions/openapi.yaml.

Server-side endpoints (secret key)

• POST /api/v1/public/contacts — batch upsert contacts and register devices.
• POST /api/v1/public/events — batch ingest behavioral events.
• POST /api/v1/public/enroll — enroll a contact into a campaign.

In-app SDK endpoints (publishable key)

These are called by the client SDKs; you normally don't call them directly.

• POST /api/v1/public/inapp/identify — resolve/create the contact for an external_id.
• GET /api/v1/public/inapp/messages?external_id=… — fetch the next pending takeover.
• POST /api/v1/public/inapp/messages/:id/events — report shown / clicked / dismissed.
• POST /api/v1/public/inapp/messages/:id/survey?external_id=… — send the answers to the survey in a takeover. Body: { "answers": [{ "question_id": "q1", "value": 9 }], "complete": true }.

Survey page endpoints (link token)

The hosted survey page uses these. The t query value is the personal token from the survey link; no API key is needed. See Surveys.

• GET /api/v1/public/surveys/:id?t=… — load the questions and any earlier answers. It never records an answer.
• POST /api/v1/public/surveys/:id/responses?t=… — save answers. Body as above; send "complete": true on the final submit. Returns 409 when the survey is not active.

When identity verification is enabled for your workspace, the in-app endpoints additionally require a valid X-Identity-Hash header. See the In-App Takeover setup guide.