Runtime HTTP reference

This is the script’s delivery protocol. Use MCP/the authenticated client for authoring; these endpoints are not a general workspace-management API. Preview access uses a separate scoped bearer, never an MCP key in merchant JavaScript. Base path: /personalization/runtime/{workspaceUuid} on the API service, not necessarily the script CDN origin.

Endpoint map

Method / suffix	Request	Success
`GET /site`	`features`, `path` query; live Origin or preview bearer	`{ site, origin, name, mode, settings }`
`POST /installed`	`{ path, revision: string \| null }` plus exact live Origin	`{ accepted: true }`
`POST /decide`	Decision request below	Receipt with revision, page, decision and summary
`POST /collect`	Validated analytics batch	204
`POST /enrich`	`{ visitor, path, referrer?, internal? }`	`{ value, expiresAt? }`; value may be null
`POST /events`	Legacy event contract	`{ accepted: true }`
`GET /install.js`	Legacy per-workspace installer	Shared JavaScript

GET /dynamite.js is also served at the application root. /personalization/runtime/snapshot.js supports preview rendering. The CDN is a separate static bundle surface.

Configuration

Current installed clients request features=editorial-v3 and the encoded pathname. Feature negotiation changes editorial target/catalog delivery for older clients. Live responses cache for 20 seconds and vary by origin; private preview responses remain no-store. site is the released logical VisitorSite, with resolved component values. settings exposes experiment holdout/salt/pause, runtime goals and an enrichment-enabled flag; secret connector headers are not sent.

Standard decision body

{
  siteId: string;             // logical site ID, not the workspace UUID
  revision: string;
  pageId: string;
  profile: unknown;           // normalized by the server
  features?: 'editorial-v2' | 'editorial-v3';
  previewDays?: number;       // 0 live; simulated offsets require preview
  sessionId?: string;
  controls?: Record<string, { value: string; visitorOwned: boolean }>;
  enrichment?: string;        // signed value from /enrich
  internal?: boolean;
}

Specialized NBA/horror preview fields also exist in the source schema; they are not a generic production quiz API. See decisionInput for the complete current contract.

Receipt

{
  revision: string;
  pageId: string;
  decision: {
    id: string;
    manifestId: string;
    revision: string;
    policyId: string;
    evaluationId: string;
    arm: 'control' | 'personalized';
    selections: Record<string, {
      variant: string;
      reason: string;
      confidence: number | null;
      probabilities: Record<string, number>;
    }>;
    // Provider identity, model, call count, timestamps and timings also included.
  };
  summary: VisitorSummary;
  // Optional identity/editorial selections/catalog for compatible paths.
}

The adaptive receipt calls its holdout arm control; public browser experiment reporting uses holdout (and off when paused). Do not conflate these enum names. The browser checks the receipt against current page/revision and eligibility before applying.

Measurement batches

The browser owns event batching and session semantics. Reuse its tracker instead of inventing /collect payloads. The exact schema is in analytics/collect.server.ts. The service validates references, deduplicates and recomputes group assignment; a 204 acknowledges accepted processing, not proof that every claimed event was valid or durably flushed.

Errors and limits

Status	Typical meaning
400	Malformed JSON/schema, invalid profile/page or unsupported input
401	Invalid preview authentication
403	Wrong origin, unavailable live release/access, forbidden simulated context
404	Missing resource or no enabled enrichment source on that path
409	Configuration/revision conflict
429	Rate limit
503	Unavailable provider/service or unclassified internal failure

Runtime bodies are limited to 32 KiB. Current fixed-window limits include 900 requests per client/site per minute, 240 live decisions and 30 enrichment requests, plus address/workspace ceilings. Do not design a client to continuously poll for personalization. Public runtime posts accept JSON carried as text/plain or application/json. The installed client uses safelisted text bodies to avoid unnecessary preflights. Normal API failures keep originals; authentication and authoring clients should inspect errors and not silently report success. Source: routes, context, browser requests.

Contracts & tools

Inside Dynamite

Source & maintenance

Runtime HTTP reference

Endpoint map

Configuration

Standard decision body

Receipt

Measurement batches

Errors and limits

​Endpoint map

​Configuration

​Standard decision body

​Receipt

​Measurement batches

​Errors and limits

Endpoint map

Configuration

Standard decision body

Receipt

Measurement batches

Errors and limits