Skip to content

cURL / REST Examples

You can call the Synapse API directly with cURL or any HTTP client. This page provides copy-paste examples for the most common operations.

Note

For SDK libraries with built-in retries and type safety, see JavaScript SDK or Python SDK.

Authentication

API Key (data-plane endpoints)

bash
# Header-based (recommended)
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" \
-d '{"event_name": "signup", "external_id": "user_123"}'
bash
# Basic Auth alternative
curl -X POST https://synapse-api.pyrx.tech/v1/events \
-H "Content-Type: application/json" \
-H "Authorization: Basic $(echo -n 'ws_k7x9m2p4:psk_live_a1b2c3d4...' | base64)" \
-d '{"event_name": "signup", "external_id": "user_123"}'

JWT (dashboard/control-plane endpoints)

bash
curl https://synapse-api.pyrx.tech/v1/workspace/members \
-H "Authorization: Bearer eyJhbGciOiJFUzI1NiIs..."

Ingest an Event

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" \
-d '{
"event_name": "purchase_completed",
"external_id": "user_12345",
"attributes": {
"order_id": "ord_abc123",
"amount": 99.99,
"currency": "USD"
},
"idempotency_key": "purchase_ord_abc123"
}'

Response (202):

json
{"event_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "status": "accepted"}

Upsert a Contact

bash
curl -X POST https://synapse-api.pyrx.tech/v1/contacts \
-H "Content-Type: application/json" \
-H "X-WORKSPACE-ID: ws_k7x9m2p4" \
-H "X-API-KEY: psk_live_a1b2c3d4e5f67890abcdef1234567890" \
-d '{
"external_id": "user_12345",
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"properties": {"plan": "growth", "company": "Acme"}
}'

Send a Transactional Email

bash
curl -X POST https://synapse-api.pyrx.tech/v1/send \
-H "Content-Type: application/json" \
-H "X-WORKSPACE-ID: ws_k7x9m2p4" \
-H "X-API-KEY: psk_live_a1b2c3d4e5f67890abcdef1234567890" \
-d '{
"to": "[email protected]",
"template_slug": "order-confirmation",
"data": {
"order_id": "ord_abc123",
"total": "$99.99"
}
}'

List Flows

bash
curl https://synapse-api.pyrx.tech/v1/flows \
-H "X-WORKSPACE-ID: ws_k7x9m2p4" \
-H "X-API-KEY: psk_live_a1b2c3d4e5f67890abcdef1234567890"

Create a Segment

bash
curl -X POST https://synapse-api.pyrx.tech/v1/segments \
-H "Content-Type: application/json" \
-H "X-WORKSPACE-ID: ws_k7x9m2p4" \
-H "X-API-KEY: psk_live_a1b2c3d4e5f67890abcdef1234567890" \
-d '{
"name": "Active Users",
"description": "Users who logged in this month",
"filters": {
"operator": "AND",
"conditions": [
{"field": "last_seen_at", "operator": "within_last", "value": "30d"}
]
}
}'

Error Handling

All errors return a JSON body with detail and code:

bash
# Example: rate limited
HTTP/1.1 429 Too Many Requests
Retry-After: 42
 
{"detail": "Rate limit exceeded", "code": "rate_limit_exceeded"}
bash
# Example: insufficient scope
HTTP/1.1 403 Forbidden
 
{"detail": "API key scope 'data' does not permit: flows:read", "code": "insufficient_scope"}

Always check:

  • 401: Invalid or expired credentials
  • 403: Insufficient scope/role or plan limit reached
  • 429: Rate limited -- use the Retry-After header
  • 422: Validation error -- check the request body

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1746528900

See Rate Limiting Guide for handling strategies.