API overview

Use the API to send events from your backend, trigger transactional messages, start flows and merge identities. Apps use the SDKs, which call the SDK endpoints for you.

Base URL

https://api.true-engage.com/v1

Every path in these docs is relative to this URL. The environment (Test or Live) comes from your key, so there is one base URL for both.

An interactive reference is served at /docs on the API host.

Endpoints

Method and path	Key	Purpose
POST /events	Server or Data API key	Send server events
POST /transactional/:slug/send	Server key	Send a transactional message
POST /business-events/:name/activate	Server key	Activate a business event
POST /flows/:id/enter	Server key	Enter a user into a flow
POST /users/identity/promote	Server or Data API key	Promote an identity
POST /sdk/batch, GET /sdk/config	SDK app key	SDK ingest

Authentication

Kind	Header	Used for
SDK app key	X-TE-App-Key: test_xxxxxxxx	SDK endpoints. Public, no secret.
Server key, Basic	Authorization: Basic base64(appKey:secret)	Server endpoints
Server key, Bearer	Authorization: Bearer <appKey>.<secret>	Server endpoints

Server endpoints reject an SDK app key. See Authentication and API keys.

Response envelope

Every endpoint except /sdk/* wraps its answer in the same envelope:

{
  "requestId": "0b1c6f2e-6a1d-4c58-9f47-2b7d6d1f8a10",
  "data": { "accepted": 1, "rejected": 0, "batchId": "01J9Z3K8..." }
}

On failure, data is usually absent and code is set:

{
  "requestId": "0b1c6f2e-6a1d-4c58-9f47-2b7d6d1f8a10",
  "message": "This key lacks the required scope.",
  "code": "INSUFFICIENT_SCOPE"
}

Field	Meaning
requestId	Quote this when you contact support.
data	The result. On some failures it carries details.
message	Human-readable text. On validation errors it can be a list.
code	Stable machine-readable error code. Branch on this, never on message.

The /sdk/* endpoints return their payload directly, without the envelope. See SDK ingest.

See Errors for every code.

Rate limits

Limits apply per key and, on some endpoints, per source IP, in a rolling one-minute window.

Endpoint	Per key	Per IP
POST /events	6,000/min	1,200/min
POST /transactional/:slug/send	6,000/min	n/a
POST /business-events/:name/activate	5/hour and 20/day per environment	n/a
POST /flows/:id/enter	3,000/min	n/a
POST /users/identity/promote	600/min	n/a
POST /sdk/batch	6,000/min	300/min
GET /sdk/config	600/min	60/min

Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). When you exceed a limit you get 429 with code RATE_LIMITED and a Retry-After header in seconds. Wait that long, then retry. A key can also carry its own lower limit, set when you create it.

Idempotency

Retries are safe when you give the API a way to recognise them:

• POST /events: send a messageId per event. A repeat within 24 hours is ignored.
• POST /transactional/:slug/send: idempotencyKey is required. A repeat within 24 hours returns the first result.
• POST /users/identity/promote: naturally idempotent. A repeat returns noop.
• POST /sdk/batch: each item has a messageId, and the batch can carry X-TE-Batch-Id.

POST /business-events/:name/activate and POST /flows/:id/enter are not idempotent. Do not blindly retry them after a timeout.

Versioning

The version is in the path (/v1). Changes inside /v1 add optional fields and new endpoints. They do not rename or remove fields or error codes. The SDK endpoints are held stable for years, because apps in the field cannot be updated on demand.

Limits worth knowing

• Event names: up to 100 characters. Up to 50 properties per event. See Send server events.
• Up to 500 events per request.
• Event timestamps more than 48 hours in the future, or more than 30 days in the past, are rejected.