> ## Documentation Index
> Fetch the complete documentation index at: https://synapse-docs.apart.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Use the tenant-bound, versioned Synapse API directly from any language.

# Synapse API

Use the same tenant-bound, versioned contract from any language. The canonical
OpenAPI 3.1 document powers generated endpoint pages and both SDK type systems.

<Info>
  Examples use `$SYNAPSE_API_URL`. Use the base URL supplied for your
  provisioned Synapse environment rather than copying a placeholder or stale
  deployment URL.
</Info>

## First request

```bash theme={null}
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"}}'
```

<CardGroup cols={2}>
  <Card title="Versioned routes" icon="code-branch">
    Product contracts live under `/v1`. Authentication lifecycle operations
    live under `/auth`, and `/health` is reserved for readiness checks.
  </Card>

  <Card title="Tenant-bound auth" icon="lock">
    The credential and exact organization, app, and environment path must
    agree. Cross-scope resources are never discoverable.
  </Card>

  <Card title="Idempotent writes" icon="rotate">
    Every durable mutation requires `Idempotency-Key`. Exact replays return
    the original response; conflicts return `409`.
  </Card>

  <Card title="Cursor pages" icon="list">
    Collection responses contain `items` and an opaque `next_cursor`, bound
    to the resource and filters.
  </Card>
</CardGroup>

## 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

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

Validation failures use `422`; authentication failures use `401`; valid
credentials without scope use `403`; missing tenant resources use
non-enumerating `404`; state or replay conflicts use `409`. Validation
details from `/v1` use the structured object above. Authentication lifecycle
operations keep their documented response shapes.

Use the [endpoint reference](/api/reference), review
[authentication and scope](/api/authentication), or
[download the canonical specification](/openapi.json).