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

# Edge API

> Data-plane HTTP and WebSocket routes the SDK uses.

## Overview

Base URL: `https://edge.useshipd.com` (local: `http://localhost:8787`). Authenticate with `Authorization: Bearer shipd_sdk_…`.

WebSocket gateway: `https://ws.useshipd.com` (path `/sdk/v1/stream`).

## GET /sdk/v1/snapshot

Current environment snapshot.

```http theme={null}
GET /sdk/v1/snapshot HTTP/1.1
Host: edge.useshipd.com
Authorization: Bearer shipd_sdk_server_…
If-None-Match: "snapshot-42"
```

| Status | Meaning                                                                            |
| ------ | ---------------------------------------------------------------------------------- |
| 200    | Body is a `FlagSnapshot`. `ETag: "snapshot-<version>"`. `Cache-Control: no-cache`. |
| 304    | Unchanged                                                                          |
| 401    | Bad or revoked key                                                                 |

See [Snapshots](/concepts/snapshots) for the JSON envelope.

## POST /sdk/v1/events

Batched diagnostics. **202 Accepted**. `identify` enqueues to Postgres. Production `evaluation` events go to Tinybird when configured (never staging).

```json theme={null}
{
  "sentAt": "2026-08-18T16:04:00.000Z",
  "events": [
    {
      "type": "evaluation",
      "key": "new-checkout",
      "reason": "fallthrough",
      "value": true,
      "userId": "usr_8f2k19"
    },
    { "type": "unregistered_flag", "key": "typo-flag" },
    { "type": "error", "message": "snapshot fetch failed: HTTP 503" },
    { "type": "version_skew", "previousVersion": 41, "currentVersion": 42 },
    { "type": "identify", "userId": "usr_8f2k19", "traits": { "plan": "pro" } }
  ]
}
```

Disable from the SDK with `events: false`.

## GET /sdk/v1/identity

KV trait overlay for the identified user. The SDK merges this under session traits after `identify()` unless `remoteTraits: false`.

## WS /sdk/v1/stream

1. Authenticate (SDK key)
2. Server → `connected`
3. Client → `subscribe` with `environmentId` + `lastKnownVersion`
4. Server → `snapshot.updated` / `snapshot.resync` when KV `current` advances

Application ping/pong plus transport heartbeat. Revoked keys disconnect. This channel never carries full snapshots or analytics payloads.

## Compatibility

SDK supports snapshot schema `1` and stream protocol `1`. Newer schemas are rejected; last good snapshot is kept.

Guides: [Evaluate flags](/guides/evaluate-flags) · [SDK reference](/reference/sdk).