Edge API

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.

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 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).

{
  "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

Authenticate (SDK key)
Server → connected
Client → subscribe with environmentId + lastKnownVersion
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 · SDK reference.

Getting started

Guides

How-to

Concepts

Reference

Overview

GET /sdk/v1/snapshot

POST /sdk/v1/events

GET /sdk/v1/identity

WS /sdk/v1/stream

Compatibility

​Overview

​GET /sdk/v1/snapshot

​POST /sdk/v1/events

​GET /sdk/v1/identity

​WS /sdk/v1/stream

​Compatibility

Overview

GET /sdk/v1/snapshot

POST /sdk/v1/events

GET /sdk/v1/identity

WS /sdk/v1/stream

Compatibility