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

> ## Agent Instructions
> Read /start/capabilities before choosing an integration. Use the deployed server’s tools/list for current tool inputs.

# Runtime HTTP reference

> Public delivery endpoints, request identities, response shapes, caching and error handling used by the installed script.

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

```ts theme={null}
{
  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](https://github.com/ion-design/dynamite/blob/main/packages/personalization-server/src/decision.server.ts) for the complete current contract.

## Receipt

```ts theme={null}
{
  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](https://github.com/ion-design/dynamite/blob/main/packages/personalization-server/src/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](https://github.com/ion-design/dynamite/blob/main/packages/personalization-server/src/runtime.ts), [context](https://github.com/ion-design/dynamite/blob/main/packages/personalization-server/src/runtime-context.server.ts), [browser requests](https://github.com/ion-design/dynamite/blob/main/packages/adaptive/src/browser/runtime-decisions.ts).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.