API

REST API reference

Everything the SDKs do, over plain HTTPS. JSON in, JSON out.

Base URL

https://api.alitycs.com

All requests use TLS; plain HTTP is refused.

Authentication

Event ingestion sends a publishable or secret key as Authorization: Bearer. Analytics reads send a secret key in X-Alitycs-API-Key and select its workspace with X-Workspace-Id. Do not combine the API-key and bearer channels on one read request.

curl -X POST https://api.alitycs.com/events \
  -H "Authorization: Bearer $ALITYCS_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json"

curl "https://api.alitycs.com/v1/events?startDate=2026-06-01&endDate=2026-06-30" \
  -H "X-Alitycs-API-Key: $ALITYCS_SECRET_KEY" \
  -H "X-Workspace-Id: $ALITYCS_WORKSPACE_ID"

Send events

POST/events

Field	Type		Notes
`batchId`	string	Required	Stable identifier for this delivery attempt
`sentAt`	integer	Required	Unix time in milliseconds
`events`	array	Required	Canonical event objects
`events[].event`	string	Required	Event name
`events[].eventId`	string	Required	Preserve together with timestamp across retries
`events[].timestamp`	integer	Required	Original event time in Unix milliseconds
`events[].userId / anonymousId`	string	Conditional	At least one identity is required
`events[].properties`	object	Optional	String values; up to 50 entries

NOW=$(date +%s000)
curl -X POST https://api.alitycs.com/events \
  -H "Authorization: Bearer $ALITYCS_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "batchId": "batch_purchase_01",
  "sentAt": $NOW,
  "events": [{
    "eventId": "evt_purchase_01",
    "event": "purchase_completed",
    "eventType": "track",
    "userId": "usr_1842",
    "anonymousId": "anon_purchase_01",
    "sessionId": "session_purchase_01",
    "timestamp": $NOW,
    "properties": { "amount": "96.40", "currency": "USD" },
    "context": { "sdkVersion": "rest-1.0.0", "sdkLanguage": "http" }
  }]
}
JSON

{
  "status": "batch published",
  "count": 1,
  "batchId": "batch_purchase_01"
}

The batch is atomic: Worker validates every event before publishing. If any event is invalid, the request returns 400and none of the batch is published. Keep the serialized request below the configured 1 MiB body limit.

Query events

GET/v1/events

startDate and endDateare required. Filter with repeated eventNames or eventTypes values and page with limit and offset. The response includes events plus pagination totals and hasMore.

curl "https://api.alitycs.com/v1/events?startDate=2026-06-01&endDate=2026-06-30&eventNames=signup_completed&limit=50&offset=0" \
  -H "X-Alitycs-API-Key: $ALITYCS_SECRET_KEY" \
  -H "X-Workspace-Id: $ALITYCS_WORKSPACE_ID"

Errors

Ingestion failures always include an errormessage. Authentication and rate-limit responses also include stable codes where documented. Branch first on the HTTP status, then on a code when one is present.

Status	Code	Meaning
400	`error`	Malformed batch or an invalid event
401	`authentication_failed`	Key is missing, malformed, or unknown
403	`missing_scope`	Key lacks the required scope or allowed origin
413	`error`	Request exceeds the configured body limit
429	`*_rate_limit_exceeded`	Too many requests — honor `Retry-After`
500	`error`	Retry with exponential backoff

Rate limits

Request and event limits come from the API key and current plan. Batching counts as one request while consuming the number of published events. Successful responses carry X-RateLimit-Limit and X-RateLimit-Remaining, plus the corresponding event-limit headers.