@shipeasy/openapi 1.6.0 → 2.2.0

package/spec/paths/experiments.yaml

@@ -0,0 +1,803 @@
+/api/admin/experiments:
+  get:
+    operationId: listExperiments
+    summary: List experiments
+    description: |-
+      Returns a single page of non-archived experiments ordered by `updated_at desc, id desc`. Use the `cursor` query parameter to paginate.
+
+      **Use case:** Snapshot every active experiment in the project — e.g. render an overview dashboard or drive a CI check that no experiment has been running past its `min_runtime_days`.
+    tags:
+      - Experiments
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - $ref: ../components/parameters.yaml#/PaginationLimit
+      - $ref: ../components/parameters.yaml#/PaginationCursor
+      - name: status
+        in: query
+        required: false
+        description: Filter by lifecycle status. Pass `archived` to return the archive tab; any other value (or omitting it) returns the non-archived experiments.
+        schema:
+          type: string
+      - $ref: ../components/parameters.yaml#/Q
+    responses:
+      "200":
+        description: List experiments
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/experiments.yaml#/ListExperimentsResponse
+            example:
+              data:
+                - id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
+                  name: checkout_button_color
+                  description: Test green vs. blue CTA on the checkout page.
+                  tag: checkout
+                  status: running
+                  universe: primary_users
+                  targetingGate: null
+                  allocationPct: 5000
+                  salt: 8d3e9a1f6b7c4a5fa1c2b6d3e7c8e3a1
+                  params:
+                    cta_color: string
+                  groups:
+                    - name: control
+                      weight: 5000
+                      params:
+                        cta_color: blue
+                    - name: treatment
+                      weight: 5000
+                      params:
+                        cta_color: green
+                  significanceThreshold: 0.05
+                  minRuntimeDays: 7
+                  minSampleSize: 1000
+                  sequentialTesting: false
+                  startedAt: 2026-05-01T12:00:00.000Z
+                  stoppedAt: null
+                  updatedAt: 2026-05-09T18:22:11.000Z
+              next_cursor: null
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+    x-cli:
+      name: list
+  post:
+    operationId: createExperiment
+    summary: Create an experiment
+    description: |-
+      Creates a new experiment in `draft` status. `name`, `universe`, and `groups` are required; everything else has sensible defaults.
+
+      Returns `409` if `name` already exists, `422` if the named universe doesn't exist, `403` if a plan-gated option is set (`sequential_testing`, custom `significance_threshold`) on a plan that doesn't include it.
+
+      **Use cases**
+
+      - **Minimal 50/50** — `name` + `universe` + two equal-weight groups.
+      - **Targeted rollout** — supply `targeting_gate` to restrict the eligible audience and `allocation_pct` to enrol a slice of it.
+      - **Multivariant** — three or more groups with weights summing to 10000.
+      - **Sequential testing** — `sequential_testing: true` for Premium plans.
+    tags:
+      - Experiments
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/experiments.yaml#/CreateExperimentRequest
+          examples:
+            minimal:
+              summary: Minimal — two-group 50/50
+              description: Smallest valid body. Two groups at 50/50, no allocation, no targeting.
+              value:
+                name: checkout_button_color
+                universe: primary_users
+                groups:
+                  - name: control
+                    weight: 5000
+                  - name: treatment
+                    weight: 5000
+            targeted:
+              summary: Targeted — gate + allocation + params
+              description: Gate the audience with a `targeting_gate`, allocate 50% of it, and parameterise the variants.
+              value:
+                name: checkout_button_color
+                description: Green CTA on checkout for Pro users.
+                universe: primary_users
+                targeting_gate: pro_plan_only
+                allocation_pct: 5000
+                params:
+                  cta_color: string
+                groups:
+                  - name: control
+                    weight: 5000
+                    params:
+                      cta_color: blue
+                  - name: treatment
+                    weight: 5000
+                    params:
+                      cta_color: green
+            multivariant:
+              summary: Multivariant — three groups
+              description: Three variants splitting 40/30/30. Requires the sum to equal 10000.
+              value:
+                name: headline_test
+                universe: primary_users
+                groups:
+                  - name: control
+                    weight: 4000
+                  - name: alt_a
+                    weight: 3000
+                  - name: alt_b
+                    weight: 3000
+            sequential:
+              summary: Sequential testing — Premium plan
+              description: Enable always-valid sequential tests. Requires Premium plan or higher.
+              value:
+                name: checkout_button_color
+                universe: primary_users
+                groups:
+                  - name: control
+                    weight: 5000
+                  - name: treatment
+                    weight: 5000
+                sequential_testing: true
+                min_runtime_days: 14
+    responses:
+      "201":
+        description: Create an experiment
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/experiments.yaml#/CreateExperimentResponse
+            example:
+              id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
+              name: checkout_button_color
+        links:
+          GetExperiment:
+            operationId: getExperiment
+            parameters: { id: $response.body#/id }
+          UpdateExperiment:
+            operationId: updateExperiment
+            parameters: { id: $response.body#/id }
+          SetExperimentMetrics:
+            operationId: setExperimentMetrics
+            parameters: { id: $response.body#/id }
+          SetExperimentStatus:
+            operationId: setExperimentStatus
+            parameters: { id: $response.body#/id }
+          ReanalyzeExperiment:
+            operationId: reanalyzeExperiment
+            parameters: { id: $response.body#/id }
+          DeleteExperiment:
+            operationId: deleteExperiment
+            parameters: { id: $response.body#/id }
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - PLAN_REQUIRED
+      - ALREADY_EXISTS
+      - GROUPS_WEIGHT_SUM
+      - REFERENCED_NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: create
+      positional:
+        - name
+/api/admin/experiments/{id}:
+  get:
+    operationId: getExperiment
+    summary: Get one experiment
+    description: |-
+      Returns the full experiment row including groups, params, allocation, and lifecycle timestamps.
+
+      **Use case:** Fetch one experiment to render the detail page or to inspect its current allocation and group weights.
+    tags:
+      - Experiments
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Get one experiment
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/experiments.yaml#/GetExperimentResponse
+            example:
+              id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
+              name: checkout_button_color
+              description: Test green vs. blue CTA on the checkout page.
+              tag: checkout
+              status: running
+              universe: primary_users
+              targetingGate: null
+              allocationPct: 5000
+              salt: 8d3e9a1f6b7c4a5fa1c2b6d3e7c8e3a1
+              params:
+                cta_color: string
+              groups:
+                - name: control
+                  weight: 5000
+                  params:
+                    cta_color: blue
+                - name: treatment
+                  weight: 5000
+                  params:
+                    cta_color: green
+              significanceThreshold: 0.05
+              minRuntimeDays: 7
+              minSampleSize: 1000
+              sequentialTesting: false
+              startedAt: 2026-05-01T12:00:00.000Z
+              stoppedAt: null
+              updatedAt: 2026-05-09T18:22:11.000Z
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: get
+      positional:
+        - id
+  patch:
+    operationId: updateExperiment
+    summary: Update an experiment
+    description: |-
+      Partial update. `allocation_pct`, `groups`, `salt`, `universe`, `params` are **immutable while running** — returns `409` if you try. Stop the experiment first.
+
+      Editing `groups` while in `draft` is fine; weights must still sum to 10000.
+
+      **Use cases**
+
+      - **Update metadata** — `description`, `tag`, `targeting_gate` editable any time.
+      - **Ramp before launch** — set `allocation_pct` while still in `draft`.
+      - **Tighten significance** — `significance_threshold` (Pro+).
+      - **Rewire groups** — replace `groups` wholesale while in `draft`; immutable once running.
+    tags:
+      - Experiments
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/experiments.yaml#/UpdateExperimentRequest
+          examples:
+            rampAllocation:
+              summary: Ramp allocation — 0 → 50%
+              description: Bumps the share of the targeted audience enrolled. Allowed only when the experiment is in `draft`.
+              value:
+                allocation_pct: 5000
+            changeWeights:
+              summary: Change group weights
+              description: Replace the groups array — weights must still sum to 10000.
+              value:
+                groups:
+                  - name: control
+                    weight: 2500
+                  - name: treatment
+                    weight: 7500
+            tighterSignificance:
+              summary: Tighter significance threshold
+              description: Drop the p-value cutoff from 0.05 → 0.01. Requires Pro plan or higher.
+              value:
+                significance_threshold: 0.01
+            updateMetadata:
+              summary: Update metadata
+              description: Change description/tag/targeting_gate freely on running experiments.
+              value:
+                description: Bumped to 50% after passing canary on 25%.
+                tag: checkout
+    responses:
+      "200":
+        description: Update an experiment
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/experiments.yaml#/UpdateExperimentResponse
+            example:
+              id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - PLAN_REQUIRED
+      - NOT_FOUND
+      - IMMUTABLE_FIELD
+      - INVALID_TRANSITION
+      - GROUPS_WEIGHT_SUM
+      - REFERENCED_NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: update
+      positional:
+        - id
+  delete:
+    operationId: deleteExperiment
+    summary: Delete an experiment
+    description: |-
+      Archives the experiment (soft-delete via status transition). Returns `409` if the experiment is still `running` — stop it first.
+
+      **Use case:** Tear down an experiment after the analysis is signed off.
+    tags:
+      - Experiments
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Delete an experiment
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/experiments.yaml#/DeleteExperimentResponse
+            example:
+              ok: true
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - INVALID_TRANSITION
+    x-cli:
+      name: archive
+      positional:
+        - id
+/api/admin/experiments/{id}/status:
+  post:
+    operationId: setExperimentStatus
+    summary: Transition experiment status
+    description: |-
+      Drives the experiment lifecycle. Allowed transitions:
+
+      - `draft → running` — starts allocation. Bumps the `startedAt` timestamp.
+      - `running → stopped` — halts allocation. Existing exposures stay in the dataset.
+      - `stopped → archived` — soft-delete.
+      - `draft → archived` — discard an unstarted experiment.
+      - `archived → draft` — restore a soft-deleted experiment so it can be re-completed and started. Allowed only if it never started; one that already ran must be cloned instead.
+
+      Restarting an `archived` experiment directly is not allowed — restore it to `draft` first. Returns `409` on illegal transitions and `429` if the plan's `experiments_running` limit is exceeded on `→ running`.
+
+      **Use cases**
+
+      - **Start** — `{ "status": "running" }` after wiring up the SDK and verifying targeting on staging.
+      - **Stop** — `{ "status": "stopped" }` once the experiment hits its `min_runtime_days` and conclusive results land.
+      - **Archive** — `{ "status": "archived" }` to soft-delete after sign-off.
+    tags:
+      - Experiments
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/experiments.yaml#/SetExperimentStatusRequest
+          examples:
+            start:
+              summary: Start — draft → running
+              description: Begins allocation. The experiment counts against the plan's `experiments_running` limit.
+              value:
+                status: running
+            stop:
+              summary: Stop — running → stopped
+              description: Halts allocation. Existing exposures remain analysable.
+              value:
+                status: stopped
+            archive:
+              summary: Archive — stopped → archived
+              description: Soft-deletes the experiment. List endpoints exclude archived rows by default.
+              value:
+                status: archived
+            restore:
+              summary: Restore — archived → draft
+              description: Un-deletes a soft-deleted experiment so it can be re-completed and started. Allowed only if it never ran.
+              value:
+                status: draft
+    responses:
+      "200":
+        description: Transition experiment status
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/experiments.yaml#/SetExperimentStatusResponse
+            example:
+              id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
+              status: running
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - INVALID_TRANSITION
+      - VALIDATION
+    x-cli:
+      positional:
+        - id
+      commands:
+        - name: start
+          summary: Start an experiment (draft → running)
+          preset:
+            status: running
+        - name: stop
+          summary: Stop a running experiment
+          preset:
+            status: stopped
+        - name: restore
+          summary: Restore an archived experiment (→ draft)
+          preset:
+            status: draft
+/api/admin/experiments/{id}/metrics:
+  post:
+    operationId: setExperimentMetrics
+    summary: Attach metrics
+    description: |-
+      Replaces the experiment's metric attachments wholesale. Each entry pairs an existing `metric_id` with a `role` (`goal` / `guardrail` / `secondary`).
+
+      Returns `422` if any `metric_id` doesn't exist in the project. Pass `{ metrics: [] }` to detach everything.
+
+      **Use cases**
+
+      - **Standard setup** — one `goal`, one or two `guardrail`, optional `secondary` metrics for diagnostics.
+      - **Detach all** — send `{ "metrics": [] }` before archiving.
+    tags:
+      - Experiments
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/experiments.yaml#/SetExperimentMetricsRequest
+          examples:
+            standard:
+              summary: Standard — one goal + one guardrail
+              description: Attaches one decision metric and one safety metric.
+              value:
+                metrics:
+                  - metric_id: met_checkout_completed
+                    role: goal
+                  - metric_id: met_page_errors
+                    role: guardrail
+            detach:
+              summary: Detach all
+              description: Send an empty array to clear every metric.
+              value:
+                metrics: []
+    responses:
+      "200":
+        description: Attach metrics
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/experiments.yaml#/SetExperimentMetricsResponse
+            example:
+              id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
+              metrics:
+                - metric_id: met_checkout_completed
+                  role: goal
+                - metric_id: met_page_errors
+                  role: guardrail
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - EVENT_PENDING
+      - REFERENCED_NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: set-metrics
+      positional:
+        - id
+/api/admin/experiments/{id}/results:
+  get:
+    operationId: getExperimentResults
+    summary: Get analysis results
+    description: |-
+      Returns the latest analysis output for the experiment — one row per metric/group/day, including sample size, mean, % delta vs. control, p-value, and a sample-ratio mismatch flag.
+
+      **Use case:** Render the results table on the experiment detail page or drive an automated decision once a `goal` metric reaches significance.
+    tags:
+      - Experiments
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Get analysis results
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/experiments.yaml#/GetExperimentResultsResponse
+            example:
+              experiment:
+                id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
+                name: checkout_button_color
+                status: running
+              results:
+                - metric: checkout_completed
+                  group_name: control
+                  ds: 2026-05-09
+                  n: 12421
+                  mean: 0.1834
+                  delta_pct: null
+                  p_value: null
+                  srm_detected: 0
+                - metric: checkout_completed
+                  group_name: treatment
+                  ds: 2026-05-09
+                  n: 12519
+                  mean: 0.1922
+                  delta_pct: 4.8
+                  p_value: 0.018
+                  srm_detected: 0
+              verdict: ship
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: results
+      positional:
+        - id
+/api/admin/experiments/{id}/timeseries:
+  get:
+    operationId: getExperimentTimeseries
+    summary: Get analysis timeseries
+    description: |-
+      Same row shape as `/results`, but returns every daily slice rather than the latest. Filter to a single metric with the `metric` query parameter.
+
+      **Use case:** Drive a chart of metric movement over the experiment runtime, or sanity-check the lift is monotonic before deciding.
+    tags:
+      - Experiments
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+      - name: metric
+        in: query
+        required: false
+        description: Optional metric name to filter the series.
+        schema:
+          type: string
+    responses:
+      "200":
+        description: Get analysis timeseries
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/experiments.yaml#/GetExperimentTimeseriesResponse
+            example:
+              experiment:
+                id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
+                name: checkout_button_color
+                status: running
+              series:
+                - metric: checkout_completed
+                  group_name: treatment
+                  ds: 2026-05-08
+                  n: 11200
+                  mean: 0.1903
+                  delta_pct: 3.9
+                  p_value: 0.034
+                  srm_detected: 0
+                - metric: checkout_completed
+                  group_name: treatment
+                  ds: 2026-05-09
+                  n: 12519
+                  mean: 0.1922
+                  delta_pct: 4.8
+                  p_value: 0.018
+                  srm_detected: 0
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: timeseries
+      positional:
+        - id
+/api/admin/experiments/{id}/reanalyze:
+  post:
+    operationId: reanalyzeExperiment
+    summary: Re-queue analysis
+    description: |-
+      Requeues the daily analysis pass for this experiment outside the normal cron cadence. Useful after attaching a new metric or correcting an event taxonomy. The job runs asynchronously.
+
+      **Use case:** Force-refresh results after wiring up a new metric without waiting for the next nightly cron tick.
+    tags:
+      - Experiments
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Re-queue analysis
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/experiments.yaml#/ReanalyzeExperimentResponse
+            example:
+              id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
+              queued: true
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: reanalyze
+      positional:
+        - id