Generated OpenAPI reference

Get deterministic server-side assignments

/assign

Parameters

• shop_id in query required
• user_id in query required
• url in query - Browser URL for storefront URL targeting. App clients may send an app screen URL (app://<bundle id>/<screen>); app callers (publishable-key lane or any app:// URL) are never assigned experiments with storefront URL targeting.
• environment in query
• experiments in query

Responses

• 200 Assignments and program cohort returned
• 400 Invalid request, including a customer identifier supplied in the query string instead of a POST body.
• 401
• 429
• 503

Get deterministic assignments with commerce proof inputs

/assign

Request body

{
  shop_id: string
  user_id?: string
  logged_in_customer_id?: string
  customer_id?: string
  decision_use?: "aggregate" | "individual"
  url?: string (uri)
  environment?: string
  experiments?: string[]
  cart_token?: string
  persist_function_handoff?: boolean
  exclusion_group_selections?: object[]
}

Responses

• 200 Assignments, program cohort, and commerce authorization returned
• 400
• 401
• 403 A logged-in customer assignment was requested for an individual-level decision.
• 429
• 503

Verify a signed cross-domain bucketing handover token

/handover/verify

Worker runtime endpoint. Verifies the token signature, expiry, and shop binding without requiring ingest credentials.

Parameters

• X-Drip-Shop in header required

Request body

{
  verifyToken: string
}

Responses

• 200 Verified handover payload
• 400 Missing or invalid shop identifier
• 401 Unsigned, forged, expired, or cross-shop handover token
• 500 Handover verification is unavailable

Inspect experiment conflicts

/experiments/conflicts

Request body

{
  selectors: string[]
  exclude_experiment_id?: string (uuid)
}

Responses

• 200 Conflict analysis
• 400
• 401
• 403
• 404
• 429
• 503

Update experiment QA

/experiments/{id}/qa

Approves QA and marks ready to launch, without launching or changing weights. Zero-traffic acknowledgement requires an Admin or Internal person principal; shop API keys cannot acknowledge.

Parameters

• scope in query - Set to store to act only on this store; omitted acts on every store when this is a brand-test parent.

Request body

{
  acknowledge_degenerate_weights?: boolean
  acknowledge_degenerate_weights_hash?: string
  scope?: "store"
}

Responses

• 200 QA updated: the raw experiment row, plus program on a brand-test parent (#9255)
• 400
• 401
• 403
• 404
• 409 QA conflict, including a missing, stale, or unauthorized zero-traffic acknowledgement
• 429
• 503

Reset experiment QA

/experiments/{id}/qa

Responses

• 200 QA reset
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Read saved commerce QA probe evidence

/experiments/{id}/qa/commerce-probes

Reads saved price, shipping, and post-purchase probe evidence without calling Shopify. Requires experiments:read. Current shipping evidence also returns its saved result, preserving summary, details and optional action: { label: string, href: string }. Results from earlier draft versions are omitted.

Responses

• 200 Saved commerce probe evidence
• 401
• 403
• 404
• 429
• 503

Run commerce QA probes

/experiments/{id}/qa/commerce-probes

The shipping probe checks each enforced arm against the store rate in every delivery zone and also runs for enforced arms without a threshold. Runs the requested saved-draft commerce probes. Requires experiments:write. When shipping evidence cannot be read, kinds.shipping.result includes a plain-language summary and the same sentence first in details. A missing Shopify permission may also include optional action: { label: "Approve in Shopify", href: string }, linking to Pricing & Offers authorization.

Request body

{
  kinds?: ("price" | "shipping" | "post_purchase")[]
}

Responses

• 200 Commerce probe results and saved evidence
• 400
• 401
• 403
• 404
• 409 Experiment must be draft or paused, or installation unavailable
• 422 Probe not applicable or invalid commerce configuration
• 429
• 502 Shopify upstream request failed
• 503

Read QA-tagged events

/experiments/{id}/qa/events

Returns goal and custom events for a QA session. Requires experiments:read.

Responses

• 200 QA event groups
• 400
• 401
• 403
• 404
• 429
• 503 QA event readback unavailable

Read QA run

/experiments/{id}/qa/run

Creates a run only when none exists. Existing runs are computed in memory without writes: updatedAt is the stored mutation time; computedAt is the ISO timestamp of this read.

Responses

• 200 QA run, including QA destination URLs for goals on pages outside experiment targeting (goal-page entries in urls, and goalPageDestinations evidence on the qa_url_coverage checklist item)
• 400
• 401
• 403
• 404
• 429
• 503

Update QA run

/experiments/{id}/qa/run

Request body

{
  runId: string
  itemId?: string
  status?: "pending" | "pass" | "warning" | "fail" | "accepted" | "skipped"
  notes?: string
  evidence?: object
  runNotes?: string
  acceptanceCriteriaSummary?: string | null
}

Responses

• 200 QA run updated
• 400
• 401
• 403
• 404
• 429
• 503

Add a custom QA checklist item

/experiments/{id}/qa/run

Request body

{
  runId: string
  title: string
  description?: string
  category?: string
  required?: boolean
}

Responses

• 201 QA checklist item created
• 400
• 401
• 403
• 404
• 429
• 503

Delete custom QA checklist item

/experiments/{id}/qa/run

Parameters

• runId in query
• itemId in query

Request body

{
  runId?: string
  itemId?: string
}

Responses

• 200 QA run deleted
• 400
• 401
• 403
• 404
• 429
• 503

Retired experiment launch endpoint

/experiments/{id}/start

This endpoint is gone. Launch traffic through the dashboard approval workflow.

Responses

• 410 Launch is dashboard-only

Create harness session

/harness/sessions

Request body

{
  experimentId?: string
  variationId?: string
  experimentSlug: string
  experimentName: string
  variationSlug: string
  variationName: string
  targetUrl: string (uri)
  resetJs?: string | null
  antiFlickerSelectors?: string[]
  ttlSeconds?: integer
}

Responses

• 201 Harness session created
• 400 Invalid request or artifact review blocked the session; nothing was created or changed
• 401
• 403
• 404
• 409 Artifact conflict during the save, or experiment is not in draft status
• 429
• 503

Create harness session version

/harness/sessions/{id}/versions

Responses

• 201 Version created
• 400
• 401
• 403
• 404
• 429
• 503

Read platform operator settings

/admin/settings

admin:read plus platform health-section access. Missing undo policy defaults to 7; malformed or unreadable policy returns 503 policy_unavailable.

Responses

• 200 Typed settings and policy version
• 503 policy_unavailable

Write audited platform operator settings

/admin/settings

admin:write plus platform health-section access. Numeric policy writes require expected_version and reason. All supplied settings and audits commit atomically; boolean-only requests keep their existing contract.

Request body

{
  guardian_enabled?: boolean
  srm_check_enabled?: boolean
  experiment_undo_completion_window_days?: integer
  free_plan_days?: any
  expected_version?: string
  reason?: string
}

Responses

• 200 Updated typed settings
• 400 Invalid allowlisted setting, version or reason
• 403 Insufficient admin or section access
• 409 policy_changed; no settings written
• 503 policy_unavailable

List backlog

/backlog

Parameters

• limit in query
• cursor in query
• include_archived in query - Include archived backlog items when true.

Responses

• 200 Paginated backlog
• 400
• 401
• 403
• 429
• 503

Create a backlog item

/backlog

Creates a backlog item. Score and score-provenance fields require an active apex-editor or apex-platform-admin grant on a user API key; shop keys and other users receive 403.

Request body

{ $ref: "BacklogCreate" }

Responses

• 201 Created
• 400
• 401
• 403
• 409
• 422
• 429
• 503

List the shop's idea fields

/backlog/fields

The field definitions whose values ride on each idea's custom_fields.

Parameters

• include_archived in query - Include archived fields when true.

Responses

• 200 Field definitions, in sheet order
• 401
• 403
• 429
• 503

Add an idea field

/backlog/fields

Request body

{ $ref: "BacklogFieldCreate" }

Responses

• 201 Created
• 400
• 401
• 403
• 409
• 429
• 503

Reorder the idea fields

/backlog/fields

Places the live fields. Every named field must be live, and the resulting positions must be unique across the whole live sheet, so send the sheet rather than one row when two fields swap places. The body is the bare array or the same array under an order key.

Request body

any

Responses

• 200 Field definitions, in the new order
• 400
• 401
• 403
• 404
• 429
• 503

Update an idea field

/backlog/fields/{id}

Request body

{ $ref: "BacklogFieldUpdate" }

Responses

• 200 Updated
• 400
• 401
• 403
• 404
• 429
• 503

Archive an idea field

/backlog/fields/{id}

Archiving keeps the values already stored on ideas. The field disappears from reads and rejects new writes.

Responses

• 200 Archived
• 401
• 403
• 404
• 429
• 503

Get a backlogitem

/backlog/{id}

Responses

• 200 Resource
• 401
• 403
• 404
• 429
• 503

Update a backlogitem

/backlog/{id}

Updates a backlog item. Score and score-provenance fields, including research_hub_round_trip, require an active apex-editor or apex-platform-admin grant on a user API key; shop keys and other users receive 403. Ordinary metadata replacement remains available when neither stored nor incoming metadata contains protected score or prediction provenance. Omit metadata for ordinary edits on scored items. Supplying protected metadata, including unchanged values, or removing stored provenance returns 403. A concurrent metadata change returns 409 with error.code backlog_item_cas_miss, even when expected_version is omitted. Reload the item and retry.

Request body

{ $ref: "BacklogUpdate" }

Responses

• 200 Updated
• 400
• 401
• 403
• 404
• 409 The supplied version is stale or metadata changed during a non-staff replacement. Reload the item and retry.
• 422
• 429
• 503

Archive a backlog item

/backlog/{id}

Archives the backlog item instead of destroying it.

Responses

• 200 Deleted
• 401
• 403
• 404
• 429
• 503

Get an idea's design board

/backlog/{id}/design

Mockups, links, inspiration, and internal build notes, plus every Research Hub mirror the item carries. The internal half (build notes, inspiration, and links whose switch is off) is redacted for a client viewer: a client shop role in the dashboard, and a user API key whose holder holds one. A secret API key is minted with apikeys:manage, which no client role holds, so it reads the whole board.

Responses

• 200 Design board
• 401
• 403
• 404
• 429
• 503

Update an idea's design board

/backlog/{id}/design

Replaces the keys it carries and leaves the rest alone. Arrays replace wholesale.

Request body

{ $ref: "BacklogItemDesignPatch" }

Responses

• 200 Updated design board
• 400
• 401
• 403
• 404
• 409 The idea changed while saving
• 429
• 503

Archive a backlog item and reject its roadmap decision

/backlog/{id}/archive

Request body

{
  feedback?: string | null
  reason?: string | null
}

Responses

• 200 Archived backlog item
• 401
• 403
• 404
• 429
• 503

Approve a backlog idea into a month

/backlog/{id}/approve

Schedules the idea and records who decided. On a shop where DRIP decides the backlog, a client principal is refused with 403.

Request body

{
  roadmap_month: string
  comment?: string | null
}

Responses

• 200 The idea's decision after approving
• 400
• 401
• 403
• 404
• 409
• 422
• 429
• 503

Reject a backlog idea with a reason

/backlog/{id}/reject

Records the rejection and its reason. The idea stays in the backlog, shown as rejected, rather than being archived.

Request body

{
  reason_category: "not_right_for_brand" | "already_tested" | "too_much_effort" | "other"
  reason: string
}

Responses

• 200 The idea's decision after rejecting
• 400
• 401
• 403
• 404
• 409
• 422
• 429
• 503

Restore an archived backlog item and reset its roadmap decision to proposed

/backlog/{id}/restore

Responses

• 200 Restored backlog item
• 401
• 403
• 404
• 429
• 503

List personalizations

/personalizations

Parameters

• limit in query
• cursor in query

Responses

• 200 Personalizations with cursor pagination
• 400
• 401
• 403
• 404
• 429
• 503

Create personalization

/personalizations

Request body

{ $ref: "PersonalizationInput" }

Responses

• 201 Created personalization
• 400
• 401
• 403
• 404
• 422 Checkout messages work only on A/B tests.
• 429
• 503

Get personalization

/personalizations/{id}

Responses

• 200 Personalization
• 401
• 403
• 404
• 429
• 503

Update personalization

/personalizations/{id}

Request body

{ $ref: "PersonalizationUpdateInput" }

Responses

• 200 Updated personalization
• 400
• 401
• 403
• 404
• 429
• 503

Activate personalization

/personalizations/{id}/activate

Responses

• 200 Updated personalization
• 401
• 403
• 404
• 429
• 503

Pause personalization

/personalizations/{id}/pause

Responses

• 200 Updated personalization
• 401
• 403
• 404
• 429
• 503

Archive personalization

/personalizations/{id}/archive

Responses

• 200 Updated personalization
• 401
• 403
• 404
• 429
• 503

List assets

/assets

Parameters

• folder in query - Filter to a Brand folder; Brand includes all its subfolders.
• include_archived in query - Include archived assets.
• limit in query
• cursor in query

Responses

• 200 Assets with cursor pagination
• 400
• 401
• 403
• 429
• 503

Upload assets

/assets

Responses

• 201 Uploaded assets
• 400
• 401
• 403
• 413 Too many files or a file exceeds the upload size limit.
• 429
• 503

Get asset

/assets/{id}

Parameters

• id in path required

Responses

• 200 Asset
• 401
• 403
• 404
• 429
• 503

Archive asset

/assets/{id}

Archives the asset without deleting its stored file; it can be restored.

Parameters

• id in path required

Responses

• 200 Deleted
• 401
• 403
• 404
• 429
• 503

Restore asset

/assets/{id}/restore

Parameters

• id in path required

Responses

• 200 Restored asset
• 401
• 403
• 404
• 429
• 503

Read cost settings

/cost-settings

Parameters

• include_retired in query

Responses

• 200 Cost settings
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Change cost settings

/cost-settings

Request body

{ $ref: "CostSettingsPatchInput" }

Responses

• 200 Updated cost settings
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Read data-deletion status

/data-deletion

Returns the most recent deletion request for this shop that matches the supplied identifier. Supply at least one non-empty identifier: request_id or visitor_id. A request with neither, or with only empty values, returns 400. Both may be supplied; request_id then takes precedence and visitor_id is ignored. No match returns 404.

Parameters

• request_id in query - Id of a deletion request, as returned by POST. Takes precedence over visitor_id when both are non-empty.
• visitor_id in query - Visitor id; selects the visitor's most recent deletion request. Used only when request_id is absent or empty.

Responses

• 200 Deletion status
• 400
• 401
• 403
• 404
• 429
• 503

Request data deletion

/data-deletion

Request body

{
  visitor_id: string
}

Responses

• 202 The request is recorded when accepted. Deletion usually finishes before the response. While recent event writes for the shop are still settling, it can stay queued for up to about an hour. Copies of erased data that arrive later are found and removed by follow-up checks. Deletion completes within the 30 days promised in the DPA.
• 400
• 401
• 403
• 404
• 429
• 503

Export personal data

/data-export

Returns the most recent export request for this shop that matches the supplied identifier. Supply at least one non-empty identifier: request_id or visitor_id. A request with neither, or with only empty values, returns 400. Both may be supplied; request_id then takes precedence and visitor_id is ignored. No match returns 404.

Parameters

• request_id in query - Id of a export request, as returned by POST. Takes precedence over visitor_id when both are non-empty.
• visitor_id in query - Visitor id; selects the visitor's most recent export request. Used only when request_id is absent or empty.

Responses

• 200 Data export
• 400
• 401
• 403
• 404
• 429
• 503

Request a personal data export

/data-export

Request body

{
  limit?: integer
  visitor_id: string
}

Responses

• 200 Completed data export
• 400
• 401
• 403
• 404
• 429
• 503

List exclusion groups

/exclusion-groups

Parameters

• limit in query
• cursor in query
• include_archived in query - Include archived exclusion groups.

Responses

• 200 exclusion groups list
• 400
• 401
• 403
• 404
• 429
• 503

Create exclusion groups

/exclusion-groups

Request body

{ $ref: "ExclusionGroupInput" }

Responses

• 201 exclusion groups created
• 400
• 401
• 403
• 404
• 409 Retained checkout history refuses membership writes with checkout_mode_retired.
• 422 Constraint codes: min_members, duplicate_member, invalid_share, totals_mismatch, invalid_experiment, archived_member, or membership_conflict.
• 429
• 503

Get exclusion group

/exclusion-groups/{id}

Parameters

• id in path required

Responses

• 200 exclusion group returned
• 400
• 401
• 403
• 404
• 429
• 503

Update exclusion group

/exclusion-groups/{id}

Parameters

• id in path required

Request body

{ $ref: "ExclusionGroupUpdateInput" }

Responses

• 200 exclusion group returned
• 400
• 401
• 403
• 404
• 409 Retained checkout history refuses membership writes with checkout_mode_retired.
• 422 Constraint codes: min_members, duplicate_member, invalid_share, totals_mismatch, invalid_experiment, archived_member, or membership_conflict.
• 429
• 503

Archive exclusion group

/exclusion-groups/{id}

Archives the group while preserving membership.

Parameters

• id in path required

Responses

• 200 exclusion group deleted
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Replace exclusion group members

/exclusion-groups/{id}/members

Parameters

• id in path required

Request body

{ $ref: "ExclusionGroupMembersInput" }

Responses

• 200 Exclusion group members replaced
• 400
• 401
• 403
• 404
• 409 Retained checkout history refuses membership writes with checkout_mode_retired.
• 422 Constraint codes: min_members, duplicate_member, invalid_share, totals_mismatch, invalid_experiment, archived_member, or membership_conflict.
• 429
• 503

Restore exclusion group

/exclusion-groups/{id}/restore

Parameters

• id in path required

Responses

• 200 Exclusion group restored
• 400
• 401
• 403
• 404
• 429
• 503

Explain experiment results

/experiments/{id}/results/explain

Diagnostic classifier, not the canonical results pipeline. Labels in precedence order: bot, qa_traffic, outside_window, duplicate, before_exposure, exposed_before_window_only, not_exposed, filtered_by_goal, counted. Residuals expose rule differences between the diagnostic and the results pipeline. Reads are bounded to the result window plus 30 prior days; timeouts never return partial results.

Parameters

• id in path required
• goal in query - Attached goal ID or event key; defaults to primary.
• currency in query
• order in query - Restrict candidate rows to this order and exposures to its visitors; include its label trail across known arms. Reported values and residuals are omitted (null) in order mode.

Responses

• 200 Diagnostic explanation
• 400 Unknown goal or invalid query
• 401
• 403
• 404
• 409 No result window
• 422 diagnostic_row_limit: more than 100000 conversion candidates; error.details includes observed row count and a hint to narrow by --order.
• 429
• 502 invalid_raw_timestamp; raw analytics data could not be read
• 503
• 504 tinybird_timeout; no partial diagnostic

Generate external purchase pixel snippet

/external-pixels/snippet

Requires a secret API key with the external_pixels:write scope; the response embeds a signed ingest credential, so read-scoped and publishable keys receive 403 Forbidden.

Request body

{
  globalName?: string = "apexExternalPurchase"
  handoverParam?: string = "drip_bucket"
  provider?: string = "external"
}

Responses

• 200 Generated snippet
• 400
• 401
• 403
• 429
• 500 The server cannot sign the snippet's ingest credential because signing is not configured, or an unexpected server error occurred. Unexpected errors carry error.details.
• 503

List flags

/flags

Parameters

• limit in query
• cursor in query

Responses

• 200 Flags with cursor pagination
• 400
• 401
• 403
• 404
• 429
• 503

Create flag

/flags

Request body

{ $ref: "FeatureFlagInput" }

Responses

• 201 Created flag
• 400
• 401
• 403
• 404
• 429
• 503

Get flag

/flags/{id}

Parameters

• id in path required

Responses

• 200 Flag
• 401
• 403
• 404
• 429
• 503

Update flag

/flags/{id}

Parameters

• id in path required

Request body

{ $ref: "FeatureFlagUpdateInput" }

Responses

• 200 Updated flag
• 400
• 401
• 403
• 404
• 429
• 503

Activate flag

/flags/{id}/activate

Parameters

• id in path required

Responses

• 200 Updated flag
• 401
• 403
• 404
• 429
• 503

Archive flag

/flags/{id}/archive

Parameters

• id in path required

Responses

• 200 Updated flag
• 401
• 403
• 404
• 429
• 503

Update flag On variant code

/flags/{id}/code

Edits only the On variant code through artifact validation and review. Omitted code is preserved; null clears it. The precondition refers to the On variant. A 502 receipt with saved=true means persistence succeeded but publication failed; do not blindly retry. needs_review is advisory for an already active flag.

Parameters

• id in path required

Request body

{
  custom_css?: string | null
  custom_js?: string | null
  expected_artifact_hash?: string
  expected_updated_at?: string (date-time)
}

Responses

• 200 Code saved; publication status is reported separately
• 400 Validation or artifact review refused the save
• 401
• 403
• 404
• 409
• 429
• 502 Code saved but storefront publication failed
• 503

Conclude flag with a winning variant

/flags/{id}/conclude

Parameters

• id in path required

Request body

{
  variant_key: string
}

Responses

• 200 Concluded flag
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Create a rule experience

/flags/{id}/experiences

Uses the parent flag expected_updated_at. Stale versions and archived flags return 409. Rule removals retain history. Referenced experiences cannot be deleted. The response is the complete updated flag. Experience saves include code_save with artifact review and publication receipts. A 502 error.details receipt with saved=true means the write committed but publication failed; reload before retrying. Rule saves report publication_warning separately.

Parameters

• id in path required

Request body

{
  anti_flicker_selectors?: string[]
  code_delivery_mode?: "inline" | "external"
  custom_css?: string | null
  custom_js?: string | null
  environment_key?: string
  expected_updated_at: string (date-time)
  key: string
  mutations?: any[]
  name: string
  reset_js?: string | null
  value?: any
}

Responses

• 201 Updated flag
• 400
• 401
• 403
• 404
• 409
• 422
• 429
• 502 Experience saved but publication failed. The error details preserve the saved receipt.
• 503

Update a rule experience

/flags/{id}/experiences/{experienceId}

Uses the parent flag expected_updated_at. Stale versions and archived flags return 409. Rule removals retain history. Referenced experiences cannot be deleted. The response is the complete updated flag. Experience saves include code_save with artifact review and publication receipts. A 502 error.details receipt with saved=true means the write committed but publication failed; reload before retrying. Rule saves report publication_warning separately.

Parameters

• id in path required
• experienceId in path required

Request body

{
  anti_flicker_selectors?: string[]
  code_delivery_mode?: "inline" | "external"
  custom_css?: string | null
  custom_js?: string | null
  environment_key?: string
  expected_updated_at: string (date-time)
  key?: string
  mutations?: any[]
  name?: string
  reset_js?: string | null
  value?: any
}

Responses

• 200 Updated flag
• 400
• 401
• 403
• 404
• 409
• 422
• 429
• 502 Experience saved but publication failed. The error details preserve the saved receipt.
• 503

Delete an unreferenced rule experience

/flags/{id}/experiences/{experienceId}

Uses the parent flag expected_updated_at. Stale versions and archived flags return 409. Rule removals retain history. Referenced experiences cannot be deleted. The response is the complete updated flag. Experience saves include code_save with artifact review and publication receipts. A 502 error.details receipt with saved=true means the write committed but publication failed; reload before retrying. Rule saves report publication_warning separately.

Parameters

• id in path required
• experienceId in path required

Request body

{
  environment_key?: string
  expected_updated_at: string (date-time)
}

Responses

• 200 Updated flag
• 400
• 401
• 403
• 404
• 409
• 422
• 429
• 503

Pause flag

/flags/{id}/pause

Parameters

• id in path required

Responses

• 200 Updated flag
• 401
• 403
• 404
• 429
• 503

List flag QA devices

/flags/{id}/qa-devices

Parameters

• id in path required

Responses

• 200 Active QA devices
• 400
• 401
• 403
• 404
• 429
• 503

Register or update a flag QA device

/flags/{id}/qa-devices

Parameters

• id in path required

Request body

{ $ref: "FlagQaDeviceInput" }

Responses

• 200 Registered QA device
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Remove a flag QA device

/flags/{id}/qa-devices/{identity}

Parameters

• id in path required
• identity in path required

Responses

• 200 Removed
• 400
• 401
• 403
• 404
• 429
• 503

Reopen a concluded flag

/flags/{id}/reopen

Parameters

• id in path required

Responses

• 200 Reopened flag
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Replace ordered flag audiences

/flags/{id}/rules

Uses the parent flag expected_updated_at. Stale versions and archived flags return 409. Rule removals retain history. Referenced experiences cannot be deleted. The response is the complete updated flag. Experience saves include code_save with artifact review and publication receipts. A 502 error.details receipt with saved=true means the write committed but publication failed; reload before retrying. Rule saves report publication_warning separately.

Parameters

• id in path required

Request body

{
  environment_key?: string
  expected_updated_at: string (date-time)
  rules: object[]
}

Responses

• 200 Updated flag
• 400
• 401
• 403
• 404
• 409
• 422
• 429
• 503

Reorder flag audiences

/flags/{id}/rules/reorder

Uses the parent flag expected_updated_at. Stale versions and archived flags return 409. Rule removals retain history. Referenced experiences cannot be deleted. The response is the complete updated flag. Experience saves include code_save with artifact review and publication receipts. A 502 error.details receipt with saved=true means the write committed but publication failed; reload before retrying. Rule saves report publication_warning separately.

Parameters

• id in path required

Request body

{
  environment_key?: string
  expected_updated_at: string (date-time)
  rules: object[]
}

Responses

• 200 Updated flag
• 400
• 401
• 403
• 404
• 409
• 422
• 429
• 503

Get flag edge publication status

/flags/{id}/status

Returns database publication metadata, the propagation worst-case window derived from the shop's effective runtime cache TTLs, and, for visual flags, the public edge config URL used to confirm propagation. API-delivered flags have no public config URL and are available through /v1/assign.

Parameters

• id in path required

Responses

• 200 Flag publication status
• 401
• 403
• 404
• 429
• 503

List funnels

/funnels

Parameters

• limit in query
• cursor in query
• include_archived in query - Include archived funnels.

Responses

• 200 funnels list
• 400
• 401
• 403
• 404
• 429
• 503

Create funnels

/funnels

Request body

{ $ref: "FunnelInput" }

Responses

• 201 funnels created
• 400
• 401
• 403
• 404
• 409
• 422
• 429
• 503

Get funnel

/funnels/{id}

Parameters

• id in path required

Responses

• 200 funnel returned
• 400
• 401
• 403
• 404
• 429
• 503

Update funnel

/funnels/{id}

Parameters

• id in path required

Request body

{ $ref: "FunnelUpdateInput" }

Responses

• 200 funnel returned
• 400
• 401
• 403
• 404
• 409
• 422
• 429
• 503

Archive funnel

/funnels/{id}

Archives the funnel instead of destroying it.

Parameters

• id in path required

Responses

• 200 funnel deleted
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Restore funnel

/funnels/{id}/restore

Parameters

• id in path required

Responses

• 200 Restored funnel
• 400
• 401
• 403
• 404
• 429
• 503

List landing pages

/landing-pages

Requires the Apex Labs feature for the shop; shops without it receive 404 Not Found.

Parameters

• limit in query
• cursor in query
• status in query

Responses

• 200 Landing pages with cursor pagination
• 400
• 401
• 403
• 404 Apex Labs is not enabled for this shop, so landing pages are unavailable.
• 429
• 503

Create landing page

/landing-pages

Creates a landing page to build outside Apex: pull its checkout, apply a bundle, deploy. With idea_key the page records the idea, and experiments created on it link to that idea. Requires the landing-pages feature for the shop; shops without it receive 404 Not Found.

Request body

{
  idea_key?: string
  name: string
  slug?: string
}

Responses

• 201 Landing page created
• 400
• 401
• 403
• 404
• 409
• 429
• 503

List landing-page domains

/landing-pages/domains

Requires the landing-pages entitlement for the shop; shops without it receive 404 Not Found. Returns the shop's claimed and registered hostnames, newest first, without removed ones. At most 200; has_more is true when the list was cut. Pass host to look up one hostname.

Parameters

• host in query - Return only this hostname, canonicalized as the server stores it (lowercase, punycode, no scheme, port or path). Finds a record the 200-row list cut, and a removed record whose Cloudflare hostname delete has not finished (status removed), so DELETE can be retried.

Responses

• 200 Landing-page domains, newest first
• 400 host is not a valid hostname (invalid_host)
• 401
• 403
• 404
• 429
• 503

Claim or register a landing-page domain

/landing-pages/domains

Requires the landing-pages entitlement for the shop; shops without it receive 404 Not Found. mode claim adds a hostname the client controls: point a CNAME at dns_target, then call verify. Claiming the same hostname again returns the existing record (200). mode register buys a new domain on the Drip Cloudflare account, billed to the client on the next DRIP invoice, and needs a user key whose user can write landing pages (owner, admin or editor); Drip staff are notified of every purchase: the first call answers 409 with the quote, and a repeat with confirm_price equal to the quote registers it with auto-renew and WHOIS redaction on. Repeating a register call for a domain this shop already registered resumes its setup and never buys twice.

Request body

{
  confirm_price?: object
  host: string
  mode: "claim" | "register"
  years?: integer = 1
}

Responses

• 200 Existing record (repeat claim, or resumed registration)
• 201 Created record with DNS instructions
• 400
• 401
• 403
• 404
• 409 Conflict or price confirmation required
• 429
• 502 Cloudflare refused or failed the hostname or registrar call: registrar_refused (Cloudflare rejected the order, nothing was charged, the domain can be ordered again) or registrar_failed (the outcome is unknown; run verify)
• 503 Cloudflare Registrar is not configured (registrar_unconfigured), the token lacks Registrar permission (registrar_permission_missing), or the database is briefly busy (database_busy, with Retry-After)

Remove a landing-page domain

/landing-pages/domains/{id}

Requires the landing-pages entitlement for the shop; shops without it receive 404 Not Found. Deletes the Cloudflare custom hostname and marks the record removed. Refuses with 409 domain_in_use while a published landing page serves the host, and with 409 domain_registration_in_progress while a registration order is unsettled (run verify first). For a charged registration it writes the rebilling audit first and answers 503 domain_audit_pending while that write fails. A registered domain stays registered on the Drip Cloudflare account. Removing a removed record returns it unchanged.

Parameters

• id in path required

Responses

• 200 The removed record
• 401
• 403
• 404
• 409
• 429
• 502 Cloudflare could not delete the custom hostname
• 503

Check a landing-page domain

/landing-pages/domains/{id}/verify

Requires the landing-pages entitlement for the shop; shops without it receive 404 Not Found. Reads the Cloudflare custom hostname, the registration workflow (mode register) and public DNS, then records the status: pending (no CNAME to the edge yet), verifying (CNAME seen, hostname or certificate not active), active, or failed. For a registered domain it also finishes setup steps an earlier call could not complete; it never orders a domain.

Parameters

• id in path required

Responses

• 200 The record with its current status
• 401
• 403
• 404
• 409
• 429
• 502 Cloudflare could not provision the custom hostname
• 503

Get landing page

/landing-pages/{id}

Parameters

• id in path required

Responses

• 200 Landing page
• 401
• 403
• 404
• 429
• 503

Deploy a landing page version

/landing-pages/{id}/deploy

Publishes a version built outside Apex to the body host or the manifest host (a domain this shop holds), else to the shop's own instant host <shop>.apex-page.com, which the first such deploy assigns; another shop's apex-page.com host is a 400. It upserts its manifest goals and keeps the newest 20 unpublished versions. The Worker injects the shop snippet at serve time unless the manifest turns it off. Requires the landing-pages feature for the shop; shops without it receive 404 Not Found.

Parameters

• id in path required

Request body

{
  host?: string
  path?: string
  version_id?: string (uuid)
}

Responses

• 200 Deployed
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Create a landing page experiment

/landing-pages/{id}/experiment

Creates a draft experiment that splits the page's live URL between two versions, with the manifest goals attached (the first, or primary_goal, as primary) and the page's idea linked. Starting it is done in the dashboard. Requires the landing-pages feature for the shop; shops without it receive 404 Not Found.

Parameters

• id in path required

Request body

{
  control: integer
  name?: string
  primary_goal?: string
  variant: integer
}

Responses

• 201 Experiment created
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Pull a landing page checkout

/landing-pages/{id}/filesystem

Without paths: the current version's apex-landing-page.json, its file list (path, sha256, bytes) and the context folder (brand, catalog, offers, reviews, brief, idea). With paths: those files' contents, utf8 for text and base64 for binary files. Requires the landing-pages feature for the shop; shops without it receive 404 Not Found.

Parameters

• paths in query - Comma-separated file paths whose contents to return (at most 32 paths and 3145728 bytes). Without it the response lists files and carries the manifest and context.
• id in path required

Responses

• 200 Checkout
• 400
• 401
• 403
• 404
• 409
• 413 Requested files exceed one response
• 429
• 503

Apply a landing page bundle

/landing-pages/{id}/filesystem/apply

Stores the bundle as a new version, makes it current, upserts the manifest goals and returns the version and a signed preview link. Files arrive inline, unchanged from the current version, or staged through filesystem/upload. Requires the landing-pages feature for the shop; shops without it receive 404 Not Found.

Parameters

• id in path required

Request body

{
  base_version_id?: string (uuid) | null
  files: object[]
  manifest: object
}

Responses

• 201 Applied version
• 400
• 401
• 403
• 404
• 409
• 413 Bundle exceeds 300 files or 100 MB
• 429
• 503

Plan a landing page bundle

/landing-pages/{id}/filesystem/plan

Validates a bundle and its manifest and returns what an apply would change (added, changed, removed files, manifest and goal changes, files to upload first). Writes nothing. Requires the landing-pages feature for the shop; shops without it receive 404 Not Found.

Parameters

• id in path required

Request body

{
  base_version_id?: string (uuid) | null
  files: object[]
  manifest: object
}

Responses

• 200 Plan
• 400
• 401
• 403
• 404
• 413 Bundle exceeds 300 files or 100 MB
• 429
• 503

Upload landing page files

/landing-pages/{id}/filesystem/upload

Stages file bytes, keyed by sha256, for a following apply. Upload the files a plan lists under upload_required in batches of at most 32 files and 3 MB. Requires the landing-pages feature for the shop; shops without it receive 404 Not Found.

Parameters

• id in path required

Request body

{
  files: object[]
}

Responses

• 201 Staged files
• 400
• 401
• 403
• 404
• 413 Batch exceeds 32 files or 3 MB
• 429
• 503

Grant a direct video upload

/landing-pages/{id}/filesystem/upload-grant

Issues a 15-minute single-file grant bound to shop, page, base version, path, byte size and SHA-256. MP4 and WebM over 3 MB and up to 50 MB upload directly to the Worker using resumable 8 MB multipart parts. Only hash-verified bytes can be applied. Requires the landing-pages feature for the shop; shops without it receive 404 Not Found.

Parameters

• id in path required

Request body

{
  base_version_id: string (uuid) | null
  bytes: integer
  path: string
  sha256: string
}

Responses

• 201 Video upload grant
• 400
• 401
• 403
• 404
• 409 Base version changed or page archived
• 429
• 503

Get a landing page preview link

/landing-pages/{id}/preview

A fresh signed preview link (valid 24 hours, no dashboard login) for the current version, or for the version number in ?version=. Requires the landing-pages feature for the shop; shops without it receive 404 Not Found.

Parameters

• id in path required
• version in query

Responses

• 200 Preview link
• 400
• 401
• 403
• 404
• 429
• 503

Roll back a landing page

/landing-pages/{id}/rollback

Deploys an earlier version to the page's current host and path. Requires the landing-pages feature for the shop; shops without it receive 404 Not Found.

Parameters

• id in path required

Request body

{
  version_id?: string (uuid)
  version_number?: integer
}

Responses

• 200 Deployed
• 400
• 401
• 403
• 404
• 409
• 429
• 503

List landing page versions

/landing-pages/{id}/versions

Every version, newest first, with its source (generator or bundle), author, size and whether it is current or published. Requires the landing-pages feature for the shop; shops without it receive 404 Not Found.

Parameters

• id in path required

Responses

• 200 Versions
• 400
• 401
• 403
• 404
• 429
• 503

List pages

/pages

Parameters

• limit in query
• cursor in query

Responses

• 200 pages list
• 400
• 401
• 403
• 404
• 429
• 503

Create pages

/pages

Request body

{ $ref: "PageInput" }

Responses

• 201 pages created
• 400
• 401
• 403
• 404
• 409
• 422
• 429
• 503

Get page

/pages/{id}

Parameters

• id in path required

Responses

• 200 page returned
• 400
• 401
• 403
• 404
• 429
• 503

Update page

/pages/{id}

Parameters

• id in path required

Request body

{ $ref: "PageUpdateInput" }

Responses

• 200 page returned
• 400
• 401
• 403
• 404
• 409 Conflict. A live-consumer acknowledgement conflict returns the PageLiveImpactError shape — repeat the request with confirm_live_impact and confirmed_consumer_ids carrying every id listed. A trigger-propagation race or duplicate API name returns the generic Error shape.
• 422
• 429
• 503

Delete page

/pages/{id}

Parameters

• id in path required

Responses

• 200 page deleted
• 400
• 401
• 403
• 404
• 409
• 429
• 503

List segments

/segments

Parameters

• limit in query
• cursor in query

Responses

• 200 segments list
• 400
• 401
• 403
• 404
• 429
• 503

Create segments

/segments

Request body

{ $ref: "SegmentInput" }

Responses

• 201 segments created
• 400
• 401
• 403
• 404
• 409
• 422
• 429
• 503

Update segment

/segments/{id}

Parameters

• id in path required

Request body

{ $ref: "SegmentUpdateInput" }

Responses

• 200 segment returned
• 400
• 401
• 403
• 404
• 409 Atomic refusal: a blocked consumer, concurrent edit, or more than 200 consumer expansions in one transaction. Limit refusals use segment_propagation_limit; nothing is saved or queued.
• 422
• 429
• 503

Delete segment

/segments/{id}

Parameters

• id in path required

Responses

• 200 segment deleted
• 400
• 401
• 403
• 404
• 409
• 429
• 503

List signals

/signals

The first page includes the built-in signal catalog before paginated custom signals. Built-ins do not participate in cursor pagination.

Parameters

• limit in query
• cursor in query
• include_archived in query - Include archived custom signals when true. Built-in signals are always active.

Responses

• 200 Paginated signals
• 400
• 401
• 403
• 429
• 503

Create a signal

/signals

Request body

{ $ref: "SignalCreate" }

Responses

• 201 Created
• 400
• 401
• 403
• 409
• 429
• 503

Get a signal

/signals/{id}

Parameters

• id in path required - Custom signal UUID or built-in catalog signal key (e.g. url.full).

Responses

• 200 Resource
• 401
• 403
• 404
• 429
• 503

Update a signal

/signals/{id}

Parameters

• id in path required - Custom signal UUID or built-in catalog signal key (e.g. url.full).

Request body

{ $ref: "SignalUpdate" }

Responses

• 200 Updated
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Delete or archive a signal

/signals/{id}

Parameters

• id in path required - Custom signal UUID or built-in catalog signal key (e.g. url.full).

Responses

• 200 Deleted or archived
• 401
• 403
• 404
• 429
• 503

List surveys

/surveys

Requires the Surveys lab for the shop; shops without it receive 404 Not Found.

Parameters

• limit in query
• cursor in query
• status in query

Responses

• 200 Surveys
• 400
• 401
• 403
• 404
• 429
• 503

Create survey

/surveys

Requires the Surveys lab for the shop; shops without it receive 404 Not Found.

Request body

{ $ref: "SurveyInput" }

Responses

• 201 Created survey
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Get survey

/surveys/{id}

Requires the Surveys lab for the shop; shops without it receive 404 Not Found.

Parameters

• id in path required

Responses

• 200 Survey
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Delete survey

/surveys/{id}

Requires the Surveys lab for the shop; shops without it receive 404 Not Found. Deletes a draft or completed survey; live and paused surveys must be ended first.

Parameters

• id in path required

Responses

• 200 Deleted survey
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Update survey

/surveys/{id}

Requires the Surveys lab for the shop; shops without it receive 404 Not Found.

Parameters

• id in path required

Request body

{ $ref: "SurveyUpdateInput" }

Responses

• 200 Updated survey
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Complete survey

/surveys/{id}/complete

Requires the Surveys lab for the shop; shops without it receive 404 Not Found.

Parameters

• id in path required

Responses

• 200 Survey
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Duplicate survey

/surveys/{id}/duplicate

Requires the Surveys lab for the shop; shops without it receive 404 Not Found.

Parameters

• id in path required

Responses

• 201 Survey
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Pause survey

/surveys/{id}/pause

Requires the Surveys lab for the shop; shops without it receive 404 Not Found.

Parameters

• id in path required

Responses

• 200 Survey
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Start survey

/surveys/{id}/start

Requires the Surveys lab for the shop; shops without it receive 404 Not Found.

Parameters

• id in path required

Responses

• 200 Survey
• 400
• 401
• 403
• 404
• 409
• 429
• 503

Preview brand completion undo

/api/multi-shop-programs/{id}/actions/undo-completion/preview

Not yet enabled: both routes return 404 while the server rollout is off. Dashboard session, required initiating shop pin, program access and per-store write/launch rights. Explicit all_with_source includes the source once; all means copies only; shop_id selects source or one copy. Preview is read-only. Apply binds actor, pin, policy, exact targets and program membership. Structural conflicts before execution write nothing. Later refusals produce partial receipts; each target commits independently. A same-key replay never repeats committed lifecycle work. Re-completion requires a new preview and key.

Parameters

• id in path required
• x-apex-shop in header required

Request body

{
  scope?: "all" | "all_with_source"
  shop_id?: string (uuid)
}

Responses

• 200 Per-store eligibility and redacted no-access targets
• 400 Typed refusal. Errors after partial work carry committed:true and durable, access-redacted receipts.
• 401 Typed refusal. Errors after partial work carry committed:true and durable, access-redacted receipts.
• 403 Typed refusal. Errors after partial work carry committed:true and durable, access-redacted receipts.
• 404 Not found, including while server rollout is off.
• 409 Typed refusal. Errors after partial work carry committed:true and durable, access-redacted receipts.
• 500 Typed refusal. Errors after partial work carry committed:true and durable, access-redacted receipts.
• 503 Typed refusal. Errors after partial work carry committed:true and durable, access-redacted receipts.

Undo completion independently in each reviewed store

/api/multi-shop-programs/{id}/actions/undo-completion

Not yet enabled: both routes return 404 while the server rollout is off. Dashboard session, required initiating shop pin, program access and per-store write/launch rights. Explicit all_with_source includes the source once; all means copies only; shop_id selects source or one copy. Preview is read-only. Apply binds actor, pin, policy, exact targets and program membership. Structural conflicts before execution write nothing. Later refusals produce partial receipts; each target commits independently. A same-key replay never repeats committed lifecycle work. Re-completion requires a new preview and key.

Parameters

• id in path required
• x-apex-shop in header required

Request body

{
  scope?: "all" | "all_with_source"
  shop_id?: string (uuid)
  reason: string
  idempotency_key: string (uuid)
  preview_version: string
  targets: object[]
}

Responses

• 200 Durable store receipts, including partial or fully blocked results
• 400 Typed refusal. Errors after partial work carry committed:true and durable, access-redacted receipts.
• 401 Typed refusal. Errors after partial work carry committed:true and durable, access-redacted receipts.
• 403 Typed refusal. Errors after partial work carry committed:true and durable, access-redacted receipts.
• 404 Not found, including while server rollout is off.
• 409 Typed refusal. Errors after partial work carry committed:true and durable, access-redacted receipts.
• 500 Typed refusal. Errors after partial work carry committed:true and durable, access-redacted receipts.
• 503 Typed refusal. Errors after partial work carry committed:true and durable, access-redacted receipts.

Create a rule experience

/api/flags/{id}/experiences

Uses the parent flag expected_updated_at. Stale versions and archived flags return 409. Rule removals retain history. Referenced experiences cannot be deleted. The response is the complete updated flag. Experience saves include code_save with artifact review and publication receipts. A 502 error.details receipt with saved=true means the write committed but publication failed; reload before retrying. Rule saves report publication_warning separately.

Parameters

• id in path required

Request body

{
  anti_flicker_selectors?: string[]
  code_delivery_mode?: "inline" | "external"
  custom_css?: string | null
  custom_js?: string | null
  environment_key?: string
  expected_updated_at: string (date-time)
  key: string
  mutations?: any[]
  name: string
  reset_js?: string | null
  value?: any
}

Responses

• 201 Updated flag
• 400 Request refused
• 401 Request refused
• 403 Request refused
• 404 Request refused
• 409 Request refused
• 422 Request refused
• 429 Request refused
• 502 Request refused
• 503 Request refused

Update a rule experience

/api/flags/{id}/experiences/{experienceId}

Uses the parent flag expected_updated_at. Stale versions and archived flags return 409. Rule removals retain history. Referenced experiences cannot be deleted. The response is the complete updated flag. Experience saves include code_save with artifact review and publication receipts. A 502 error.details receipt with saved=true means the write committed but publication failed; reload before retrying. Rule saves report publication_warning separately.

Parameters

• id in path required
• experienceId in path required

Request body

{
  anti_flicker_selectors?: string[]
  code_delivery_mode?: "inline" | "external"
  custom_css?: string | null
  custom_js?: string | null
  environment_key?: string
  expected_updated_at: string (date-time)
  key?: string
  mutations?: any[]
  name?: string
  reset_js?: string | null
  value?: any
}

Responses

• 200 Updated flag
• 400 Request refused
• 401 Request refused
• 403 Request refused
• 404 Request refused
• 409 Request refused
• 422 Request refused
• 429 Request refused
• 502 Request refused
• 503 Request refused

Delete an unreferenced rule experience

/api/flags/{id}/experiences/{experienceId}

Uses the parent flag expected_updated_at. Stale versions and archived flags return 409. Rule removals retain history. Referenced experiences cannot be deleted. The response is the complete updated flag. Experience saves include code_save with artifact review and publication receipts. A 502 error.details receipt with saved=true means the write committed but publication failed; reload before retrying. Rule saves report publication_warning separately.

Parameters

• id in path required
• experienceId in path required

Request body

{
  environment_key?: string
  expected_updated_at: string (date-time)
}

Responses

• 200 Updated flag
• 400 Request refused
• 401 Request refused
• 403 Request refused
• 404 Request refused
• 409 Request refused
• 422 Request refused
• 429 Request refused
• 503 Request refused

Replace ordered flag audiences

/api/flags/{id}/rules

Uses the parent flag expected_updated_at. Stale versions and archived flags return 409. Rule removals retain history. Referenced experiences cannot be deleted. The response is the complete updated flag. Experience saves include code_save with artifact review and publication receipts. A 502 error.details receipt with saved=true means the write committed but publication failed; reload before retrying. Rule saves report publication_warning separately.

Parameters

• id in path required

Request body

{
  environment_key?: string
  expected_updated_at: string (date-time)
  rules: object[]
}

Responses

• 200 Updated flag
• 400 Request refused
• 401 Request refused
• 403 Request refused
• 404 Request refused
• 409 Request refused
• 422 Request refused
• 429 Request refused
• 503 Request refused

Reorder flag audiences

/api/flags/{id}/rules/reorder

Uses the parent flag expected_updated_at. Stale versions and archived flags return 409. Rule removals retain history. Referenced experiences cannot be deleted. The response is the complete updated flag. Experience saves include code_save with artifact review and publication receipts. A 502 error.details receipt with saved=true means the write committed but publication failed; reload before retrying. Rule saves report publication_warning separately.

Parameters

• id in path required

Request body

{
  environment_key?: string
  expected_updated_at: string (date-time)
  rules: object[]
}

Responses

• 200 Updated flag
• 400 Request refused
• 401 Request refused
• 403 Request refused
• 404 Request refused
• 409 Request refused
• 422 Request refused
• 429 Request refused
• 503 Request refused

Undo completion in the same run

/api/experiments/{id}/undo-completion

Not yet enabled: both routes return 404 while the server rollout is off. Dashboard session only. Requires experiments:write and experiments:launch for running restoration. Preview never writes. Applies re-read policy and bind actor, shop, completion, definition, history and membership versions. Committed refresh failures remain HTTP 200; retry the same key for publication only. Queued retries and in-flight external sends may still deliver.

Parameters

• id in path required
• x-apex-shop in header required

Request body

{
  expected_assignment_epoch: integer
  preview_version: string
  completion_id: string (uuid)
  idempotency_key: string (uuid)
  reason: string
}

Responses

• 200 Durable commit receipt or idempotent replay
• 400 invalid_request / shop_pin_required
• 401 unauthenticated
• 403 no_permission / member_suspended
• 404 experiment_not_found
• 409 undo_window_expired / undo_disabled / serving_derivative_exists / configuration_changed / assignment_epoch_mismatch / scheduled_end_in_past / resume_blocked / experiment_changed / run_changed / preview_changed / policy_changed / program_deployment_moved / completion_scope_mismatch / completion_evidence_missing / completion_not_last_lifecycle_event / run_not_closed_by_completion / completion_timestamp_missing / status_not_completed / experiment_archived / program_archived / program_action_in_progress / action_in_progress / idempotency_key_mismatch
• 503 policy_unavailable

Preview same-run completion undo

/api/experiments/{id}/undo-completion/preview

Not yet enabled: both routes return 404 while the server rollout is off. Dashboard session only. Requires experiments:write and experiments:launch for running restoration. Preview never writes. Applies re-read policy and bind actor, shop, completion, definition, history and membership versions. Committed refresh failures remain HTTP 200; retry the same key for publication only. Queued retries and in-flight external sends may still deliver.

Parameters

• id in path required
• x-apex-shop in header required

Request body

{
  expected_assignment_epoch: integer
}

Responses

• 200 Eligible or blocked read-only preview
• 400 invalid_request / shop_pin_required
• 401 unauthenticated
• 403 no_permission / member_suspended
• 404 experiment_not_found
• 409 undo_window_expired / undo_disabled / serving_derivative_exists / configuration_changed / assignment_epoch_mismatch / scheduled_end_in_past / resume_blocked / experiment_changed / run_changed / preview_changed / policy_changed / program_deployment_moved / completion_scope_mismatch / completion_evidence_missing / completion_not_last_lifecycle_event / run_not_closed_by_completion / completion_timestamp_missing / status_not_completed / experiment_archived / program_archived / program_action_in_progress / action_in_progress / idempotency_key_mismatch
• 503 policy_unavailable

Attach or upload QA evidence

/experiments/{id}/qa/evidence

Attaches a terminal screenshot job, writes typed evidence records, or uploads QA evidence images. Exactly one request form is accepted per call.

Request body

any

Responses

• 200 Signed QA run with the updated evidence
• 400
• 401
• 403
• 404
• 409
• 429
• 502 Evidence upload failed
• 503

Create an artifact-injecting proxy preview session

/preview-sessions

Requires a secret API key with experiments:write. The returned short-lived URL is a bearer capability that renders the selected draft variation without a dashboard session or installed Apex snippet.

Request body

{
  experiment_id: string
  variation_id?: string
  target_url?: string (uri)
  ttl_hours?: integer = 168
}

Responses

• 200 Preview session
• 400
• 401
• 403
• 404
• 409 QA run changed during preview; retry
• 429
• 503

List experiments

/experiments

Returns a paginated list of experiments. Supports cursor-based pagination and optional status filter.

Parameters

• view in query - Full retains the existing response; summary omits code, targeting objects and goals unless fields requests a full-view field, which switches automatically to full details.
• fields in query - Comma-separated top-level keys. Always keeps id. Fields outside summary switch automatically to full details. Unknown keys return 400 with allowed keys.
• status in query
• url in query - Absolute storefront URL; returns only experiments whose effective URL targeting matches it, evaluated server-side. Experiments with no URL rules match every URL.
• archived in query - Set to 1 to include archived experiments
• limit in query
• cursor in query - ID of the last item from the previous page

Responses

• 200 Paginated list of experiments
• 400 invalid_view, invalid_fields, or invalid_status; the error lists allowed values.
• 401 Unauthorized
• 429 Rate limit exceeded
• 503

Create experiment

/experiments

Creates a new experiment. Default control and variant are created if variations are not provided. Omitted statistical settings use the shop testing defaults. Experiments authenticated with a user API key default owner_user_id to that key's user; organization- and shop-scoped keys have no user and leave the owner null. When commerce sentinel mutations are supplied without goals, the shop default takes priority, followed by the oldest active unscoped revenue goal. The first attached goal is primary. For mutation drafts with URL or page-rule targeting, omitted or null store_url triggers an observed-page inventory lookup with a 1.5-second budget before the database transaction. A matching observed URL is saved only if it still matches the final persisted targeting. If no matching page is available, including on lookup timeout, store_url remains null and the partial draft is still created. An explicit store_url takes precedence. Redirect creation keeps its existing entry-URL behavior.

Request body

{
  name: string
  slug?: string | null
  description?: string | null
  backlog_item_id?: string (uuid)
  idea_key?: string
  as_follow_up?: boolean = false
  owner_user_id?: string (uuid) | null
  counting_type?: "standard" | "setup_test" | "aa_test" | "non_program" = "standard"
  delivery_type?: "mutation" | "redirect" = "mutation"
  type?: "standard" | "setup_test" | "aa_test" | "non_program"
  experiment_type?: "mutation" | "redirect"
  traffic_allocation?: number = 1
  experiment_js?: string | null
  experiment_reset_js?: string | null
  experiment_css?: string | null
  sequential_testing_enabled?: boolean
  significance_level?: number
  statistical_power?: number
  store_url?: string (uri) | null
  auto_stop_override?: AutoStopOverride
  guardian_override?: GuardianOverride
  targeting?: ExperimentTargeting | null
  variations?: object[]
  primary_goal_id?: string (uuid) | null
  goal_ids?: string (uuid)[]
  expectedCommerceRevision?: integer | null
  expectedArtifactHash?: string
  definition?: object
}

Responses

• 200 Existing experiment already linked to the backlog item
• 201 Experiment created
• 400 Validation error
• 401 Unauthorized
• 404 Backlog item not found for this shop
• 409 commerce_definition_revision_conflict, artifact_hash_conflict, commerce_definition_legacy_readonly, or workspace/file conflict. No automatic retry with fresh tokens.
• 422 Backlog item requires customer approval or the dashboard landing-page handoff, or both backlog_item_id and idea_key were sent commerce_definition_feature_unavailable with escaped paths; no partial authoring writes.
• 429 Rate limit exceeded
• 503

Get experiment

/experiments/{id}

Returns a single experiment by ID with variations and goals.

Parameters

• include in query - Pass preview_target to resolve and include the preview destination. Omitted by default to avoid an inventory lookup.
• id in path required

Responses

• 200 Experiment details
• 404 Experiment not found

Update experiment

/experiments/{id}

Partially updates an experiment. Completed experiments accept only a window-only body (`results_weekdays`), which changes how the ended test is judged without editing the test. Audience and page targeting writes return 409 composition_locked while an experiment is running, completed or archived; the v1 API accepts other edits on draft experiments only, except a body that carries only `results_weekdays`, which it accepts on non-draft experiments. Unchanged launch-critical values preserve existing QA approval and scheduling. Material setup changes revoke launch readiness and write a same-transaction Activity audit with reason `launch_critical_edit`. If that required audit fails, the update fails and rolls back.

Parameters

• id in path required

Request body

{
  name?: string
  slug?: string | null
  description?: string | null
  owner_user_id?: string (uuid) | null
  results_weekdays?: ResultsWeekdays | null
  counting_type?: "standard" | "setup_test" | "aa_test" | "non_program"
  type?: "standard" | "setup_test" | "aa_test" | "non_program"
  traffic_allocation?: number
  experiment_js?: string | null
  experiment_reset_js?: string | null
  experiment_css?: string | null
  sequential_testing_enabled?: boolean
  store_url?: string (uri) | null
  auto_stop_override?: AutoStopOverride
  guardian_override?: GuardianOverride
  targeting?: ExperimentTargeting | null
  confirmTargetingReplace?: boolean
}

Responses

• 200 Experiment updated
• 400 Cannot update completed experiment (a window-only results_weekdays body is the exception)
• 404 Experiment not found
• 409 Targeting replacement requires confirmation (error.code confirm_targeting_replace_required): the update would replace the experiment's author-explicit URL targeting with a page-entity rule. Retry with confirmTargetingReplace: true. Retired historical targeting writes return 409 checkout_mode_retired.
• 422 Invalid experiment constraints.

Archive experiment

/experiments/{id}

Archives an experiment while preserving its variations and results history.

Parameters

• id in path required

Responses

• 200 Experiment deleted
• 404 Experiment not found

Read the experiment filesystem JSON Schema

/experiments/filesystem/schema

Returns the versioned JSON Schema document bundled by the Apex CLI.

Responses

• 200 Experiment filesystem schema
• 401 Unauthorized
• 403 Forbidden
• 429
• 503

Read experiment filesystem

/experiments/{id}/filesystem

Returns the complete canonical filesystem snapshot for an experiment. Commerce drafts are represented as typed commerce/<kind>.json files with read-only serverOwned fields. commerce/discount-codes.json declares per-variation code blocking and optional en/de messages (1 to 120 characters); control never blocks. It combines with price, shipping and offer levers and requires the automatic offers discount owner at launch. File hashes can be used to detect changes before planning a write.

Parameters

• id in path required

Responses

• 200 Canonical experiment filesystem
• 401 Unauthorized
• 404 Experiment not found
• 429 Rate limit exceeded
• 503

Plan an experiment filesystem apply

/experiments/{id}/filesystem/plan

Validates a complete filesystem snapshot and reports the changes without writing them. Typed commerce files are draft-only and preserve server-owned carrier fields. Draft experiments accept all supported filesystem changes. Paused experiments accept treatment-content changes and redirect destinations. Running experiments accept treatment-content changes only; redirect destinations remain draft/paused-only. Structural changes remain draft-only and are reported with the offending file paths.

Parameters

• id in path required

Request body

{
  files: object[]
}

Responses

• 200 Filesystem apply plan
• 400 Invalid request body
• 401 Unauthorized
• 404 Experiment not found
• 429 Rate limit exceeded
• 503

Apply an experiment filesystem

/experiments/{id}/filesystem/apply

Atomically applies experiment, goal, variation, and variation-artifact changes to draft experiments. Paused experiments accept treatment-content changes and redirect destinations. Running experiments accept treatment-content changes only; redirect destinations remain draft/paused-only. Structural changes remain draft-only and fail closed with the offending file paths. Running artifact writes republish the storefront configuration. A successful response with applied=true means every database change committed. applied=false means no changes from this request committed, except when saved=true reports a committed artifact whose storefront publication failed. Identically re-applying an already committed snapshot is safe and converges on the same final state.

Parameters

• id in path required

Request body

{
  accept_qa_invalidation?: boolean
  confirmTargetingReplace?: boolean
  files: object[]
}

Responses

• 200 Atomic apply outcome
• 400 Invalid request body
• 401 Unauthorized
• 404 Experiment not found
• 409 Targeting replacement requires confirmation (error.code confirm_targeting_replace_required). Retry with confirmTargetingReplace: true. A fresh QA approval requires acknowledgement when accept_qa_invalidation is false (error.code qa_acknowledgment_required, error.details { qa_approved_at, required_acknowledgment }); retry with accept_qa_invalidation: true after reviewing the approval. No writes occur for either confirmation refusal. Retired historical targeting writes return 409 checkout_mode_retired.
• 422 Invalid experiment constraints.
• 429 Rate limit exceeded
• 500 Unexpected failure; the atomic database transaction was rolled back and no filesystem changes committed.
• 503

Get experiment results

/experiments/{id}/results

Returns the canonical experiment results read model, including totals, arms, decision, metrics, timeseries, warnings, and delivery health.

Parameters

• id in path required
• currency in query - Optional ISO currency code for revenue diagnostics.
• segment in query - Include one built-in audience dim:value (for example device:mobile). Include wins over exclude_segment. Unknown dimensions, invalid or unobserved values fall back to the unsliced read with segment_applied.applied false and an explicit reason. One model build per request.
• exclude_segment in query - Exclude one audience dim:value; ignored when segment is also present.

Responses

• 200 Experiment results
• 401 Unauthorized
• 403 API key is missing experiment read permission
• 404 Experiment not found
• 429 Rate limit exceeded
• 503 The default snapshot or live results are still computing, or the database is temporarily busy.

Get experiment by slug

/experiments/by-slug/{slug}

Fetch a single experiment by slug (scoped to the API key's shop). Archived variations are omitted unless include_archived=true.

Parameters

• include in query - Pass preview_target to resolve and include the preview destination. Omitted by default to avoid an inventory lookup.
• include_archived in query - Pass true to include archived variations and their archived_at timestamps.
• slug in path required

Responses

• 200 Experiment details
• 401 Unauthorized
• 404 Experiment not found
• 429 Rate limit exceeded
• 503

Upsert experiment by slug

/experiments/by-slug/{slug}

Idempotently create or update a draft experiment by slug. New experiments use the shop testing defaults for omitted statistical settings and default owner_user_id to the authenticated user for user API keys; organization- and shop-scoped keys leave the owner null. If an experiment exists with this slug and is not in draft status, or an incoming variation slug belongs to an archived variation, returns 409. Unchanged launch-critical values preserve existing QA approval and scheduling. Material setup changes revoke launch readiness and write a same-transaction Activity audit with reason `launch_critical_edit`. If that required audit fails, the update fails and rolls back. On creation, commerce sentinel mutations without goals use the shop default, then the oldest active unscoped revenue goal; existing drafts keep their saved goals. Existing draft-only and replacement semantics still apply: preservation depends on the resulting material values, not merely on omitted fields.

Parameters

• slug in path required

Request body

{
  name: string
  description?: string | null
  counting_type?: "standard" | "setup_test" | "aa_test" | "non_program"
  delivery_type?: "mutation" | "redirect"
  type?: "standard" | "setup_test" | "aa_test" | "non_program"
  experiment_type?: "mutation" | "redirect"
  traffic_allocation?: number = 1
  experiment_js?: string | null
  experiment_reset_js?: string | null
  experiment_css?: string | null
  sequential_testing_enabled?: boolean
  significance_level?: number
  statistical_power?: number
  store_url?: string (uri) | null
  auto_stop_override?: AutoStopOverride
  targeting?: ExperimentTargeting | null
  variations: object[]
  primary_goal_id?: string (uuid) | null
  goal_ids?: string (uuid)[]
  expectedCommerceRevision?: integer | null
  expectedArtifactHash?: string
  definition?: object
}

Responses

• 200 Experiment updated
• 201 Experiment created
• 400 Validation error
• 401 Unauthorized
• 409 Conflict (experiment not in draft status or slug already exists). Retired historical targeting writes return 409 checkout_mode_retired. commerce_definition_revision_conflict, artifact_hash_conflict, commerce_definition_legacy_readonly, or workspace/file conflict. No automatic retry with fresh tokens.
• 422 Invalid experiment constraints. commerce_definition_feature_unavailable with escaped paths; no partial authoring writes.
• 429 Rate limit exceeded
• 503

Attach an idea to an experiment

/experiments/{id}/idea

Links the experiment to one idea. Send exactly one of backlog_item_id or idea_key. Repeating the request returns the existing link with 200 and writes no audit entry.

Parameters

• id in path required

Request body

{
  backlog_item_id?: string (uuid)
  idea_key?: string
  as_follow_up?: boolean = false
}

Responses

• 200 The experiment was already linked to this idea
• 201 Idea attached
• 400 No identifier, or a field of the wrong type
• 401 Unauthorized
• 403
• 404 Experiment or idea not found
• 409 The experiment already carries another idea, the idea already has a primary test, or a follow-up was requested for an idea with no primary test. error.code names which one; the dashboard route reports the same codes.
• 422 Both backlog_item_id and idea_key were sent
• 429 Rate limit exceeded
• 503

Detach the linked idea from an experiment

/experiments/{id}/idea

Removes one idea link. Without an identifier the primary link goes first, then the oldest link.

Parameters

• id in path required
• backlog_item_id in query - Remove the link to this idea instead of the primary link.
• idea_key in query - Shop backlog key alternative to backlog_item_id.

Responses

• 200 Idea detached
• 401 Unauthorized
• 403
• 404 Experiment or idea link not found
• 422 Both backlog_item_id and idea_key were sent, or an identifier was repeated or blank
• 429 Rate limit exceeded
• 503

Pause experiment

/experiments/{id}/pause

Pauses a running experiment.

Parameters

• id in path required
• scope in query - Set to store to act only on this store; omitted acts on every store when this is a brand-test parent.

Responses

• 200 Experiment paused
• 400 Only running experiments can be paused
• 404 Experiment not found
• 502 Commerce configuration failed before commit, or the lifecycle change committed but storefront publication failed
• 503 Publication lock contended; retry after the Retry-After interval

Complete experiment

/experiments/{id}/complete

Marks a running or paused experiment as completed. Sets ended_at timestamp.

Parameters

• id in path required
• scope in query - Set to store to act only on this store; omitted acts on every store when this is a brand-test parent.

Responses

• 200 Experiment completed
• 400 Only running or paused experiments can be completed
• 404 Experiment not found
• 502 Commerce configuration failed before commit, or the lifecycle change committed but storefront publication failed
• 503 Publication lock contended; retry after the Retry-After interval

Duplicate experiment

/experiments/{id}/duplicate

Creates a faithful copy of the experiment in draft status with its configuration, variation artifacts, landing-page bindings, and goal associations. Review, scheduling, runtime, and result state do not carry over.

Parameters

• id in path required

Request body

{
  expectedSourceCommerceRevision?: integer | null
  expectedSourceArtifactHashes?: object
}

Responses

• 201 Duplicate experiment created: the serialized v1 experiment with canonical targeting.url and targeting.authorUrl rule arrays.
• 400 A variation artifact could not be copied; no duplicate is created
• 404 Experiment not found
• 409 A concurrent write caused a temporary transaction conflict (error code tx_write_conflict); retry the request. commerce_definition_revision_conflict, artifact_hash_conflict, commerce_definition_legacy_readonly, or workspace/file conflict. No automatic retry with fresh tokens.
• 422 commerce_definition_feature_unavailable with escaped paths; no partial authoring writes.

Generate experiment with AI

/experiments/generate

Uses AI to generate an experiment configuration based on a store URL and prompt.

Request body

{
  store_url: string (uri)
  prompt: string
  primary_goal_id?: string (uuid) | null
  goal_ids?: string (uuid)[]
  traffic_allocation?: number = 1
  targeting?: ExperimentTargeting | null
  screenshot_devices?: string[]
  expectedCommerceRevision?: integer | null
  expectedArtifactHash?: string
  definition?: object
}

Responses

• 201 AI-generated experiment created
• 400 Validation error
• 409 commerce_definition_revision_conflict, artifact_hash_conflict, commerce_definition_legacy_readonly, or workspace/file conflict. No automatic retry with fresh tokens.
• 422 commerce_definition_feature_unavailable with escaped paths; no partial authoring writes.

Replay experiment lifecycle events

/experiment-events

Returns sequenced events for the API key's shop. Positions are gap-tolerant opaque decimal cursors that strictly increase in exposure order. When no further event matches, next_after jumps to the newest committed position so filtered polls do not rescan.

Parameters

• after in query
• limit in query
• types in query - Comma-separated event types

Responses

• 200 An ordered page of experiment lifecycle events

Read the stored commerce definition

/experiments/{id}/commerce

Parameters

• id in path required - Experiment UUID or public ID / test key

Responses

• 200 Canonical definition or stored legacy envelope, with compile output
• 401
• 403
• 404 Experiment not found in this API key's shop, or it has no commerce definition
• 429
• 503

Compile and save the canonical commerce definition

/experiments/{id}/commerce

Parameters

• id in path required - Experiment UUID or public ID / test key

Request body

{
  definition: CommerceDefinition
  expectedRevision: integer | null
}

Responses

• 200 Definition saved
• 400
• 401
• 403
• 404 Experiment not found in this API key's shop
• 409 commerce_definition_revision_conflict, commerce_definition_legacy_readonly, commerce_definition_running_price_locked, artifact_status_conflict (a completed test, or a running or paused shipping test), artifact_hash_conflict, experiment_archived, variation_archived, variation_not_found, or commerce_price_variant_relationship. Stale or changed generic save inputs, including missing, forged, or expired prepared evidence, yield commerce_definition_revision_conflict with error.details.retriable=true and no violations, whether or not a priceFloor exists. Carrier refusals list every blocking issue in error.details.blockingIssues. Floor-specific refusals use commerce_price_below_floor for evaluation or unavailable evidence: retriable true for unreadable costs when a margin is enforced or belowCost is block (even without a margin and under either missingCost policy), or solely unavailable target membership (truthful placeholder violations), false for any definitive violation including undefined known-cost margin at conservative bound zero. The shared refusal schema also permits the launch diagnostic for unreadable saved-definition JSON with the same code, empty violations and retriable true; this does not make malformed PUT bodies valid or identify an evaluated below-floor variant. Acknowledgement cannot bypass either refusal. Floor lives only in definition; defaults missingCost=block, belowCost=warn apply at evaluation when omitted, with no thresholds.
• 422 Compile refusals: commerce_definition_feature_unavailable, commerce_definition_price_invalid, commerce_definition_price_variants_unresolved, commerce_definition_variations_mismatch, commerce_definition_shipping_scopes_invalid (one to ten disjoint scopes and at most one default), commerce_definition_shipping_market_unresolved (market must resolve completely to active region countries), commerce_definition_shipping_rules_invalid (shipping rules need strictly ascending subtotals and free shipping only as the last rule; up to five rules per scope). Numeric and GID variant aliases resolve to the same variant; duplicate canonical overrides or scope ids refuse with commerce_definition_price_invalid. Unknown override or scope variants refuse with commerce_definition_price_variants_unresolved naming the variant. Inactive variants are listed in serverOwned.excludedVariants and missing included products in serverOwned.excludedProducts with reason not_found. Selection resolution refuses empty_selection, invalid_product_id, invalid_collection_id, installation_unavailable, catalog_scopes_missing, catalog_page_read_failed, catalog_page_incomplete, variant_page_incomplete, collection_membership_unresolved, variant_relationships_unresolved, invalid_variant_money, currency_mismatch, selection_resolution_failed, or a selection that prices no variants. commerce_definition_feature_unavailable also refuses selections over the 100-variant cap until #9033. When the artifact gate refuses a derived carrier, error.code is its first blocking code and error.details.blockingIssues lists all blocking issues.
• 429
• 503

Export effective selection prices as CSV

/experiments/{id}/commerce/price/csv

Parameters

• id in path required

Responses

• 200 JSON envelope with RFC 4180 CSV text, definition revision, and text/csv; charset=utf-8 contentType. Informational columns product_id,variant_id,sku,product_title,variant_title,base_price followed by editable price version slugs in versions.order. Read-only candidate price columns follow editable columns. Informational <slug>__floor_status columns follow all price columns in versions.order and are ignored on import. Read-only percentage price cells are blank without an authored price and make no selling-price claim. Exact amount-off and authored prices remain unchanged. Failed cost reads retain missing_cost diagnostics.
• 401
• 403
• 404 Experiment or definition not found in this shop; commerce_price_table_unavailable when there is no sold-item pricing projection
• 409 commerce_price_table_unavailable for legacy or unresolved definitions
• 422 commerce_definition_price_invalid, commerce_definition_price_variants_unresolved
• 429
• 500 Unexpected server error
• 503

Import price overrides from CSV

/experiments/{id}/commerce/price/csv

Parameters

• id in path required
• If-Match in header required - Quoted expected definition revision

Responses

• 200 Import result; unchanged definitions are not written
• 400 commerce_price_csv_revision_invalid: If-Match is not a quoted positive integer
• 401
• 403
• 404 Experiment or definition not found in this shop; commerce_price_table_unavailable when there is no sold-item pricing projection
• 409 commerce_definition_revision_conflict, commerce_definition_legacy_readonly, commerce_definition_running_price_locked, artifact_status_conflict (a completed test, or a running or paused shipping test), artifact_hash_conflict, experiment_archived, variation_archived, variation_not_found, or commerce_price_variant_relationship. Stale or changed generic save inputs, including missing, forged, or expired prepared evidence, yield commerce_definition_revision_conflict with error.details.retriable=true and no violations, whether or not a priceFloor exists. Carrier refusals list every blocking issue in error.details.blockingIssues. Floor-specific refusals use commerce_price_below_floor for evaluation or unavailable evidence: retriable true for unreadable costs when a margin is enforced or belowCost is block (even without a margin and under either missingCost policy), or solely unavailable target membership (truthful placeholder violations), false for any definitive violation including undefined known-cost margin at conservative bound zero. The shared refusal schema also permits the launch diagnostic for unreadable saved-definition JSON with the same code, empty violations and retriable true; this does not make malformed PUT bodies valid or identify an evaluated below-floor variant. Acknowledgement cannot bypass either refusal. Floor lives only in definition; defaults missingCost=block, belowCost=warn apply at evaluation when omitted, with no thresholds.; commerce_price_table_unavailable
• 413 commerce_price_csv_too_large: body exceeds 2 MB
• 415 commerce_price_csv_content_type_invalid: Content-Type must be text/csv
• 422 Compile refusals: commerce_definition_feature_unavailable, commerce_definition_price_invalid, commerce_definition_price_variants_unresolved, commerce_definition_variations_mismatch, commerce_definition_shipping_scopes_invalid (one to ten disjoint scopes and at most one default), commerce_definition_shipping_market_unresolved (market must resolve completely to active region countries), commerce_definition_shipping_rules_invalid (shipping rules need strictly ascending subtotals and free shipping only as the last rule; up to five rules per scope). Numeric and GID variant aliases resolve to the same variant; duplicate canonical overrides or scope ids refuse with commerce_definition_price_invalid. Unknown override or scope variants refuse with commerce_definition_price_variants_unresolved naming the variant. Inactive variants are listed in serverOwned.excludedVariants and missing included products in serverOwned.excludedProducts with reason not_found. Selection resolution refuses empty_selection, invalid_product_id, invalid_collection_id, installation_unavailable, catalog_scopes_missing, catalog_page_read_failed, catalog_page_incomplete, variant_page_incomplete, collection_membership_unresolved, variant_relationships_unresolved, invalid_variant_money, currency_mismatch, selection_resolution_failed, or a selection that prices no variants. commerce_definition_feature_unavailable also refuses selections over the 100-variant cap until #9033. When the artifact gate refuses a derived carrier, error.code is its first blocking code and error.details.blockingIssues lists all blocking issues.; commerce_price_csv_header_mismatch, commerce_price_csv_unknown_variant, commerce_price_csv_duplicate_variant, commerce_price_csv_invalid. Invalid money uses commerce_definition_price_invalid with error.details.line and column. Unknown variants carry line.
• 428 commerce_price_csv_revision_required: If-Match is required
• 429
• 500 Unexpected server error
• 503

Read grouped effective price rows

/experiments/{id}/commerce/price/rows

Parameters

• id in path required
• group in query
• limit in query - Number of groups
• cursor in query - Opaque cursor from the preceding page

Responses

• 200 Groups sorted by label then key. Collection grouping includes only selected collections. Read-only amount-off and offer cells include discount sources. Every evaluated cell includes floor diagnostics before pagination; failed cost reads retain exact prices and missing_cost reasons, without inventing verified costs.
• 400 commerce_price_rows_query_invalid: invalid grouping, limit or cursor
• 401
• 403
• 404 Experiment or definition not found in this shop; commerce_price_table_unavailable when there is no sold-item pricing projection
• 409 commerce_price_table_unavailable for legacy or unresolved definitions
• 422 commerce_definition_price_invalid, commerce_definition_price_variants_unresolved
• 429
• 500 Unexpected server error
• 503

Read experiment launch readiness

/experiments/{id}/readiness

Read-only checklist and human launch handoff. Requires experiments:read on shop keys or shops:read on user keys. Does not create QA runs, approve QA, or launch. Screenshot URLs are signed from the latest persisted QA run. The checkout item reports checkout-message warnings and live confirmation for launchable or running checkout tests.

Parameters

• id in path required - Experiment UUID or public ID
• variation_id in query - Select a live variation by UUID, public ID or slug for the signed preview.
• target_url in query - Signed preview destination on the experiment's allowed store origin.

Responses

• 200 Readiness checklist
• 401 Invalid or missing API key
• 403 Read scope or shop access required
• 404 Experiment not found in this shop
• 429 Rate limit exceeded
• 503 Rate-limit backend unavailable

Read return on ad spend per experiment variant

/experiments/{id}/results/ad-roas

Current-run Meta ad-arrived visitors and shop-currency matched revenue, with spend allocated by each ad-hour's share of all matching traffic. Variant spend reconciles within a test; overlapping tests are not additive. Revenue per ad visitor includes non-buyers as zeros, with Welch intervals and differences from original. ROAS has no significance claim and is never a decision basis. Missing FX, truncation and read failures never become measured zeros.

Parameters

• id in path required

Responses

• 200 Ad ROAS read-out or explicit unknown state
• 401
• 403
• 404
• 429
• 503

Read experiment money by arrival channel

/experiments/{id}/results/by-channel

Current-run snapshot through as_of, pinned to a published copy generation. Identified money uses all exposed visitors, including non-buyers as zeros. Matched money plus identified unmatched and identity-free residuals equals the headline recomputed through that cutoff. Unavailable and degraded never carry zero-filled money. Channel comparisons suggest follow-up tests, never winners. Unknown includes missing consent and pre-tracking exposures. Updates hourly.

Parameters

• id in path required

Responses

• 200 Snapshot or explicit unavailable/degraded state
• 401
• 403
• 404
• 429
• 503

Create a personal managed-client join link

/admin/client-links

Requires a user API key with admin:write. Uses the same validation, sellable-plan, consultant, referral and conflict rules as Admin > Links. It creates the link but does not send email.

Request body

{
  kind: "invite"
  plan: "self_managed" | "apex_managed" | "drip_managed"
  client_name: string
  client_type: "company" | "agency"
  email: string (email)
  consultant_user_id?: string (uuid) | null
  consultant_title?: string | null
  payment?: "card" | "invoice"
  discount_pct?: integer | null
  discount_months?: integer | null
  free_days?: integer
  store_url?: string (uri) | null
  expires_at?: string | null
  internal_note?: string | null
  teammates?: object[]
}

Responses

• 201 Created link and join URL
• 400
• 401
• 403
• 409
• 429
• 503

Create an engineering account

/admin/customers

Requires a user API key with admin:write and a live platform role with onboarding:write. Customer accounts are refused with use_client_link; create them with POST /api/v1/admin/client-links (apex admin clients create) or Admin, Links. A claimed store also requires admin:write. Every creation records the reason in the audit.

Request body

{
  name: string
  type: "company" | "agency"
  category: "internal" | "demo" | "dogfood"
  plan: "self_managed" | "apex_managed" | "drip_managed"
  store?: any
  ownerEmail?: string (email)
  teammates: object[]
  consultant?: any
  reason: string
}

Responses

• 201 Created, including any invitation delivery failures
• 400 Invalid request, consultant_required or use_client_link
• 401 Missing, expired or revoked user API key
• 402 First store requires checkout; no account retained
• 403 Missing key scope or live platform permission
• 409 Name, domain, store claim or owner conflict
• 429 Rate limit exceeded
• 503 Audit, provisioning or owner identity verification unavailable

Change an account category, managing agency or workspace type

/admin/customers/{orgId}

Requires a user API key with admin:write. Moves an existing organization between the customer, internal, demo and dogfood categories through the audited customer change path; the reason is recorded in the audit. Managing agency and workspace type changes require platform admin access. Only active, unmanaged agency organizations can manage a customer; self-management and chains are refused. Workspace type changes refuse archived organizations and unchanged values; becoming an agency requires no active stores or managing agency, and becoming a company requires unlinking every managed organization. A competing customer change answers 409.

Request body

any

Responses

• 200 Category, managing agency or workspace type changed
• 400 Invalid organization id, category, workspace type or reason; a managed organization cannot become an agency (managed)
• 401 Missing, expired or revoked user API key
• 403 Missing key scope or live platform permission
• 404 Customer not found
• 409 Customer changed before the write; refresh and retry. Workspace type conflicts: unchanged, stores_present, manages_organizations or archived
• 429 Rate limit exceeded
• 503 Audit could not be recorded

Preview or move a set of stores to a customer

/admin/customers/{orgId}/move-stores

Requires admin:write on a user API key and the live apex-platform-admin role. dry_run returns the before/after access plan without moving stores or writing move audits. Confirmation uses the audited store-set chokepoint; keep_grants preserves explicit roles and overrides.

Request body

{
  shop_ids: string (uuid)[]
  reason: string
  keep_grants?: boolean = false
  dry_run?: boolean = false
}

Responses

• 200 Plan or completed move: shops, brands, scope counts, programs, entitlement change, kept/removed grants and auditIds
• 400 Invalid store ids or reason
• 401 Invalid user API key
• 403 Platform admin required
• 404 Store or destination not found
• 409 Brand split or concurrent move conflict
• 429 Rate limit exceeded
• 503 Audit unavailable

Read a customer's setup checklist

/admin/customers/{orgId}/setup

Requires admin:read on a user API key. Each item says whether it is done, open, waiting on the client, optional or unknown, and names its fix. A Research Hub read failure is reported in degraded, never as done (#9232).

Responses

• 200 Setup checklist
• 400 Invalid customer id
• 401 Invalid user API key
• 403 admin:read required
• 404 Customer not found
• 429 Rate limit exceeded
• 503 Database busy

Apply one setup checklist fix

/admin/customers/{orgId}/setup

Requires admin:write on a user API key. Runs the existing audited writer for the fix with that writer's own permission check, then returns the fresh checklist (#9232).

Request body

{
  fix: "rename" | "set_plan" | "set_managed_by" | "set_consultant" | "enable_switch" | "resend_owner_invite" | "invite_owner" | "retry_teammates" | "link_research_hub" | "apply_plan_switches"
  shopId?: string (uuid)
  input?: any
  reason: string
}

Responses

• 200 Updated setup checklist
• 400 Invalid fix, input or reason
• 401 Invalid user API key
• 403 Permission for this fix required
• 404 Customer, store or invitation not found
• 409 The fix conflicts with the current state (owner_exists, owner_invitation_pending, research_hub_already_linked, research_hub_link_changed)
• 429 Rate limit exceeded
• 503 Audit unavailable

Read an organization’s monthly unique visitors

/admin/customers/{orgId}/unique-visitors

Each consented web visitor ID that loads at least one page with an active Apex script counts once per shop and calendar month in the shop’s analytics timezone (report timezone, then Shopify installation timezone, then UTC); detected bots, crawlers, preview, QA, non-production traffic and anonymous sentinel identities are excluded. Platform user key with admin:read scope and platform billing:read permission required. Includes archived shops, ordered by name. Failed shop reads have null counts and a null organization total. A month that has not started or is past the 365-day retention answers 400; a shop whose own timezone has not reached the month reads month_not_counted.

Parameters

• orgId in path required
• month in query required

Responses

• 200 All organization shops for one month
• 400 Invalid month or range
• 401
• 403
• 404 Organization not found
• 429
• 503 Analytics or shop timezone temporarily unavailable; never reported as zero

Archive a shop

/admin/shops/{id}/archive

Requires an admin:write user API key and refuses shops with running, non-archived experiments.

Responses

• 200 Shop archived and delivery disabled
• 401
• 403
• 404 Shop not found (pass-through orchestration body)
• 409 Shop has running, non-archived experiments
• 429
• 503 Archival persisted but snippet republication pending, or publication lock contention — retriable

Read every registered per-shop setting

/admin/shops/{id}/settings

Requires an admin:read platform user API key. Exact domain matching is case-insensitive; archived shops remain resolvable. Returns registry metadata and nullable override state for every registered key.

Responses

• 200 Shop identity and registered settings
• 401
• 403
• 404 Shop not found
• 409 Ambiguous domain; pass a shop UUID
• 429
• 503

Write a registered per-shop setting

/admin/shops/{id}/settings

Requires an admin:write platform user API key plus the registry's per-key adminWrite permission. Uses the audited shop-settings writer; keys owned by other write paths are refused. Resolve a domain with GET first, then pin the resolved UUID with x-apex-shop. Does not return a settings snapshot.

Parameters

• x-apex-shop in header required - Must equal the resolved shop UUID, including when id is a domain

Request body

{
  key: string
  value: boolean | string | number | null
  reason?: string
  expectedVersion?: string | null
}

Responses

• 200 Audited write persisted; precompile reports publication outcome when applicable
• 400 Invalid payload or missing/mismatched x-apex-shop pin; validation issues appear at error.details.issues
• 401
• 403 Platform permission or registry per-key write permission refused
• 404 Shop not found
• 409 Stale expectedVersion or ambiguous domain (error.details.candidates lists shop UUIDs); use a shop UUID
• 429
• 503 Required audit could not be recorded or database temporarily unavailable

Restore an archived shop

/admin/shops/{id}/restore

Requires an admin:write user API key. Delivery remains controlled by the shop runtime kill switch.

Responses

• 200 Shop restored
• 401
• 403
• 404 Shop not found (pass-through orchestration body)
• 429
• 503

List tracking quarantine events

/admin/tracking/quarantine

Read-only platform view requiring a live PlatformAccess row.

Parameters

• shopId in query
• reasonCode in query
• verdict in query
• limit in query

Responses

• 200 Quarantine rows
• 401
• 403
• 429
• 503

Read staff tracking health

/admin/shops/{id}/tracking-health

Returns tracking health for one shop with staff-only causes for unlinked orders.

Responses

• 200 Staff per-shop tracking health
• 401
• 403
• 404
• 429
• 503

Get the current user's profile

/account/profile

Responses

• 200 Account profile
• 401
• 403
• 429
• 503

Update the current user's profile

/account/profile

Request body

{
  displayName?: string
  avatarDataUrl?: string | null
  themePreference?: "system" | "dark" | "light"
}

Responses

• 200 Updated account profile
• 400
• 401
• 403
• 429
• 503

Read the presented key's shop identity

/key

Any valid shop key can read its own identity without a resource scope. Shop context headers and query parameters do not change its shop. User keys return kind user and shop_id null without resolving shop context. MCP user credentials continue to resolve their bound shop through /keys/self/shop.

Responses

• 200 Key identity
• 401
• 403 Key or shop access is denied
• 429
• 503 Rate limiting backend unavailable

Read the connector's bound shop

/keys/self/shop

User keys only, shops:write. Returns the existing bound shop's domain and platform without requiring shops:read. Organization and live shop authorization are checked; unbound keys return 400.

Responses

• 200 Connector's bound shop
• 400
• 401
• 403
• 404
• 429
• 503

Bind the connector to a shop

/keys/self/shop

User keys only, shops:write. Bind an unbound key once to an authorized shop in its organization; a concurrent or subsequent binding returns 409. Binding and required audit are atomic.

Request body

{
  shop_id: string (uuid)
}

Responses

• 200 Connector bound
• 400
• 401
• 403
• 404
• 409
• 429
• 503

List a shop's API keys

/keys

Parameters

• shop_id in query required

Responses

• 200 API key metadata; hashes and secrets are never included
• 400
• 403
• 404
• 429
• 503

Create a shop API key

/keys

Request body

{
  shop_id: string (uuid)
  name: string
  type: "live_secret" | "test_secret" | "publishable"
  permissions?: string[]
  rate_limit?: integer
  expires_at?: string (date-time) | null
}

Responses

• 201 Created key, including its secret exactly once
• 400
• 403
• 404
• 429
• 503

Revoke a shop API key

/keys/{id}

Parameters

• id in path required
• shop_id in query required

Responses

• 200 Revoked
• 400
• 403
• 404
• 429
• 503

Read cross-domain identity handover settings

/external-tracking

Responses

• 200 External tracking settings
• 401
• 403
• 429
• 503

Update cross-domain identity handover settings

/external-tracking

Request body

{
  externalTracking?: object
  ifRevision?: string (date-time) | null
}

Responses

• 200 Updated handover settings and edge precompile outcome
• 400
• 401
• 403
• 409
• 429
• 503

Generate variation with AI

/experiments/{id}/variations/generate

Uses AI to generate a new variation for an existing experiment.

Parameters

• id in path required - Experiment ID

Request body

{
  prompt: string
  expectedCommerceRevision?: integer | null
  expectedArtifactHash?: string
  definition?: object
}

Responses

• 201 AI-generated variation created
• 400 Validation error
• 404 Experiment not found
• 409 commerce_definition_revision_conflict, artifact_hash_conflict, commerce_definition_legacy_readonly, or workspace/file conflict. No automatic retry with fresh tokens.
• 422 commerce_definition_feature_unavailable with escaped paths; no partial authoring writes.

Create variation

/variations

Creates a new variation for a draft experiment. Requires experiment_id in the body.

Request body

{
  experiment_id: string (uuid) | string
  name: string
  weight: number
  is_control?: boolean = false
  redirect_url?: string (uri) | null
  mutations?: Mutation[]
  url_blocks?: UrlBlocks
  custom_css?: string | null
  custom_js?: string | null
  expectedCommerceRevision?: integer | null
}

Responses

• 201 Variation created
• 400 Validation error or experiment not in draft status
• 404 Experiment not found
• 409 commerce_definition_revision_conflict, artifact_hash_conflict, commerce_definition_legacy_readonly, or workspace/file conflict. No automatic retry with fresh tokens.
• 422 commerce_definition_feature_unavailable with escaped paths; no partial authoring writes.

Get variation

/variations/{id}

Returns a single variation by ID.

Parameters

• id in path required

Responses

• 200 Variation details
• 403 Not authorized to access this variation
• 404 Variation not found

Update variation

/variations/{id}

Partially updates a variation. Treatment artifacts (mutations, URL blocks, and custom CSS/JavaScript) can change while the experiment is draft, paused, or running. Running artifact writes republish the storefront configuration. Other variation fields remain draft-only. Cannot update is_control.

Parameters

• id in path required

Request body

{
  name?: string
  weight?: number
  redirect_url?: string (uri) | null
  expected_prior_redirect_url?: string (uri) | null
  mutations?: Mutation[]
  url_blocks?: UrlBlocks
  custom_css?: string | null
  custom_js?: string | null
  expectedCommerceRevision?: integer | null
  expectedArtifactHash?: string
  definition?: object
}

Responses

• 200 Variation updated
• 400 The write was rejected, or treatment artifacts committed before a later publication step reported a failure
• 403 Not authorized
• 404 Variation not found
• 409 Treatment artifacts cannot change after the experiment finishes, the redirect destination changed since it was read, the experiment is no longer editable, or a price-test mutation targets a subscription-priced or bundle-component variant commerce_definition_revision_conflict, artifact_hash_conflict, commerce_definition_legacy_readonly, or workspace/file conflict. No automatic retry with fresh tokens.
• 422 commerce_definition_feature_unavailable with escaped paths; no partial authoring writes.
• 502 The running treatment artifact was saved, but storefront publication failed

Archive variation

/variations/{id}

Archives a non-control variation from a draft experiment. Minimum 2 active variations must remain, and remaining active weights are redistributed.

Parameters

• id in path required

Request body

{
  expectedCommerceRevision?: integer | null
}

Responses

• 200 Variation archived
• 400 Cannot delete control, non-draft experiment, or last two variations
• 403 Not authorized
• 404 Variation not found
• 409 commerce_definition_revision_conflict, artifact_hash_conflict, commerce_definition_legacy_readonly, or workspace/file conflict. No automatic retry with fresh tokens.
• 422 commerce_definition_feature_unavailable with escaped paths; no partial authoring writes.

Restore variation

/variations/{id}/restore

Restores an archived variation and redistributes all active variation weights.

Parameters

• id in path required

Request body

{
  expectedCommerceRevision?: integer | null
}

Responses

• 200 Variation restored
• 404 Variation not found
• 409 Variation is already active or changed concurrently commerce_definition_revision_conflict, artifact_hash_conflict, commerce_definition_legacy_readonly, or workspace/file conflict. No automatic retry with fresh tokens.
• 422 commerce_definition_feature_unavailable with escaped paths; no partial authoring writes.

Read variation workspace

/experiments/{id}/variations/{variationId}/workspace

Returns the canonical Apex workspace for an exact experiment variation. Used by `apex workspace checkout`.

Parameters

• id in path required - Experiment ID
• variationId in path required - Variation ID

Responses

• 200 Canonical workspace payload
• 401 Unauthorized
• 403 Not authorized to access this variation
• 404 Experiment variation workspace not found
• 429 Rate limit exceeded
• 503

List variation workspace files

/experiments/{id}/variations/{variationId}/files

Lists canonical workspace files for an exact experiment variation.

Parameters

• id in path required
• variationId in path required

Responses

• 200 Workspace files
• 401 Unauthorized
• 403 Not authorized to access this variation
• 404 Experiment variation workspace not found
• 429 Rate limit exceeded
• 503

Read variation workspace file

/experiments/{id}/variations/{variationId}/files/{path}

Reads one canonical workspace file. URL-encode the file path, for example src%2Findex.js.

Parameters

• id in path required
• variationId in path required
• path in path required - Canonical workspace path, URL-encoded. Supported roots: src, goals, segments, network, metrics.json, targeting.json, experiment.config.json, dev-doc.md.

Responses

• 200 Workspace file
• 401 Unauthorized
• 403 Not authorized to access this variation
• 404 Workspace file not found
• 429 Rate limit exceeded
• 503

Write variation workspace file

/experiments/{id}/variations/{variationId}/files/{path}

Writes one canonical workspace file and records a workspace revision. Supply expected_version from the current file sha256 to reject a concurrent edit.

Parameters

• id in path required
• variationId in path required
• path in path required - Canonical workspace path, URL-encoded. Supported roots: src, goals, segments, network, metrics.json, targeting.json, experiment.config.json, dev-doc.md.

Request body

{
  content: string
  source?: "manual" | "operator" | "build" | "system" = "operator"
  title?: string
  expected_version?: string
}

Responses

• 200 Workspace file write result
• 400 Validation error or unsupported workspace path
• 401 Unauthorized
• 403 Not authorized to edit this variation
• 404 Experiment variation workspace not found
• 409 The workspace file changed or no longer exists
• 429 Rate limit exceeded
• 503

Build variation workspace

/experiments/{id}/variations/{variationId}/build

Projects canonical workspace files into Apex runtime state: mutations, CSS, JS, targeting, goals, and segments.

Parameters

• id in path required
• variationId in path required

Request body

{
  mode?: "full" | "validate_only" = "full"
  allowGoalWrites?: boolean = false
  expectedCommerceRevision?: integer | null
  expectedArtifactHash?: string
  definition?: object
  expectedWorkspaceRevision?: string
  expectedFileVersions?: object
}

Responses

• 200 Workspace build succeeded
• 400 Workspace build failed
• 401 Unauthorized
• 403 Not authorized to edit this variation
• 404 Experiment variation workspace not found
• 409 Workspace build conflicted with a concurrent artifact save commerce_definition_revision_conflict, artifact_hash_conflict, commerce_definition_legacy_readonly, or workspace/file conflict. No automatic retry with fresh tokens.
• 422 commerce_definition_feature_unavailable with escaped paths; no partial authoring writes.
• 429 Rate limit exceeded
• 503

List variation workspace revisions

/experiments/{id}/variations/{variationId}/revisions

Lists recent workspace revisions for an exact experiment variation.

Parameters

• id in path required
• variationId in path required

Responses

• 200 Workspace revisions
• 401 Unauthorized
• 403 Not authorized to access this variation
• 404 Experiment variation workspace not found
• 429 Rate limit exceeded
• 503

Test URL targeting

/targeting/test

Evaluates the API key shop's experiment targeting rules against one URL and returns all matching experiments for parallel-experiment awareness.

Parameters

• url in query required
• status in query - Comma-separated statuses or all. Defaults to draft,qa,running,paused.

Responses

• 200 Targeting evaluation
• 400 Invalid URL
• 401 Unauthorized
• 403 API key is missing experiment read permission
• 429 Rate limit exceeded
• 503

Publish harness session

/harness/sessions/{id}/publish

Publishes reviewed harness artifacts to the session variation.

Parameters

• id in path required

Responses

• 200 Harness session published
• 400 Missing JavaScript artifact or artifact review blocked publish
• 404 Harness session not found
• 409 Artifact conflict or experiment is not in draft status

Create screenshot job

/experiments/{id}/screenshots

Queues a screenshot capture job for the specified variations and devices.