Synapse OS
[ Sign In / Go Premium ]
API Reference

Synapse OS proxy โ€” in 60 seconds

Point your OpenAI or Anthropic SDK at the Synapse endpoint. We prune redundant context, dedupe shared blocks, forward the optimized payload, and stream the response back with token-savings metrics attached as response headers.

Endpoint
POSThttps://synapseui.dev/api/proxy/intercept

Send OpenAI- or Anthropic-shaped payloads. Set forward: true and include x-provider-api-key to actually forward upstream and stream the response back. Omit them for a dry-run that only returns optimization metrics.

Quickstart

Two required headers: your Synapse session bearer token (from your signed-in Supabase session) and x-provider-api-key for the upstream provider. We forward the key once and never persist it.

curl
proxy.sh
bash
curl -N -X POST https://synapseui.dev/api/proxy/intercept \
  -H "content-type: application/json" \
  -H "authorization: Bearer $SYNAPSE_SESSION_JWT" \
  -H "x-provider-api-key: $OPENAI_API_KEY" \
  -D - \
  -d '{
    "workspaceId": "00000000-0000-0000-0000-000000000000",
    "provider": "openai",
    "forward": true,
    "payload": {
      "model": "gpt-4o-mini",
      "stream": true,
      "messages": [
        { "role": "system", "content": "You are a concise assistant." },
        { "role": "user", "content": "Summarize the Synapse OS proxy in one line." }
      ]
    }
  }'
Node / TypeScript
proxy.ts
typescript
// Node 18+ / Bun / Deno โ€” forwards to OpenAI through the Synapse proxy
// and reads the X-Synapse-* optimization metrics off the response.
const res = await fetch("https://synapseui.dev/api/proxy/intercept", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    // Bearer = the caller's Supabase session JWT from your app.
    authorization: `Bearer ${process.env.SYNAPSE_SESSION_JWT}`,
    // The upstream provider key โ€” never stored server-side, forwarded once.
    "x-provider-api-key": process.env.OPENAI_API_KEY!,
  },
  body: JSON.stringify({
    workspaceId: "00000000-0000-0000-0000-000000000000",
    provider: "openai",
    forward: true,
    payload: {
      model: "gpt-4o-mini",
      stream: true,
      messages: [
        { role: "system", content: "You are a concise assistant." },
        { role: "user", content: "Summarize Synapse OS in one line." },
      ],
    },
  }),
});

// Read Synapse optimization telemetry from the response headers.
const metrics = {
  optimization: res.headers.get("X-Synapse-Optimization"),
  tokensSaved: Number(res.headers.get("X-Synapse-Tokens-Saved") ?? 0),
  reductionRatio: Number(res.headers.get("X-Synapse-Reduction-Ratio") ?? 0),
  messagesRemoved: Number(res.headers.get("X-Synapse-Messages-Removed") ?? 0),
  sharedBlocksStripped: Number(res.headers.get("X-Synapse-Shared-Blocks-Stripped") ?? 0),
  upstream: res.headers.get("X-Synapse-Upstream"),
};
console.log("[synapse]", metrics);

// Stream the upstream response body straight through to your client.
if (!res.body) throw new Error("no upstream body");
const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

Request body

FieldTypeDescription
workspaceIduuidThe workspace the caller belongs to. Tier + entitlements are resolved from the workspace owner's profile.
payloadobjectThe upstream vendor payload, unchanged (OpenAI chat.completions or Anthropic messages shape).
provider"openai" | "anthropic"Which upstream to forward to when forward: true.
forwardbooleanIf true, forwards the optimized payload upstream and streams the response body back. Otherwise returns JSON metrics only.

Response headers

Every response โ€” dry-run or streamed upstream โ€” carries X-Synapse-* headers so you can attribute savings per call. All headers are exposed via CORS for browser clients.

HeaderTypeMeaning
X-Synapse-Optimizationeligible | skipped | unauthorizedWhether the request went through the optimization layer. `skipped` means the workspace owner needs to upgrade to Team.
X-Synapse-Original-TokensintegerEstimated token count of the payload before pruning.
X-Synapse-Estimated-TokensintegerEstimated token count of the optimized payload that was forwarded upstream.
X-Synapse-Tokens-SavedintegerTotal tokens removed by pruning + shared-block deduplication.
X-Synapse-Reduction-Ratio0.0000 โ€“ 1.0000Fraction of the original token budget reclaimed.
X-Synapse-Messages-RemovedintegerHow many low-signal messages the pruner dropped.
X-Synapse-Shared-Blocks-StrippedintegerRepeated system / context blocks lifted into shared memory.
X-Synapse-Upstreamopenai | anthropicWhich provider the optimized payload was forwarded to.
X-Synapse-Upstream-Statusinteger | errorHTTP status returned by the upstream provider (or `error` if the upstream call failed).

Tiers

Free
Metrics only

Dry-run profiling of every request. You get token estimates and an X-Synapse-Upgrade: team hint, but no upstream forwarding.

Team
Live optimization

Full pruning, shared-context deduplication, upstream forwarding, and response streaming โ€” with savings reported per call.

Ready to plug it in?

Grab your workspace ID from the workspace screen, then send your first request.