Edge API

Overview

The edge is the data plane: SDKs download snapshots, send events, and open realtime streams here. The TypeScript SDK calls these routes for you; use this page when you write your own client or debug traffic.

	Value
Base URL	`https://edge.useshipd.com` (local: `http://localhost:8787`)
WebSocket gateway	`wss://ws.useshipd.com` (path `/sdk/v1/stream`)
Authentication	`Authorization: Bearer shipd_sdk_…`
Rate limit	6,000 requests per minute per SDK key at the edge rate limiter (`429` with `Retry-After` when exceeded). A separate per-minute admission limit also applies, and your plan’s monthly allowance is in Usage and limits.

Authentication

Only SDK keys work on the edge. Each key is bound to one organization, project, and environment, and carries explicit data-plane scopes:

Scope	Routes	Key types
`snapshot:read`	`GET /sdk/v1/snapshot`	Server and client
`events:write`	`POST /sdk/v1/events`	Server and client
`stream:connect`	`POST /sdk/v1/stream-ticket`, `WS /sdk/v1/stream`	Server and client
`identity:read`	`GET /sdk/v1/identity`	Server only

A missing scope returns 403. A management API key, service account token, or any other credential returns the same generic 401 as an invalid SDK key. Authenticated traffic is limited per key by Cloudflare’s distributed rate limiter. The edge usage rollup sends only key ids (never secrets) to the control plane and updates each key’s lastUsedAt at most once per minute. See SDK keys, management API keys, and service account tokens.

GET /sdk/v1/snapshot

Returns the current snapshot for the key’s environment.

GET /sdk/v1/snapshot HTTP/1.1
Host: edge.useshipd.com
Authorization: Bearer shipd_sdk_server_…
If-None-Match: "snapshot-42"

string

required

Bearer followed by an SDK key with snapshot:read.

string

The ETag from the previous response. The edge returns 304 if the snapshot has not changed.

Responses

Status	Meaning
`200`	Body is a `FlagSnapshot`. Headers: `ETag: "snapshot-<version>"`, `Cache-Control: no-cache`.
`304`	Unchanged since `If-None-Match`.

Client SDK keys also receive X-Shipd-Auto-Traits on 200 and 304 when geolocation is available: country, region, city, and timezone from Cloudflare geolocation. The raw IP address is never included.

Example 200 body

{
  "schemaVersion": 1,
  "environmentKey": "production",
  "version": 42,
  "flags": { "new-checkout": { "key": "new-checkout", "type": "boolean", "enabled": true } }
}

The example is abbreviated. See Snapshots for the full envelope. Errors

Status	Cause
`401`	Invalid, revoked, or non-SDK credential
`403`	Key lacks `snapshot:read`
`404`	No snapshot has been published for this environment yet
`429`	Rate limit exceeded; retry after `Retry-After`

Related: Snapshots · Local evaluation

POST /sdk/v1/events

Accepts a batch of evaluation, diagnostic, and identify events.

POST /sdk/v1/events HTTP/1.1
Host: edge.useshipd.com
Authorization: Bearer shipd_sdk_server_…
Content-Type: application/json

string

required

Must be application/json.

string

ISO-8601 time the batch was sent. Optional. When present it must be an ISO-8601 timestamp. The TypeScript SDK always sends it.

Event[]

required

1–100 events. The whole body must be 256 KiB or smaller.

Every event has a type and an ISO ts. Evaluation, error, unregistered-flag, identify, and timing events also carry snapshotVersion, which may be null before a snapshot is available.

`type`	Extra fields
`evaluation`	`key`, `reason`, `value`, `userId`, `snapshotVersion`
`unregistered_flag`	`key`, `snapshotVersion`
`error`	`message`, `snapshotVersion`
`version_skew`	`previousVersion`, `currentVersion`
`identify`	`userId`, `traits`, `snapshotVersion`
`timing`	`stage`, `durationMs`, `snapshotVersion`

Example request body

{
  "sentAt": "2026-08-18T16:04:00.000Z",
  "events": [
    {
      "type": "evaluation",
      "ts": "2026-08-18T16:03:59.900Z",
      "key": "new-checkout",
      "reason": "fallthrough",
      "value": true,
      "userId": "usr_8f2k19",
      "snapshotVersion": 42
    },
    { "type": "unregistered_flag", "ts": "2026-08-18T16:03:59.910Z", "key": "typo-flag", "snapshotVersion": 42 },
    { "type": "error", "ts": "2026-08-18T16:03:59.920Z", "message": "snapshot fetch failed: HTTP 503", "snapshotVersion": 42 },
    { "type": "version_skew", "ts": "2026-08-18T16:03:59.930Z", "previousVersion": 41, "currentVersion": 42 },
    { "type": "identify", "ts": "2026-08-18T16:03:59.940Z", "userId": "usr_8f2k19", "traits": { "plan": "pro" }, "snapshotVersion": 42 }
  ]
}

Responses

Status	Meaning
`202`	Accepted. The edge validates every event before accepting the batch. `identify` events are durably enqueued before the response.

Evaluation analytics are stored only for production environments when analytics is configured; non-production evaluation events are never stored. Client SDK identify events also pick up country, region, city, and timezone from the request; explicit traits win. Server SDK keys are not enriched. Disable events in the SDK with events: false. Errors

Status	Code	Cause
`401`		Invalid, revoked, or non-SDK credential
`403`		Key lacks `events:write`
`413`	`payload_too_large`	Body larger than 256 KiB
`422`	`validation_error`	Wrong `Content-Type`, or a malformed batch or event
`429`	`rate_limited`	Rate limit exceeded; retry after `Retry-After`
`500`	`internal`	The queue failed. The error is retryable; the edge never acknowledges data it did not queue.

Related: Identify users · Usage and limits

POST /sdk/v1/stream-ticket

Mints a short-lived HMAC ticket for authenticating the WebSocket stream. Browsers cannot set Authorization on a WebSocket, so the SDK mints a ticket with the Bearer header first.

POST /sdk/v1/stream-ticket HTTP/1.1
Host: edge.useshipd.com
Authorization: Bearer shipd_sdk_client_…

string

required

Bearer followed by the same SDK key you use for snapshot fetches. Requires stream:connect.

Responses

Status	Meaning
`200`	Body: `{ "ticket", "expiresAt", "ttlSeconds" }`. Header: `Cache-Control: no-store`. The default TTL is five minutes.

Example 200 body

{
  "ticket": "…",
  "expiresAt": "2026-08-18T16:09:00.000Z",
  "ttlSeconds": 300
}

Errors

Status	Cause
`401`	Invalid, revoked, or non-SDK credential
`403`	Key lacks `stream:connect`
`429`	Rate limit exceeded; retry after `Retry-After`

Related: WS /sdk/v1/stream (below)

GET /sdk/v1/identity

Returns the stored trait overlay for an identified user to server SDK keys with identity:read. Client SDK keys receive 403. Current server SDKs do not fetch the overlay automatically; pass traits in the evaluation context. Browser clients cannot load it with their client SDK key.

GET /sdk/v1/identity?userId=usr_8f2k19 HTTP/1.1
Host: edge.useshipd.com
Authorization: Bearer shipd_sdk_server_…

string

required

The user id passed to identify().

string

required

Bearer followed by a server SDK key with identity:read.

Responses

Status	Meaning
`200`	Body: `{ "attributes", "name", "updatedAt" }`. Header: `Cache-Control: no-store`.

Example 200 body

{
  "attributes": { "plan": "pro" },
  "name": "Ada Lovelace",
  "updatedAt": "2026-08-18T16:03:59.940Z"
}

Errors

Status	Cause
`401`	Invalid, revoked, or non-SDK credential
`403`	Client SDK key, or key lacks `identity:read`
`404`	No overlay stored for this user. The SDK keeps its local context.
`422`	`userId` is missing

Related: Identify users · SDK

WS /sdk/v1/stream

Pushes snapshot invalidations for one environment. The channel never carries snapshots or analytics payloads; after an invalidation, you fetch the snapshot over HTTP.

wss://ws.useshipd.com/sdk/v1/stream?ticket=…

string

required

A ticket from POST /sdk/v1/stream-ticket.

Mint a ticket

Call POST /sdk/v1/stream-ticket with your SDK key. The TypeScript SDK does this before each connect.

Connect

Open wss://ws.useshipd.com/sdk/v1/stream?ticket=…. The ticket must be valid, unexpired, and bound to the environment of an active SDK key.

Receive connected

Wait for connected with connectionId, environmentId, and snapshotVersion. The socket is already bound to that environment’s fanout.

Recover gaps (optional)

Send subscribe with the same environmentId and a stale lastKnownVersion only when you need gap recovery, for example when configuration changed between connected and client registration. Subscribing to another environment is rejected.

Handle updates

On snapshot.updated or snapshot.resync, fetch the snapshot with GET /sdk/v1/snapshot.

Message	Direction	Fields
`connected`	Server → client	`connectionId`, `environmentId`, `snapshotVersion`
`subscribe`	Client → server	`environmentId`, `lastKnownVersion`
`snapshot.updated`	Server → client	`environmentId`, `version`
`snapshot.resync`	Server → client	`reason` (`version_gap`), sent when a `subscribe` reveals more than one missed version
`ping` / `pong`	Client → server / server → client	Application keepalive
`error`	Server → client	`code`, `message`

Application ping/pong plus a transport heartbeat keep the socket alive. Errors. Client-facing authentication errors are generic. Revoked keys are disconnected. Revocation. Revoked keys stop authorizing new HTTP calls as revocation propagates. Existing sockets revalidate at least every 60 seconds. The end-to-end revocation target is 120 seconds. Deprecated: ?sdkKey= authentication. Passing the SDK key in the URL is deprecated because URLs can end up in proxy and access logs. Migrate to POST /sdk/v1/stream-ticket and ?ticket=. Legacy authentication is rejected by default. Compatibility support will not be removed before March 1, 2027; migrate clients to tickets before connecting. Related: Architecture · What happens if shipd is down?

Compatibility

The SDK supports snapshot schema 1 and stream protocol 1. It rejects newer schemas and keeps the last good snapshot. Related: SDK · Node.js and server runtimes · Browser · Errors

HTTP APIs

Operations APIs

Enterprise APIs

Errors

Overview

Authentication

GET /sdk/v1/snapshot

POST /sdk/v1/events

POST /sdk/v1/stream-ticket

GET /sdk/v1/identity

WS /sdk/v1/stream

Compatibility

​Overview

​Authentication

​GET /sdk/v1/snapshot

​POST /sdk/v1/events

​POST /sdk/v1/stream-ticket

​GET /sdk/v1/identity

​WS /sdk/v1/stream

​Compatibility

Overview

Authentication

GET /sdk/v1/snapshot

POST /sdk/v1/events

POST /sdk/v1/stream-ticket

GET /sdk/v1/identity

WS /sdk/v1/stream

Compatibility