​

Synapse API

​

First request

curl --request POST \
  --url "$SYNAPSE_API_URL/v1/organizations/$ORG_ID/apps/$APP_ID/environments/$ENV_ID/subjects" \
  --header "Authorization: Bearer $SYNAPSE_ENVIRONMENT_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $OPAQUE_REQUEST_ID" \
  --data '{"external_id":"customer-42","profile":{"locale":"en"}}'

​

Request conventions

• Send and receive UTF-8 JSON with Content-Type: application/json.
• Keep raw external IDs, participant tokens, share tokens, and PII out of URL paths, query strings, logs, and analytics.
• Page limits are 1–100. Treat cursors as opaque and discard them when filters change.
• Capture the response request ID for support without recording the request body or credential.
• Honor Retry-After on 429 and use bounded exponential backoff for retryable transport and server failures.

​

Stable errors

{
  "detail": {
    "code": "IDEMPOTENCY_KEY_REUSED",
    "message": "This idempotency key was already used with a different request body.",
    "request_id": "req_opaque"
  }
}