Events API¶
This document describes the Events API endpoints as implemented.
Overview¶
The Events API provides access to the canonical event stream. It supports polling for events, retrieving individual events, generating sample data for integration testing, and creating test events.
Base Path: /api/v1/events
Authentication: API Key via X-Api-Key header
Endpoints¶
List Events¶
Retrieves events with cursor-based pagination.
Method: GET
Path: /api/v1/events
Authentication: API Key with events:read scope
Rate Limit Bucket: read
Query Parameters¶
| Parameter | Required | Description |
|---|---|---|
types |
No | Comma-separated event types to filter (case-insensitive, normalized to lowercase) |
cursor |
No | Opaque pagination token from previous response |
limit |
No | Page size (1-200, default 50) |
Unknown query parameters return 400 Bad Request.
Response¶
200 OK: Returns EventsResponse containing array of event envelopes.
If more results are available, the X-Paging-Cursor response header contains the cursor for the next page.
Pagination¶
Cursor-based pagination uses (CreatedUtc, Id) tuple. This provides stable pagination even when new events are inserted during traversal.
To paginate:
1. Call without cursor to get first page
2. If X-Paging-Cursor header is present, call again with that value as cursor
3. Repeat until no X-Paging-Cursor header is returned
Events are ordered chronologically (oldest first within page).
Get Event by ID¶
Retrieves a specific event.
Method: GET
Path: /api/v1/events/{id}
Authentication: API Key with events:read scope
Rate Limit Bucket: read
Path Parameters¶
| Parameter | Description |
|---|---|
id |
Event ID (long integer) |
Response¶
- 200 OK: Returns event envelope
- 404 Not Found: Event does not exist or belongs to different company
Get Sample Events¶
Generates sample event data for integration testing. Used by Zapier for trigger setup.
Method: GET
Path: /api/v1/events/sample
Authentication: API Key with events:read scope
Rate Limit Bucket: read
Query Parameters¶
| Parameter | Required | Description |
|---|---|---|
type |
Yes | Event type to generate sample for |
count |
No | Number of samples (1-3, default 1) |
Response¶
- 200 OK: Returns array of sample event envelopes
- 400 Bad Request: Missing type, invalid event type, or count out of range
- 500 Internal Server Error: Sample generation failed
Sample events have stable fake IDs starting at 1000000 and slightly different timestamps for multiple samples.
Get Event Types¶
Returns list of all supported event types.
Method: GET
Path: /api/v1/events/types
Authentication: API Key with events:read scope
Rate Limit Bucket: read
Response¶
Returns object with event_types array containing:
- name - Event type identifier (e.g., client.created)
- label - Human-readable label (e.g., "Client Created")
- description - Description of when event fires
Create Test Event¶
Creates a test event in the database. Requires admin scope.
Method: POST
Path: /api/v1/events/test
Authentication: API Key with admin scope
Rate Limit Bucket: write
Request Body¶
| Field | Required | Description |
|---|---|---|
type |
Yes | Event type |
payload |
No | JSON string containing event payload |
metadata |
No | JSON string containing additional context |
dedupeKey |
No | Unique key for deduplication |
Validation¶
typeis requiredpayloadandmetadatamust be valid JSON strings (parsed and normalized)payloadsize limited to 256KBmetadatasize limited to 64KB- Total request body limited to 512KB
Response¶
- 202 Accepted: Returns
{ id, createdUtc } - 400 Bad Request: Invalid JSON, missing type, or size exceeded
Event Envelope Structure¶
| Field | Type | Description |
|---|---|---|
id |
long | Unique event identifier |
companyId |
int | Tenant identifier |
type |
string | Event type |
createdUtc |
datetime | Event creation timestamp |
payload |
string | JSON string with event data |
metadata |
string | JSON string with context |
JSON Handling¶
Payload and metadata are stored and returned as JSON strings, not parsed objects. Clients must parse the JSON themselves. This avoids JsonDocument/JsonElement lifecycle issues.
Deduplication¶
Events support deduplication via dedupeKey:
- If provided during creation, the system checks for existing events with the same key
- Keys are unique within a company
- Used to prevent duplicate events during retries
Event Retention¶
Events are retained for a configurable period: - Production: 7 days (default) - Development/Staging: 14 days (default)
After retention period, events are automatically purged along with related delivery logs.
For Event Types¶
See the Event Catalog document for the list of supported event types.