REST endpoints
The plugin's HTTP endpoints under Payload's API route, their permissions and request rules.
All routes are relative to Payload's routes.api (normally /api). The admin uses them; you can call them from your own tools with an authenticated Payload session.
Results
| Endpoint | Permission | Response |
|---|---|---|
GET /xp/experiments/:id/results?phase=1&series=1 | readResults | Round summaries, the selected round's newest snapshot (null before a run), an optional decisionSnapshot, and the time series when requested. Without phase, a decided test opens on its decision round. Includes the test's name, kind and status. |
GET /xp/experiments/summary?ids=… | readResults | A map of test ids to exposures, days and verdict summary. Encode each id, comma-join, at most 100 ids. Includes the next setup step for draft and stopped tests when the caller can manage. |
POST /xp/experiments/:id/recompute | manage | Runs results for one test; returns { snapshotId }. |
Actions
All need access.manage and are POST /xp/experiments/:id/<action>:
start, allocate, add-metric, stop, decide, release-holdout, release-pages, make-content, content-report/dismiss, content-report/restore, archive.
Request and response types are exported from the package root: AllocateBody, AddMetricBody, AddMetricResult, DecideBody, ArchiveBody, MakeContentResult, DismissContentEntryBody, RestoreContentEntryBody, TransitionSuccess and ErrorEnvelope.
Setup
| Endpoint | Permission | Purpose |
|---|---|---|
GET /xp/experiments/:id/preflight | manage | Setup checks, placements, preview links, traffic and duration estimate |
GET /xp/experiments/:id/preview-token | manage | A signed preview token for one group |
GET /xp/experiments/:id/click-keys | manage | Click-goal keys found in the test's content |
GET /xp/pages?path=… | manage | Page browsing and resolving a path to a page |
POST /xp/placements/status | manage | Test status for placements |
POST /xp/blocks/wrap | manage | Wrap a block in an Experiment block in the latest draft. Respects document locks; 16 KiB request cap |
Browser events
POST /xp/events needs a valid signed visitor cookie, not a Payload session. See Security for its limits.
Manifest
GET /xp/manifest needs the x-xp-manifest-key header. It is used by createHttpManifestLoader; see Runtimes.
Errors and refusals
400is reserved for requests that cannot be parsed.- Well-formed requests that cannot be accepted return
422or409with a refusalcode, for examplelayer-full,page-busy,interacting-tests,placement-unpublished,goal-in-some-versions,invalid-status,stale-editorconfirmation-required. Codes are exported as theRefusalCodetype; readiness checks asReadinessCode. - Saves through the Payload REST API on the tests collection keep their refusal
codetoo.
To avoid overwriting someone else's changes, send the test's last updatedAt in the x-xp-if-updated-at header (exported as XP_IF_UPDATED_AT_HEADER from /admin/client). An outdated save is refused with stale-edit.