Events API

Events are the primary data ingestion point for Synapse. Your application sends events when users take actions (sign up, purchase, page view), and Synapse uses these events to trigger flows, update contact profiles, and drive analytics.

Note

For a platform guide on events, see Events. For authentication details, see Authentication.

Authentication

Events API uses API key authentication with the data scope.

bash

curl -X POST https://synapse-api.pyrx.tech/v1/events \

-H "Content-Type: application/json" \

-H "X-WORKSPACE-ID: ws_k7x9m2p4" \

-H "X-API-KEY: psk_live_a1b2c3d4e5f67890abcdef1234567890"

Endpoints

Method	Path	Description
`POST`	`/v1/events`	Ingest a single event
`POST`	`/v1/events/batch`	Ingest up to 50 events in one request
`GET`	`/v1/events`	List events (JWT auth, dashboard)
`GET`	`/v1/events/{id}`	Get event details (JWT auth, dashboard)
`POST`	`/v1/events/trigger`	Trigger a test event (JWT auth, dashboard)
`POST`	`/v1/events/{id}/retrigger`	Re-trigger flow processing for an event (JWT auth, dashboard)

Ingest Event

POST /v1/events

Auth: API key (data scope)

Request Body

json

{

"event_name": "purchase_completed",

"external_id": "user_12345",

"attributes": {

"order_id": "ord_abc123",

"amount": 99.99,

"currency": "USD",

"items": ["widget-pro", "widget-basic"]

"contact_overrides": {

"email": "[email protected]",

"first_name": "Jane"

"idempotency_key": "purchase_ord_abc123",

"timestamp": "2026-05-06T10:15:30Z"

}

Field	Type	Required	Description
`event_name`	string	Yes	Snake-case event name (e.g., `purchase_completed`)
`external_id`	string	Yes	Your application's user ID for the contact
`attributes`	object	No	Event-specific data (used in templates and conditions)
`contact_overrides`	object	No	Update contact fields (email, first_name, last_name, phone, properties)
`idempotency_key`	string	No	Prevents duplicate processing (7-day TTL)
`timestamp`	string	No	ISO 8601 timestamp (defaults to server time)

Response (202 Accepted)

json

{

"event_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",

"status": "accepted"

}

Tip

Events are processed asynchronously. A 202 Accepted response means the event has been queued for processing, not that flows have been triggered yet.

Batch Ingest

POST /v1/events/batch

Auth: API key (data scope)

Send up to 50 events in a single request. Each event in the batch counts as 1 event against your monthly limit, but the entire batch counts as 1 request against the rate limit.

Request Body

json

{

"events": [

{

"event_name": "page_viewed",

"external_id": "user_123",

"attributes": {"page": "/pricing"}

{

"event_name": "page_viewed",

"external_id": "user_456",

"attributes": {"page": "/docs"}

}

]

}

List Events (Dashboard)

GET /v1/events

Auth: JWT (dashboard). Requires events:read permission.

Query Parameters

Parameter	Type	Default	Description
`search`	string		Search by event name or external ID
`event_name`	string		Filter by event name
`limit`	integer	50	Max items per page (max 100)
`offset`	integer	0	Pagination offset

Plan Limits

Plan	Monthly Events
Free	10,000
Starter	100,000
Growth	1,000,000
Enterprise	Unlimited

Exceeding the monthly event limit returns 403 with code plan_limit_reached.