openapi: 3.2.0
info:
  title: Shipeasy Admin API
  version: 2.0.0
  description: |-
    REST API for managing feature gates, experiments, configs, universes, and killswitches in a Shipeasy project. Authenticate with an admin SDK key (`Authorization: Bearer sdk_admin_…`) and scope every request to a project via the `X-Project-Id` header.

    Mint admin keys via `POST /api/admin/keys` with `type: "admin"`. Keys expire after 90 days; rotate with the `revoke` action.
  contact:
    name: Shipeasy
    url: https://shipeasy.ai
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://shipeasy.ai
    description: Production
  - url: http://localhost:3000
    description: Local Next.js dev server
security:
  - bearerSdkKey: []
tags:
  - name: Release
    summary: Feature delivery — flags, kill switches, dynamic configs, A/B experiments, and the universes they bucket in.
    kind: nav
    description: |-
      Release: the feature-delivery surface. One roof over the five resources
      that decide which code path a user gets — feature gates (flags), kill
      switches, dynamic configs, A/B/n experiments, and the universes that bucket
      them — each exposed as its own subcommand group.

      **Groups.**
      - `flags` — boolean feature gates: AND-combined targeting rules + a percentage rollout (basis points), evaluated on the SDK hot path.
      - `killswitch` (`ks`) — per-env boolean overrides for incident response; no rules, no rollout, versioned per environment.
      - `configs` — JSON-Schema-validated structured values with a draft → publish workflow, delivered per environment.
      - `experiments` — randomised A/B/n assignment plus the analysis pipeline (t-test, sequential testing, SRM detection); `universes` hold the shared bucketing space and holdouts the experiments draw from.

      **Delivery model.** Every write rebuilds the project's KV blob and purges
      the CDN — SDKs poll at the plan interval and never touch the database on
      the hot path. The destructive verb is `archive` (soft-delete), never
      `delete`.

      Run `shipeasy release <group> --help` for the full contract of each group.
  - name: Flags
    parent: Release
    description: |-
      Feature gates: boolean flags evaluated at runtime against project rules + a percentage rollout.

      **Identity.** Each gate is keyed by a stable `name` (a-z, 0-9, `_`/`-`, max 64 chars) which is what SDKs pass to `Shipeasy.checkGate(user, '<name>')`. The `name` is immutable — rename means delete + recreate.

      **Evaluation model.** A gate returns `true` when (a) `enabled` is true, and (b) the caller satisfies the gate's rules. There are two evaluation shapes:
      - **Flat** — `rules` (AND-combined predicates) gate the caller, then `rollout_pct` (basis points, 0–10000) hashes them into a bucket. Used for simple `is in X% rollout` gates.
      - **Gatekeeper stack** — an ordered array of `condition` and `rollout` sub-gates, evaluated top-to-bottom; first match wins. Used to express `internal-only ∪ 1% beta ∪ 50% public` in one gate. When `stack` is present it takes precedence over the flat fields.

      **Rules.** Each rule is `{ attr, op, value }`. Supported ops: `eq`, `neq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `contains`, `regex`. Attribute names match the keys on the SDK evaluation context (e.g. `country`, `plan`, `email`).

      **Rollout basis points.** `rollout_pct` is in **basis points**, not percent. `0` = 0%, `100` = 1%, `5000` = 50%, `10000` = 100%. This allows sub-1% precision (e.g. `7` = 0.07%).

      **Lifecycle.** Create dark (`rollout_pct: 0`) → attach rules → ramp via PATCH → flip kill-switch via `disable`/`enable` → delete once retired. Deletion is blocked while a running experiment references the gate as a targeting gate.
  - name: Killswitch
    parent: Release
    x-cli:
      aliases:
        - ks
    description: |-
      Killswitches: per-env boolean overrides for kill-style operational toggles. Optimised for incident response — no rules, no rollout, just a flat boolean (plus optional per-key overrides) versioned per environment.

      **Identity.** Each killswitch is keyed by `name` in `folder.name` form (e.g. `payments.checkout`). Immutable after create.

      **Per-env values.** Every killswitch stores one version stream per env (`dev`, `stage`, `prod`). A `PATCH` with `value`/`switches` applies to **every** env in one shot (publishes a new version per env). To touch a single env, use `PUT /{id}/switch` and friends.

      **Switches map.** Optional `switches: { key: bool }` overrides the flat `value` for specific named call sites — useful for region/feature-scoped kills.

      **Versioning.** Each publish (create, update, set-switch, unset-switch) bumps the per-env `version` monotonically. SDKs deliver the latest published version.
  - name: Configs
    parent: Release
    description: |-
      Dynamic configs: JSON-Schema-validated structured values delivered to SDKs and editable per environment with a draft/publish workflow.

      **Identity.** Each config is keyed by `name` in `folder.name` form (e.g. `pricing.tiers`). Immutable after create.

      **Schema-first.** Every config carries a JSON Schema (draft 2020-12, top-level `type: 'object'`). Every published value is validated against it.

      **Drafts → publish.** Per-env edits go through `PUT /{id}/drafts` (stages a value) then `POST /{id}/publish` (promotes to a new version). The flat `PATCH /{id}` republishes on **every** env in one shot — bypassing drafts.

      **Versioning.** Each publish bumps the per-env `version` monotonically. SDKs deliver the latest published version for each env.
  - name: Experiments
    parent: Release
    description: |-
      A/B/n experiments: randomised group assignment plus the analysis pipeline (t-test, sequential testing, SRM detection) on top of a universe.

      **Identity.** Stable `name` (a-z, 0-9, `_`/`-`, max 64 chars). Immutable after create.

      **Lifecycle.** `draft → running → stopped → archived`. Transition via `POST /{id}/status`. An archived experiment that never started can be restored with `archived → draft`; restarting an archived experiment directly is not allowed.

      **Allocation.** `allocation_pct` (basis points, 0–10000) is the share of the targeted audience enrolled; `groups[].weight` (must sum to 10000) splits the enrolled audience. `targeting_gate` narrows the eligible audience before allocation.

      **Immutable while running.** `allocation_pct`, `groups`, `salt`, `universe`, `params` cannot be edited on a running experiment — stop it first.

      **Metrics.** Attach via `POST /{id}/metrics`. Each metric has a role: `goal` drives the decision, `guardrail` blocks ship on regression, `secondary` is informational.

      **Analysis.** Daily cron writes results to D1. Read via `GET /{id}/results` (latest per metric/group/day) or `GET /{id}/timeseries` (full history). `POST /{id}/reanalyze` requeues the analysis pass.
  - name: Universes
    parent: Experiments
    description: |-
      Universes: the shared bucketing space all experiments draw from.

      **Identity.** Each universe is keyed by a stable `name` (a-z, 0-9, `_`/`-`, max 64 chars). Experiments reference it via `universe: '<name>'`. The name is immutable.

      **Unit of randomisation.** `unit_type` selects the attribute hashed into a 0–9999 bucket — default `user_id` for per-user randomisation, `account_id` to keep a whole account in the same group.

      **Holdout.** `holdout_range` is an inclusive `[lo, hi]` bucket range (0–9999) reserved for measurement — callers hashed into the holdout are excluded from every experiment in the universe. Pro plan or higher.

      **Deletion.** Blocked while any non-archived experiment references the universe — archive those first.
  - name: Templates
    parent: Flags
    description: |-
      Targeting-rule templates: reusable `{ attr, op, value }` rule definitions
      (country, email-domain, region presets, …). Read-only built-ins ship with
      the platform; each project can also save its own. To target by
      country/plan/region, list templates, copy the matching template's `rules`,
      substitute the concrete value(s), and pass them to `release flags create`.
  - name: Attributes
    parent: Flags
    description: |-
      Targeting attributes: the auto-inferred schema of user-context keys the
      platform has observed in evaluation calls. Read-only — populated by the
      SDK hot path, surfaced here so you can see which keys (and value types)
      are available when writing gate/experiment targeting rules.
  - name: Metrics
    description: |-
      Metrics: the event-backed queries that drive tracking dashboards and
      experiment success / guardrail measurement.

      **Definition.** Each metric pins one source event (`event_name`), one
      aggregation, and (for `sum`/`avg`/quantile) a numeric value label. The
      query is expressed as the DSL string (`query`, e.g. `sum(purchase, amount)`)
      or its typed IR (`query_ir`) — supply exactly one.

      **Identity.** Keyed by a stable `name` (single segment or `folder.name`).
      Resolve endpoints accept the `id` or the `name`.

      **Deletion.** Archive (soft-delete). Blocked while the metric is attached
      to a running experiment — stop those first.
  - name: Events
    parent: Metrics
    description: |-
      Events: the catalog of event names (and their typed properties) that metric queries reference.

      **Auto-discovery.** The SDK's `/collect` ingest path records any unknown event name it receives as a `pending` row (`pending: 1`) so you can review it. Metrics defined on a pending event fail until it is approved.

      **Approval.** `POST /{id}/approve` promotes a pending event to usable (`pending: 0`), optionally declaring its folder/description/properties in the same call. Registering a brand-new event via `POST` that matches a pending name approves it instead of failing with a conflict.

      **Properties.** Each event can declare typed properties (`name`, `type` of `string|number|boolean`, `required`). On update/approve the `properties` array replaces the full set — there is no merge.

      **Deletion.** Soft-delete (the user-facing verb is `archive`). Blocked while any metric still references the event — delete those metrics first.
  - name: Ops
    description: |-
      Operational queue: the unified table of bug reports, feature requests, and
      auto-filed error/alert tickets, all over `/api/admin/ops`. One `create`
      endpoint files either user type (`type: bug | feature_request`); list, get,
      update, and link-pr are unified across every type. Also exposes the
      `notify` escalation bell and the read-only Slack-channels list used to
      resolve alert-rule notification targets.

      **Handles.** A queue item is addressed by its per-project `number` (e.g. `7`)
      or its full id — the API resolves either.
  - name: Alerts
    parent: Ops
    x-cli:
      aliases:
        - ar
    description: |-
      Alert rules: the metric-threshold definitions the analysis cron evaluates each run.

      **What fires.** Each rule binds a `metricId`, a `comparator` (`gt`/`gte`/`lt`/`lte`), and a `threshold`. On every cron pass the cron aggregates the metric over the trailing `windowHours` and raises an alert at `severity` when `value comparator threshold` holds.

      **Immutable metric.** The bound metric (and its aggregation) is fixed at create time — there is no update path for `metricId`. Tune `threshold`/`comparator`/`windowHours`/`severity`/`name`/`enabled` instead, or delete + recreate to repoint the rule at a different metric.

      **Delivery.** `notify` optionally targets a Slack channel and/or email for this rule; `null` falls back to the project's default notification settings. Slack targets require a connected Slack connector.
  - name: Comments
    parent: Ops
    description: |-
      Comments on a queue item — the discussion thread that hangs off any bug,
      feature request, or auto-filed error/alert ticket. Append a comment or read
      the thread; one level of threaded replies via `parentId`.

      **Mentions.** `@teammate` in a body raises an in-app notification for that
      person; `@shipeasy` asks Jarvis (the AI agent) to read the item and reply.
      Comments authored by Jarvis carry `authorType: system`.
  - name: Projects
    description: |-
      Projects: the account-level container every other resource is scoped to.

      **Account-level, not bound-project-level.** Both operations resolve from the caller's credential rather than the `.shipeasy`-bound project — `current` reads the project the auth header maps to, and `upsert` find-or-creates under the session's owner. Neither touches the local `.shipeasy` binding; recording the result there is a consumer side-effect layered on top.

      **Idempotent upsert.** A project is keyed by `(owner_email, domain)`. Calling `upsert` again with the same domain returns the existing project with `created: false`, so it is safe to run on every install.
  - name: i18n
    description: |-
      String Manager (i18n): the worker-safe REST surface — locale profiles, the
      insert-only key push, single-key overwrite, chunk publish, and the read-only
      key/draft listings.

      The fs/AST parts (scan, validate, install-loader, codemod) are NOT part of
      this API — they stay in the fs-having CLI/MCP.
  - name: Profiles
    parent: i18n
    description: Locale profiles (e.g. `en:prod`) — create, list, and publish a profile's chunks to the CDN.
  - name: Keys
    parent: i18n
    description: Translation keys — the insert-only push, single-key overwrite, and key listing.
  - name: Drafts
    parent: i18n
    description: Machine-translation drafts awaiting review before publish.
  - name: Errors
    description: |-
      Tracked production errors: the deduplicated, fingerprinted error stream the
      SDK + framework error sinks feed. Read-only list/get plus a status update
      (`open`/`resolved`/`ignored`), an auto-file-to-GitHub-issue action, and a
      time-series rollup. Errors are ingestion-only — there is no create route.
  - name: Trigger
    parent: Ops
    description: |-
      Recurring coding-agent triggers: the scheduled, unattended runs that burn
      down the ops queue in `--pr` mode (one PR per fixed item; nothing
      auto-merges). Shipeasy can fire four providers directly — Claude routines,
      Cursor cloud agents, Copilot cloud agents, and Google Jules (the Gemini
      path) — registered here as trigger connectors (idempotent per provider
      key). Other platforms (Codex, Windsurf, Cline, OpenClaw, OpenCode,
      Continue) schedule on their own surface — typically a GitHub Actions
      `schedule:` cron running the platform's headless CLI with the shared
      trigger prompt.
  - name: Connectors
    description: |-
      Outbound integrations: the per-project destinations feedback + trigger
      events are dispatched to (GitHub, Google Sheets, Slack, and the
      Claude/Cursor/Copilot/Jules autopilot triggers). CRUD plus a manual
      `fire` (trigger-only) and a `test` payload.
  - name: API Keys
    description: |-
      Admin + SDK key management: mint, list, and revoke the `sdk_*` keys that
      authenticate every other endpoint. The plaintext key is returned exactly
      once, on create. Revoke is the rotation verb.
paths:
  /api/admin/gates:
    get:
      operationId: listGates
      summary: List feature gates
      description: |-
        Returns a single page of gates ordered by `updated_at desc, id desc`. Use the `cursor` query parameter to paginate.

        **Use case:** Snapshot every gate in the project — for example to render an admin overview or to drive a CI check that asserts no gate is left at 100% in staging.
      tags:
        - Flags
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/PaginationLimit'
        - $ref: '#/components/parameters/PaginationCursor'
        - $ref: '#/components/parameters/Q'
      responses:
        '200':
          description: List feature gates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGatesResponse'
              example:
                data:
                  - id: gat_01j7w7m9q4hxbf6npe6s9zr3vc
                    name: checkout_v2
                    enabled: 1
                    rolloutPct: 5000
                    rules:
                      - attr: country
                        op: in
                        value:
                          - US
                          - CA
                          - GB
                      - attr: plan
                        op: neq
                        value: free
                    salt: 9c1f4f1f2c0c4a5fa1c2b6d3e7c8e3a1
                    title: Checkout v2
                    description: New checkout flow. Pro users in US/CA/GB only.
                    folder: checkout
                    groupName: growth
                    ownerEmail: ana@example.com
                    stack: null
                    updatedAt: '2026-05-09T16:01:22.000Z'
                next_cursor: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: list
    post:
      operationId: createGate
      summary: Create a feature gate
      description: |-
        Creates a new gate. Default `enabled: true` at the supplied `rollout_pct` (`0` = fully dark).

        Only `name` is required. Request fields use snake_case (`owner_email`); the GET response returns camelCase (`ownerEmail`, `groupName`).

        Returns `409` if `name` already exists in the project (case-sensitive).

        **Use cases**

        - **Dark create + ramp later** — `{ "name": "checkout_v2" }` at 0% rollout. Ramp via PATCH after deploy validation.
        - **Targeted rollout** — supply `rules` to gate the caller (e.g. only `plan = pro` users) plus a `rollout_pct` to bucket within that audience.
        - **Gatekeeper stack** — supply `stack` instead of `rules`/`rollout_pct` for `internal ∪ beta ∪ public` fall-through. Stack entries evaluated top-to-bottom; first match wins.
        - **Dashboard metadata** — populate `title`, `description`, `folder`, `group`, `owner_email` so the admin UI is self-documenting from day one.
        - **Disabled on create** — pre-provision with `enabled: false` for a future launch; flip on with `POST /{id}/enable` at go-live.
      tags:
        - Flags
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGateRequest'
            examples:
              minimal:
                summary: Minimal — dark gate, name only
                description: 'Smallest valid body. The gate is created `enabled: true` at `rollout_pct: 0`, with no rules. Ramp it later via PATCH.'
                value:
                  name: checkout_v2
              targeted:
                summary: Targeted rollout — rules + percentage
                description: 'Gate Pro users in US/CA/GB, then hash 10% of that audience into the on-bucket (`rollout_pct: 1000` = 10.00%). Adds dashboard metadata so the gate is self-documenting.'
                value:
                  name: checkout_v2
                  rollout_pct: 1000
                  rules:
                    - attr: country
                      op: in
                      value:
                        - US
                        - CA
                        - GB
                    - attr: plan
                      op: neq
                      value: free
                  title: Checkout v2
                  description: New checkout flow. Pro users in US/CA/GB only.
                  folder: checkout
                  group: growth
                  owner_email: ana@example.com
              gatekeeperStack:
                summary: Gatekeeper stack — internal ∪ beta ∪ public
                description: 'Three-layer fall-through: employees always on, opted-in beta accounts always on, then 25% of everyone else. First match wins; evaluation stops as soon as one entry returns `true`.'
                value:
                  name: checkout_v2
                  title: Checkout v2
                  owner_email: ana@example.com
                  stack:
                    - id: 01HKJ0EMP
                      type: condition
                      name: Employees
                      pass: any
                      rules:
                        - attr: email
                          op: regex
                          value: '@acme\.com$'
                    - id: 01HKJ0BETA
                      type: condition
                      name: Beta opt-in
                      pass: all
                      rules:
                        - attr: beta_opt_in
                          op: eq
                          value: true
                    - id: 01HKJ0PUB
                      type: rollout
                      name: Public
                      rolloutPct: 2500
                      bucketBy: userID
                      locked: true
              disabledOnCreate:
                summary: Disabled on create — provision then enable later
                description: 'Create with `enabled: false` so the gate evaluates to `false` for every caller until a follow-up `POST /{id}/enable`. Useful when provisioning ahead of a launch.'
                value:
                  name: checkout_v2
                  enabled: false
                  rollout_pct: 0
      responses:
        '201':
          description: Create a feature gate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateGateResponse'
              example:
                id: gat_01j7w7m9q4hxbf6npe6s9zr3vc
                name: checkout_v2
          links:
            UpdateGate:
              operationId: updateGate
              parameters:
                id: $response.body#/id
            EnableGate:
              operationId: enableGate
              parameters:
                id: $response.body#/id
            DisableGate:
              operationId: disableGate
              parameters:
                id: $response.body#/id
            DeleteGate:
              operationId: deleteGate
              parameters:
                id: $response.body#/id
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - ALREADY_EXISTS
        - VALIDATION
        - PLAN_LIMIT
      x-cli:
        name: create
        positional:
          - name
  /api/admin/gates/{id}:
    patch:
      operationId: updateGate
      summary: Update a feature gate
      description: |-
        Partial update — only supplied fields change. Array fields (`rules`, `stack`) **replace** wholesale; there is no merge or append.

        `name` and the gate id are immutable. The response carries only `{ id }` — re-fetch via `GET /api/admin/gates` for the new row.

        **Use cases**

        - **Ramp rollout** — `{ "rollout_pct": 5000 }` for 50%. Basis points (0–10000); `100` = 1%.
        - **Kill switch** — `{ "enabled": false }`. Forces evaluation to `false` for every caller regardless of rules/rollout. Re-enable with `POST /{id}/enable` or `{ "enabled": true }`.
        - **Modify a rule's `in` set** — send the full new `rules` array. To add `'GB'` to `['US','CA']`: `{ "rules": [{ "attr": "country", "op": "in", "value": ["US","CA","GB"] }] }`. No per-rule patch endpoint.
        - **Add targeting from scratch** — `{ "rules": [{ "attr": "email", "op": "regex", "value": "@acme\\.com$" }] }`.
        - **Switch to gatekeeper stack** — send a non-null `stack`. To revert to flat eval, send `{ "stack": null }`.
        - **Update metadata** — any subset of `title`, `description`, `folder`, `group`, `owner_email`.
      tags:
        - Flags
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque gate id (`gat_…`) or the gate's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGateRequest'
            examples:
              rampRollout:
                summary: Ramp rollout — 0 → 50%
                description: Single-field patch. `5000` basis points = 50%.
                value:
                  rollout_pct: 5000
              killSwitch:
                summary: Kill switch — disable the gate
                description: Forces evaluation to `false` for every caller, regardless of rules or rollout. Same effect as `POST /{id}/disable` but composable with other patches.
                value:
                  enabled: false
              extendInRule:
                summary: Add a value to an `in` rule
                description: Array fields replace wholesale — there is no per-rule patch. To add `'AU'` to a country whitelist that previously held `['US','CA','GB']`, send the full new `rules` array. Same pattern applies to `not_in`.
                value:
                  rules:
                    - attr: country
                      op: in
                      value:
                        - US
                        - CA
                        - GB
                        - AU
                    - attr: plan
                      op: neq
                      value: free
              replaceStack:
                summary: Replace gatekeeper stack
                description: 'Stack is replace-wholesale. Send the full new ordered list. Pass `"stack": null` to revert the gate to flat `rules` + `rollout_pct` evaluation.'
                value:
                  stack:
                    - id: 01HKJ0EMP
                      type: condition
                      name: Employees
                      pass: any
                      rules:
                        - attr: email
                          op: regex
                          value: '@acme\.com$'
                    - id: 01HKJ0PUB
                      type: rollout
                      name: Public
                      rolloutPct: 5000
                      locked: true
              updateMetadata:
                summary: Update dashboard metadata
                description: Any subset of `title`, `description`, `folder`, `group`, `owner_email`. Snake-case in the request; the GET response returns camelCase (`groupName`, `ownerEmail`).
                value:
                  title: Checkout v2 (50%)
                  description: Bumped to 50% after passing canary. Added AU.
                  folder: checkout
                  owner_email: ana@example.com
      responses:
        '200':
          description: Update a feature gate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateGateResponse'
              example:
                id: gat_01j7w7m9q4hxbf6npe6s9zr3vc
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: update
        positional:
          - id
    delete:
      operationId: deleteGate
      summary: Delete a feature gate
      description: |-
        Soft-deletes the gate. Returns 409 if the gate is still referenced by a running experiment as a targeting gate — stop the experiment first.

        **Use case:** Tear down a gate after a feature has fully shipped and the rollout flag is no longer needed.
      tags:
        - Flags
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque gate id (`gat_…`) or the gate's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Delete a feature gate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteGateResponse'
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - REFERENCED_IN_USE
      x-cli:
        name: archive
        positional:
          - id
  /api/admin/gates/{id}/enable:
    post:
      operationId: enableGate
      summary: Enable a gate
      description: |-
        Sets `enabled: true`. The current `rollout_pct` is preserved.

        **Use case:** Re-enable a previously disabled gate without re-issuing a full update.
      tags:
        - Flags
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque gate id (`gat_…`) or the gate's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Enable a gate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnableGateResponse'
              example:
                id: gat_01j7w7m9q4hxbf6npe6s9zr3vc
                enabled: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: enable
        positional:
          - id
  /api/admin/gates/{id}/disable:
    post:
      operationId: disableGate
      summary: Disable a gate
      description: |-
        Sets `enabled: false` so the gate evaluates to `false` for every caller, regardless of `rollout_pct` or `rules`. Use as a quick kill switch.

        **Use case:** Flip a gate off in production without redeploying — the canonical kill-switch flow.
      tags:
        - Flags
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque gate id (`gat_…`) or the gate's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Disable a gate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisableGateResponse'
              example:
                id: gat_01j7w7m9q4hxbf6npe6s9zr3vc
                enabled: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: disable
        positional:
          - id
  /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/ProjectId'
        - $ref: '#/components/parameters/PaginationLimit'
        - $ref: '#/components/parameters/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/Q'
      responses:
        '200':
          description: List experiments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/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/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/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/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/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/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/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Get one experiment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/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/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/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/UpdateExperimentResponse'
              example:
                id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - PLAN_REQUIRED
        - NOT_FOUND
        - IMMUTABLE_FIELD
        - INVALID_TRANSITION
        - GROUPS_WEIGHT_SUM
        - REFERENCED_NOT_FOUND
        - VALIDATION
        - EXPERIMENT_IMMUTABLE_FIELD
      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/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Delete an experiment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteExperimentResponse'
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/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/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/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/SetExperimentStatusResponse'
              example:
                id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
                status: running
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - INVALID_TRANSITION
        - VALIDATION
        - PLAN_LIMIT
        - EXPERIMENT_NO_GOAL_METRIC
        - EXPERIMENT_ARCHIVED_RESTART
        - EXPERIMENT_NOT_RUNNING
        - EXPERIMENT_RUNNING_ARCHIVE
        - EXPERIMENT_RESTORE_INVALID
      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/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/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/SetExperimentMetricsResponse'
              example:
                id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
                metrics:
                  - metric_id: met_checkout_completed
                    role: goal
                  - metric_id: met_page_errors
                    role: guardrail
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - EVENT_PENDING
        - REFERENCED_NOT_FOUND
        - VALIDATION
        - METRIC_UNKNOWN_ID
      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/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Get analysis results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/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/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
          schema:
            $ref: '#/components/schemas/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/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/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/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/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Re-queue analysis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReanalyzeExperimentResponse'
              example:
                id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
                queued: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: reanalyze
        positional:
          - id
  /api/admin/configs:
    get:
      operationId: listConfigs
      summary: List dynamic configs
      description: |-
        Returns a single page of configs ordered by `updated_at desc, id desc`. Each row includes the latest published `version` per env and any active drafts.

        **Use case:** Snapshot every config in the project — e.g. CI check that asserts no env is stuck on a stale default or that every config has a published value on prod.
      tags:
        - Configs
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/PaginationLimit'
        - $ref: '#/components/parameters/PaginationCursor'
        - $ref: '#/components/parameters/Q'
      responses:
        '200':
          description: List dynamic configs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListConfigsResponse'
              example:
                data:
                  - id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
                    name: pricing.tiers
                    description: Pricing tier definitions consumed by the checkout flow.
                    schema:
                      type: object
                      properties:
                        tiers:
                          type: array
                          items:
                            type: object
                      required:
                        - tiers
                    updatedAt: '2026-05-09T18:22:11.000Z'
                    envs:
                      dev:
                        version: 5
                        publishedAt: '2026-05-09T18:22:11.000Z'
                        publishedBy: ana@example.com
                      stage:
                        version: 4
                        publishedAt: '2026-05-08T11:05:22.000Z'
                        publishedBy: ana@example.com
                      prod:
                        version: 4
                        publishedAt: '2026-05-08T11:05:22.000Z'
                        publishedBy: ana@example.com
                    drafts:
                      dev:
                        updatedAt: '2026-05-10T09:31:00.000Z'
                        authorEmail: bo@example.com
                        baseVersion: 5
                next_cursor: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: list
    post:
      operationId: createConfig
      summary: Create a dynamic config
      description: |-
        Creates a new config with the given `schema`. The initial `value` (or an empty object) is published as version 1 on **every** env.

        Returns `409` if `name` already exists in the project, `400` if `value` doesn't validate against `schema`.

        **Use cases**

        - **Minimal create** — `name` + `schema`. Initial value defaults to `{}`.
        - **Seeded create** — supply a flat `value` to publish the same object on every env.
        - **Per-env seed** — supply a `{ env: value }` map for different per-env starting values.
      tags:
        - Configs
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConfigRequest'
            examples:
              minimal:
                summary: Minimal — name + schema
                description: Smallest valid body. Initial value defaults to `{}` on every env.
                value:
                  name: pricing.tiers
                  schema:
                    type: object
                    properties:
                      tiers:
                        type: array
                    required:
                      - tiers
              seededValue:
                summary: Seeded — schema + initial value
                description: Seed the same JSON object on every env at version 1.
                value:
                  name: pricing.tiers
                  description: Pricing tier definitions consumed by checkout.
                  schema:
                    type: object
                    properties:
                      tiers:
                        type: array
                    required:
                      - tiers
                  value:
                    tiers:
                      - name: free
                      - name: pro
              perEnvSeed:
                summary: Per-env seed
                description: 'Pass a `{ env: value }` map to seed different initial values per env.'
                value:
                  name: pricing.tiers
                  schema:
                    type: object
                    properties:
                      tiers:
                        type: array
                    required:
                      - tiers
                  value:
                    dev:
                      tiers:
                        - name: free
                        - name: pro
                        - name: enterprise
                    stage:
                      tiers:
                        - name: free
                        - name: pro
                    prod:
                      tiers:
                        - name: free
                        - name: pro
      responses:
        '201':
          description: Create a dynamic config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateConfigResponse'
              example:
                id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
                name: pricing.tiers
          links:
            GetConfig:
              operationId: getConfig
              parameters:
                id: $response.body#/id
            UpdateConfig:
              operationId: updateConfig
              parameters:
                id: $response.body#/id
            PublishConfigDraft:
              operationId: publishConfigDraft
              parameters:
                id: $response.body#/id
            DeleteConfig:
              operationId: deleteConfig
              parameters:
                id: $response.body#/id
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - ALREADY_EXISTS
        - VALIDATION
        - PLAN_LIMIT
      x-cli:
        name: create
        positional:
          - name
  /api/admin/configs/{id}:
    get:
      operationId: getConfig
      summary: Get one config
      description: |-
        Returns config metadata plus the latest published values per env and any active draft values. Use this to fetch the JSON the editor renders.

        **Use case:** Fetch one config's current published values and any in-flight drafts.
      tags:
        - Configs
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque config id (`cfg_…`) or the config's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Get one config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetConfigResponse'
              example:
                id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
                name: pricing.tiers
                description: Pricing tier definitions consumed by the checkout flow.
                schema:
                  type: object
                  properties:
                    tiers:
                      type: array
                      items:
                        type: object
                  required:
                    - tiers
                updatedAt: '2026-05-09T18:22:11.000Z'
                envs:
                  dev:
                    version: 5
                    publishedAt: '2026-05-09T18:22:11.000Z'
                    publishedBy: ana@example.com
                  stage:
                    version: 4
                    publishedAt: '2026-05-08T11:05:22.000Z'
                    publishedBy: ana@example.com
                  prod:
                    version: 4
                    publishedAt: '2026-05-08T11:05:22.000Z'
                    publishedBy: ana@example.com
                drafts:
                  dev:
                    updatedAt: '2026-05-10T09:31:00.000Z'
                    authorEmail: bo@example.com
                    baseVersion: 5
                values:
                  dev:
                    tiers:
                      - name: free
                      - name: pro
                  stage:
                    tiers:
                      - name: free
                      - name: pro
                  prod:
                    tiers:
                      - name: free
                      - name: pro
                draftValues:
                  dev:
                    tiers:
                      - name: free
                      - name: pro
                      - name: enterprise
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: get
        positional:
          - id
    patch:
      operationId: updateConfig
      summary: Update a dynamic config
      description: |-
        Partial update. When `value` is supplied it is **republished on every env** (new version per env). When `schema` is supplied it replaces the current schema; every existing value is re-validated.

        For env-scoped edits, use the draft/publish flow (`PUT /{id}/drafts` then `POST /{id}/publish`) instead.

        **Use cases**

        - **Republish flat value** — `{ "value": {…} }` sets the same value on every env.
        - **Schema migration** — `{ "schema": {…} }` replaces the schema; existing values are re-validated.
        - **Env-scoped edits** — use `PUT /{id}/drafts` + `POST /{id}/publish` instead of PATCH.
      tags:
        - Configs
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque config id (`cfg_…`) or the config's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConfigRequest'
            examples:
              flatValue:
                summary: Flat value — republish on every env
                description: Sets the same JSON object as a new version on dev/stage/prod.
                value:
                  value:
                    tiers:
                      - name: free
                      - name: pro
              schemaOnly:
                summary: Schema-only update
                description: Replaces the schema. Existing values must still validate or the update fails.
                value:
                  schema:
                    type: object
                    properties:
                      tiers:
                        type: array
                      trial_days:
                        type: integer
                    required:
                      - tiers
      responses:
        '200':
          description: Update a dynamic config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateConfigResponse'
              example:
                id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: update
        positional:
          - id
    delete:
      operationId: deleteConfig
      summary: Delete a dynamic config
      description: |-
        Soft-deletes the config and rebuilds the project's flags KV blob.

        **Use case:** Tear down a config after its consumers have stopped reading it.
      tags:
        - Configs
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque config id (`cfg_…`) or the config's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Delete a dynamic config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteConfigResponse'
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: archive
        positional:
          - id
  /api/admin/configs/{id}/drafts:
    put:
      operationId: saveConfigDraft
      summary: Save a draft value
      description: |-
        Stages a value for one env without publishing. The draft is validated against the config's current schema and stored alongside the `baseVersion` it was forked from.

        Saving over an existing draft overwrites it. Use `POST /{id}/publish` to promote it to a new published version.

        **Use case:** Iterate on a config value on dev without affecting prod — preview in staging, then publish.
      tags:
        - Configs
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque config id (`cfg_…`) or the config's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveConfigDraftRequest'
            examples:
              stageDev:
                summary: Stage a dev draft
                description: Stages a new value on dev without touching stage/prod.
                value:
                  env: dev
                  value:
                    tiers:
                      - name: free
                      - name: pro
                      - name: enterprise
      responses:
        '200':
          description: Save a draft value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SaveConfigDraftResponse'
              example:
                id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
                env: dev
                baseVersion: 5
                updatedAt: '2026-05-10T09:31:00.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: draft
        positional:
          - id
    delete:
      operationId: discardConfigDraft
      summary: Discard a draft
      description: |-
        Drops the in-flight draft on one env. Published values are unaffected.

        **Use case:** Abandon an in-progress draft after deciding not to ship it.
      tags:
        - Configs
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque config id (`cfg_…`) or the config's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscardConfigDraftRequest'
            examples:
              discardDev:
                summary: Discard the dev draft
                description: Drops the staged dev draft without publishing.
                value:
                  env: dev
      responses:
        '200':
          description: Discard a draft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscardConfigDraftResponse'
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: discard-draft
        positional:
          - id
  /api/admin/configs/{id}/publish:
    post:
      operationId: publishConfigDraft
      summary: Publish a draft
      description: |-
        Promotes the staged draft on one env to a new published version. The draft must still validate against the current schema.

        Returns `404` if there is no draft for the given env.

        **Use case:** Ship a staged change once you've validated it on a lower env.
      tags:
        - Configs
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque config id (`cfg_…`) or the config's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishConfigDraftRequest'
            examples:
              publishDev:
                summary: Publish the dev draft
                description: Promotes the dev draft to a new published version on dev.
                value:
                  env: dev
              publishProd:
                summary: Publish to prod
                description: Promotes the prod draft after staging signed off.
                value:
                  env: prod
      responses:
        '200':
          description: Publish a draft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishConfigDraftResponse'
              example:
                id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
                env: dev
                version: 6
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - INVALID_TRANSITION
        - VALIDATION
      x-cli:
        name: publish
        positional:
          - id
  /api/admin/configs/{id}/activity:
    get:
      operationId: listConfigActivity
      summary: List config activity
      description: |-
        Returns recent audit rows for one config (create, update, draft.save, publish, delete) ordered newest first. Use the `limit` query parameter to cap the result (1–100, default 20).

        **Use case:** Render the activity panel in the config editor or drive a slack notification on publish events.
      tags:
        - Configs
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque config id (`cfg_…`) or the config's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
        - name: limit
          in: query
          required: false
          description: Max rows to return (1–100). Defaults to 20.
          schema:
            default: 20
            type: integer
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: List config activity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListConfigActivityResponse'
              example:
                - id: act_01j7waf01a2b3c4d5e6f7g8h9i
                  action: config.publish
                  actorEmail: ana@example.com
                  actorType: user
                  payload:
                    env: dev
                    version: 6
                  createdAt: '2026-05-10T09:31:42.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: activity
        positional:
          - id
  /api/admin/configs/{id}/schema:
    patch:
      operationId: updateConfigSchema
      summary: Update a config schema
      description: |-
        Replaces a config's JSON Schema in place. Every existing published value is re-validated against the new schema before it lands; the update fails if any value no longer validates.

        **Use case:** Evolve a config's shape (add/remove a field) without republishing values.
      tags:
        - Configs
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque config id (`cfg_…`) or the config's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConfigSchemaRequest'
            examples:
              addField:
                summary: Add a field to the schema
                description: Replaces the schema; existing values must still validate or the update fails.
                value:
                  schema:
                    type: object
                    properties:
                      tiers:
                        type: array
                      trial_days:
                        type: integer
                    required:
                      - tiers
      responses:
        '200':
          description: Update a config schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateConfigSchemaResponse'
              example:
                id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: update-schema
        positional:
          - id
  /api/admin/killswitches:
    get:
      operationId: listKillswitches
      summary: List killswitches
      description: |-
        Returns a single page of killswitches ordered by `updated_at desc, id desc`. Each row includes the latest published `value`/`switches`/`version` per env.

        **Use case:** Snapshot every killswitch in the project — e.g. to render an incident-response runbook listing every kill and its current trip state.
      tags:
        - Killswitch
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/PaginationLimit'
        - $ref: '#/components/parameters/PaginationCursor'
        - $ref: '#/components/parameters/Q'
      responses:
        '200':
          description: List killswitches
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListKillswitchesResponse'
              example:
                data:
                  - id: ksw_01j7w9d8h2k4m6n8p0q2r4s6t8
                    name: payments.checkout
                    description: Master kill for the checkout flow. Trip to fall back to the legacy provider.
                    updatedAt: '2026-05-09T18:22:11.000Z'
                    envs:
                      dev:
                        value: false
                        version: 3
                        publishedAt: '2026-05-09T18:22:11.000Z'
                      stage:
                        value: false
                        version: 3
                        publishedAt: '2026-05-09T18:22:11.000Z'
                      prod:
                        value: false
                        switches:
                          eu_region: true
                        version: 5
                        publishedAt: '2026-05-09T18:22:11.000Z'
                next_cursor: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: list
    post:
      operationId: createKillswitch
      summary: Create a killswitch
      description: |-
        Creates a new killswitch with `value` (default `false`) applied to **every** env at version 1.

        Returns `409` if `name` already exists in the project.

        **Use cases**

        - **Untripped create** — `{ "name": "payments.checkout" }`. Provision the kill ahead of an incident.
        - **Pre-tripped** — `{ "value": true }` to ship the killswitch already engaged.
        - **With switches** — seed `switches` to carve out per-region/per-tenant kills from day one.
      tags:
        - Killswitch
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateKillswitchRequest'
            examples:
              minimal:
                summary: Minimal — name only, untripped
                description: 'Smallest valid body. Creates a killswitch with `value: false` on every env.'
                value:
                  name: payments.checkout
              preTripped:
                summary: Pre-tripped on create
                description: 'Ship the killswitch already tripped (`value: true`) — useful when provisioning a kill ahead of a deploy you want to ship with the feature off.'
                value:
                  name: payments.checkout
                  description: Master kill for the new checkout flow.
                  value: true
              withSwitches:
                summary: With per-region switches
                description: Seed a `switches` map so specific named call sites can be tripped independently of the flat `value`.
                value:
                  name: payments.checkout
                  value: false
                  switches:
                    eu_region: true
                    apac_region: false
      responses:
        '201':
          description: Create a killswitch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateKillswitchResponse'
              example:
                id: ksw_01j7w9d8h2k4m6n8p0q2r4s6t8
                name: payments.checkout
          links:
            GetKillswitch:
              operationId: getKillswitch
              parameters:
                id: $response.body#/id
            UpdateKillswitch:
              operationId: updateKillswitch
              parameters:
                id: $response.body#/id
            SetKillswitchSwitch:
              operationId: setKillswitchSwitch
              parameters:
                id: $response.body#/id
            SetKillswitchValue:
              operationId: setKillswitchValue
              parameters:
                id: $response.body#/id
            DeleteKillswitch:
              operationId: deleteKillswitch
              parameters:
                id: $response.body#/id
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - ALREADY_EXISTS
        - VALIDATION
        - PLAN_LIMIT
      x-cli:
        name: create
        positional:
          - name
  /api/admin/killswitches/{id}:
    get:
      operationId: getKillswitch
      summary: Get one killswitch
      description: |-
        Returns the killswitch metadata plus the latest published `value`/`switches`/`version` per env.

        **Use case:** Fetch the current state of one killswitch — e.g. to verify a trip propagated before declaring an incident mitigated.
      tags:
        - Killswitch
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Get one killswitch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetKillswitchResponse'
              example:
                id: ksw_01j7w9d8h2k4m6n8p0q2r4s6t8
                name: payments.checkout
                description: Master kill for the checkout flow. Trip to fall back to the legacy provider.
                updatedAt: '2026-05-09T18:22:11.000Z'
                envs:
                  dev:
                    value: false
                    version: 3
                    publishedAt: '2026-05-09T18:22:11.000Z'
                  stage:
                    value: false
                    version: 3
                    publishedAt: '2026-05-09T18:22:11.000Z'
                  prod:
                    value: false
                    switches:
                      eu_region: true
                    version: 5
                    publishedAt: '2026-05-09T18:22:11.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: get
        positional:
          - id
    patch:
      operationId: updateKillswitch
      summary: Update a killswitch
      description: |-
        Partial update applied to **every** env. Setting `value`/`switches` publishes a new version per env. Description-only patches don't bump versions.

        To change a single switch on a single env, use `PUT /{id}/switch` instead.

        **Use cases**

        - **Trip everywhere** — `{ "value": true }`. Kills the feature across dev/stage/prod in one call.
        - **Untrip everywhere** — `{ "value": false }`.
        - **Replace switches** — send the full new map; per-key edits use `PUT /{id}/switch`.
        - **Update description** — metadata-only patches don't bump versions.
      tags:
        - Killswitch
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateKillswitchRequest'
            examples:
              trip:
                summary: Trip the killswitch on every env
                description: 'Sets `value: true` on dev/stage/prod, bumping each env''s version by one.'
                value:
                  value: true
              untrip:
                summary: Untrip on every env
                description: 'Sets `value: false` on every env.'
                value:
                  value: false
              replaceSwitches:
                summary: Replace switches map
                description: Replaces the per-key overrides wholesale on every env. Pass `{}` to clear.
                value:
                  switches:
                    eu_region: true
                    apac_region: true
              updateDescription:
                summary: Description-only update
                description: Doesn't bump versions or trigger a republish — only metadata changes.
                value:
                  description: 'Master kill — owner: payments-platform'
      responses:
        '200':
          description: Update a killswitch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateKillswitchResponse'
              example:
                id: ksw_01j7w9d8h2k4m6n8p0q2r4s6t8
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: update
        positional:
          - id
    delete:
      operationId: deleteKillswitch
      summary: Delete a killswitch
      description: |-
        Soft-deletes the killswitch and rebuilds the project's flags KV blob so SDKs stop seeing it.

        **Use case:** Tear down a killswitch after the feature it protected has been removed.
      tags:
        - Killswitch
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Delete a killswitch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteKillswitchResponse'
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: archive
        positional:
          - id
  /api/admin/killswitches/{id}/switch:
    put:
      operationId: setKillswitchSwitch
      summary: Set one switch entry
      description: |-
        Sets or updates a single `switchKey` on a single `env`. Publishes one new version on that env only — other envs untouched.

        Use this for surgical per-env, per-key flips during incident response (e.g. trip `eu_region` on prod without touching the flat `value` or other envs).

        **Use cases**

        - **Trip a region** — `{ "env": "prod", "switchKey": "eu_region", "value": true }`.
        - **Untrip without removing** — same payload with `value: false`. To remove the entry entirely use `DELETE /{id}/switch`.
      tags:
        - Killswitch
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetKillswitchSwitchRequest'
            examples:
              tripRegion:
                summary: Trip eu_region on prod
                description: Sets `switches.eu_region = true` on prod only. Other envs and the flat `value` are unchanged.
                value:
                  env: prod
                  switchKey: eu_region
                  value: true
              untripRegion:
                summary: Untrip eu_region on prod
                description: Flip the same entry back off without removing it from the map.
                value:
                  env: prod
                  switchKey: eu_region
                  value: false
      responses:
        '200':
          description: Set one switch entry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetKillswitchSwitchResponse'
              example:
                id: ksw_01j7w9d8h2k4m6n8p0q2r4s6t8
                env: prod
                switchKey: eu_region
                value: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: set
        positional:
          - id
    delete:
      operationId: unsetKillswitchSwitch
      summary: Remove one switch entry
      description: |-
        Removes a single `switchKey` from the `switches` map on a single `env`. Publishes a new version on that env.

        Returns `{ removed: false }` if the entry didn't exist (idempotent no-op).

        **Use case:** Clean up a per-region override after the incident is resolved so the flat `value` governs again.
      tags:
        - Killswitch
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnsetKillswitchSwitchRequest'
            examples:
              removeRegion:
                summary: Remove eu_region from prod
                description: Drops the `eu_region` override on prod so the flat `value` applies again.
                value:
                  env: prod
                  switchKey: eu_region
      responses:
        '200':
          description: Remove one switch entry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsetKillswitchSwitchResponse'
              example:
                id: ksw_01j7w9d8h2k4m6n8p0q2r4s6t8
                env: prod
                switchKey: eu_region
                removed: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: unset
        positional:
          - id
  /api/admin/killswitches/{id}/value:
    put:
      operationId: setKillswitchValue
      summary: Set the flat value on one env
      description: |-
        Sets the flat `value` on a single `env`, publishing one new version on that env only. `switches` and other envs are untouched.

        Use this to trip (or untrip) a killswitch on one environment without replacing its per-key overrides.

        **Use cases**

        - **Trip on prod** — `{ "env": "prod", "value": true }`.
        - **Untrip on prod** — `{ "env": "prod", "value": false }`.
      tags:
        - Killswitch
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetKillswitchValueRequest'
            examples:
              tripProd:
                summary: Trip on prod
                description: 'Publishes `value: true` on prod only, bumping that env''s version.'
                value:
                  env: prod
                  value: true
              untripProd:
                summary: Untrip on prod
                description: 'Publishes `value: false` on prod only.'
                value:
                  env: prod
                  value: false
      responses:
        '200':
          description: Set the flat value on one env
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetKillswitchValueResponse'
              example:
                id: ksw_01j7w9d8h2k4m6n8p0q2r4s6t8
                env: prod
                version: 6
                published:
                  value: true
                  switches:
                    eu_region: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: set-value
        positional:
          - id
  /api/admin/universes:
    get:
      operationId: listUniverses
      summary: List universes
      description: |-
        Returns a single page of universes ordered by `created_at desc, id desc`. The universes table has no `updated_at`, so this list is keyed on creation time.

        **Use case:** Snapshot every universe in the project — for example to audit which `unit_type` and `holdout_range` are in use before launching a new experiment.
      tags:
        - Universes
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/PaginationLimit'
        - $ref: '#/components/parameters/PaginationCursor'
        - $ref: '#/components/parameters/Q'
      responses:
        '200':
          description: List universes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUniversesResponse'
              example:
                data:
                  - id: uni_01j7w8a1b2c3d4e5f6g7h8i9j0
                    name: primary_users
                    unitType: user_id
                    holdoutRange:
                      - 9500
                      - 9999
                    createdAt: '2026-04-12T10:14:08.000Z'
                next_cursor: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: list
    post:
      operationId: createUniverse
      summary: Create a universe
      description: |-
        Creates a new universe. Only `name` is required — `unit_type` defaults to `user_id` and `holdout_range` defaults to `null` (no holdout).

        Returns `409` if `name` already exists in the project. Returns `403` if you supply `holdout_range` on a plan below Pro.

        **Use cases**

        - **Default universe** — `{ "name": "primary_users" }`. Per-user randomisation, no holdout.
        - **Reserved holdout** — supply `holdout_range` to carve out a measurement slice excluded from all experiments.
        - **Account-level** — `unit_type: 'account_id'` so multi-seat accounts see one consistent variant.
      tags:
        - Universes
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUniverseRequest'
            examples:
              minimal:
                summary: Minimal — name only
                description: Smallest valid body. Creates a `user_id`-keyed universe with no holdout.
                value:
                  name: primary_users
              holdout:
                summary: Holdout — reserve 5% for measurement
                description: Reserves buckets 9500–9999 (5% of callers) as the holdout. Pro plan or higher.
                value:
                  name: primary_users
                  holdout_range:
                    - 9500
                    - 9999
              accountLevel:
                summary: Account-level randomisation
                description: 'Bucket whole accounts together via `unit_type: ''account_id''`.'
                value:
                  name: saas_accounts
                  unit_type: account_id
      responses:
        '201':
          description: Create a universe
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUniverseResponse'
              example:
                id: uni_01j7w8a1b2c3d4e5f6g7h8i9j0
                name: primary_users
          links:
            UpdateUniverse:
              operationId: updateUniverse
              parameters:
                id: $response.body#/id
            DeleteUniverse:
              operationId: deleteUniverse
              parameters:
                id: $response.body#/id
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - PLAN_REQUIRED
        - ALREADY_EXISTS
        - VALIDATION
        - PLAN_LIMIT
      x-cli:
        name: create
        positional:
          - name
  /api/admin/universes/{id}:
    patch:
      operationId: updateUniverse
      summary: Update a universe
      description: |-
        Partial update. Only `holdout_range` is mutable — `name` and `unit_type` are immutable after create.

        Pass `"holdout_range": null` to remove an existing holdout.

        **Use cases**

        - **Adjust holdout** — change the reserved measurement slice without recreating experiments.
        - **Remove holdout** — `{ "holdout_range": null }`.
      tags:
        - Universes
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque universe id (`uni_…`) or the universe's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUniverseRequest'
            examples:
              setHoldout:
                summary: Set holdout — reserve 5%
                description: Reserve buckets 9500–9999 as the holdout. Pro plan or higher.
                value:
                  holdout_range:
                    - 9500
                    - 9999
              removeHoldout:
                summary: Remove holdout
                description: Disable the holdout entirely.
                value:
                  holdout_range: null
      responses:
        '200':
          description: Update a universe
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateUniverseResponse'
              example:
                id: uni_01j7w8a1b2c3d4e5f6g7h8i9j0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - PLAN_REQUIRED
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: update
        positional:
          - id
    delete:
      operationId: deleteUniverse
      summary: Delete a universe
      description: |-
        Soft-deletes the universe. Returns `409` if any non-archived experiment still references it — archive those experiments first.

        **Use case:** Tear down a universe after every experiment that used it has been archived.
      tags:
        - Universes
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque universe id (`uni_…`) or the universe's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Delete a universe
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteUniverseResponse'
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - REFERENCED_IN_USE
      x-cli:
        name: archive
        positional:
          - id
  /api/admin/gates/templates:
    get:
      operationId: listGateTemplates
      summary: List gate templates
      description: |-
        Returns the merged targeting-rule template catalog — read-only **built-ins first** (the `@team`/`@owner` audience aliases, country, email-domain, region presets, …), then this project's **customer** templates. Each item carries a `rules: [{ attr, op, value }]` definition; the alias templates carry a symbol value (`email in ["@team"]`) that the SDK expands to the resolved email list at rebuild.

        **Turn "launch X in country Y" into a gated flag:** list templates (optionally with `q`), take the matching template's `rules`, substitute the concrete value(s), and pass them as the `rules` arg of `release_flags_create`.

        The catalog is small and bounded, so the full merged set is returned in one page — this endpoint is **not** paginated (`next_cursor` is always `null`; there are no `limit`/`cursor` params).
      tags:
        - Templates
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/Q'
        - name: query
          in: query
          required: false
          deprecated: true
          description: Deprecated alias for `q`, kept working for one release. Prefer `q`.
          schema:
            type: string
      responses:
        '200':
          description: List gate templates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGateTemplatesResponse'
              example:
                data:
                  - id: country
                    name: Country is
                    description: Target by ISO country code (resolve from GeoIP at the SDK edge before evaluating).
                    category: condition
                    auto: true
                    builtin: true
                    iconKey: globe
                    rules:
                      - attr: country
                        op: in
                        value:
                          - DE
                          - FR
                          - IT
                    createdAt: null
                    updatedAt: null
                next_cursor: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: list
    post:
      operationId: createGateTemplate
      summary: Create a gate template
      description: Creates a per-project (customer) targeting-rule template. Built-ins are read-only and cannot be created here. Returns `409` if a template with this `name` already exists in the project.
      tags:
        - Templates
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGateTemplateRequest'
            examples:
              enterpriseBeta:
                summary: Save an "enterprise plan" condition
                value:
                  name: Enterprise beta
                  description: Our enterprise plan on the beta ring.
                  category: condition
                  rules:
                    - attr: plan
                      op: eq
                      value: enterprise
      responses:
        '201':
          description: Create a gate template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateGateTemplateResponse'
              example:
                id: gtpl_01j7w8a1b2c3d4e5f6g7h8i9j0
                name: Enterprise beta
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - ALREADY_EXISTS
        - VALIDATION
      x-cli:
        name: create
        positional:
          - name
  /api/admin/gates/templates/{id}:
    get:
      operationId: getGateTemplate
      summary: Get one gate template
      description: Returns a single template by its `id` — a built-in slug (`country`) or a customer `gtpl_…` id.
      tags:
        - Templates
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Built-in slug (`country`) or customer template id (`gtpl_…`).
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Get one gate template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GateTemplate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: get
        positional:
          - id
    patch:
      operationId: updateGateTemplate
      summary: Update a gate template
      description: Partial update of a **customer** template. `rules` replaces the list wholesale. Returns `409` if `id` names a read-only built-in template.
      tags:
        - Templates
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Customer template id (`gtpl_…`) or its `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGateTemplateRequest'
            examples:
              rename:
                summary: Rename + retarget
                value:
                  name: Enterprise GA
                  rules:
                    - attr: plan
                      op: in
                      value:
                        - enterprise
                        - enterprise_trial
      responses:
        '200':
          description: Update a gate template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateGateTemplateResponse'
              example:
                id: gtpl_01j7w8a1b2c3d4e5f6g7h8i9j0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - READ_ONLY
        - VALIDATION
      x-cli:
        name: update
        positional:
          - id
    delete:
      operationId: deleteGateTemplate
      summary: Delete a gate template
      description: Soft-deletes (archives) a **customer** template. Returns `409` if `id` names a read-only built-in template.
      tags:
        - Templates
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Customer template id (`gtpl_…`) or its `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Delete a gate template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteGateTemplateResponse'
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - READ_ONLY
      x-cli:
        name: archive
        positional:
          - id
  /api/admin/attributes:
    get:
      operationId: listAttributes
      summary: List targeting attributes
      description: |-
        Returns every auto-inferred targeting attribute in the project — the `name` and (when known) the value `type` — for building gate/experiment targeting rules.

        **Use case:** Discover which user-context keys are available before authoring a targeting rule, instead of guessing attribute names.
      tags:
        - Attributes
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/Q'
      responses:
        '200':
          description: List targeting attributes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAttributesResponse'
              example:
                - name: plan
                  type: string
                - name: country
                  type: string
                - name: seats
                  type: number
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: list
    post:
      operationId: createAttribute
      summary: Declare a targeting attribute
      description: |-
        Declare a targeting attribute the SDK reports and gates/experiments can target. `type: enum` requires `enum_values`.

        **Use case:** Register a `plan` or `country` attribute so targeting rules can reference it.
      tags:
        - Attributes
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAttributeRequest'
            example:
              name: plan
              type: enum
              enum_values:
                - free
                - paid
              required: true
      responses:
        '201':
          description: Declare a targeting attribute
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAttributeResponse'
              example:
                id: attr_01j7w8a1b2c3
                name: plan
          links:
            GetAttribute:
              operationId: getAttribute
              parameters:
                id: $response.body#/id
            UpdateAttribute:
              operationId: updateAttribute
              parameters:
                id: $response.body#/id
            DeleteAttribute:
              operationId: deleteAttribute
              parameters:
                id: $response.body#/id
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - ALREADY_EXISTS
        - VALIDATION
      x-cli:
        name: create
        positional:
          - name
  /api/admin/attributes/{id}:
    get:
      operationId: getAttribute
      summary: Get a targeting attribute
      description: |-
        Fetch one targeting attribute by id.

        **Use case:** Inspect an attribute's declared type + allowed values before editing it.
      tags:
        - Attributes
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: The attribute id.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Get a targeting attribute
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAttributeResponse'
              example:
                id: attr_01j7w8a1b2c3
                name: plan
                type: enum
                enumValues:
                  - free
                  - paid
                required: 1
                createdAt: '2026-06-20T09:14:08.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: get
        positional:
          - id
    patch:
      operationId: updateAttribute
      summary: Update a targeting attribute
      description: |-
        Update a targeting attribute's type, allowed values, required flag, description, or SDK path. `name` is immutable.

        **Use case:** Add an allowed value to an `enum` attribute, or flip its required flag.
      tags:
        - Attributes
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: The attribute id.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAttributeRequest'
            example:
              enum_values:
                - free
                - paid
                - enterprise
      responses:
        '200':
          description: Update a targeting attribute
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateAttributeResponse'
              example:
                id: attr_01j7w8a1b2c3
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: update
        positional:
          - id
    delete:
      operationId: deleteAttribute
      summary: Archive a targeting attribute
      description: |-
        Soft-deletes (archives) a targeting attribute.

        **Use case:** Retire an attribute no targeting rule references anymore (the user-facing verb is `archive`).
      tags:
        - Attributes
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: The attribute id.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Archive a targeting attribute
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteAttributeResponse'
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: archive
        positional:
          - id
  /api/admin/metrics:
    get:
      operationId: listMetrics
      summary: List metrics
      description: |-
        Returns every metric in the project (not paginated) — name, folder, source event, the typed `queryIr`, and the rendered query.

        **Use case:** Audit every metric defined in the project — for example to find the metric id to attach as an experiment's success metric.
      tags:
        - Metrics
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/Q'
      responses:
        '200':
          description: List metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMetricsResponse'
              example:
                - id: met_01j7w8a1b2c3d4e5f6g7h8i9j0
                  name: checkouts
                  folder: null
                  eventName: checkout_completed
                  query: count_users(checkout_completed)
                  queryIr:
                    agg:
                      kind: count_users
                    metric: checkout_completed
                    filters: []
                  direction: higher_better
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: list
    post:
      operationId: createMetric
      summary: Create a metric
      description: |-
        Creates an event-backed metric. Pass the query as the DSL string (`query`) **or**
        the typed IR (`query_ir`) — exactly one. `event_name` must equal the event the
        query references.

        Returns `409` if a metric with the same `name` already exists, and `422` if the
        query is invalid or references an unregistered event / label.

        **Use cases**

        - **Track an event** — `count_users(<event>)` for unique-user counts.
        - **Sum a value** — `sum(<event>, <label>)` for revenue / quantity metrics.
        - **Experiment success metric** — create the metric, then attach its id to an experiment.
      tags:
        - Metrics
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMetricRequest'
            examples:
              countUsers:
                summary: Count unique users (DSL)
                description: Unique users who completed checkout, expressed with the query DSL.
                value:
                  name: checkouts
                  event_name: checkout_completed
                  query: count_users(checkout_completed)
              sumRevenue:
                summary: Sum a value label (DSL)
                description: Total revenue, summing the `amount` property of the `purchase` event.
                value:
                  name: revenue
                  folder: checkout
                  event_name: purchase
                  query: sum(purchase, amount)
                  direction: higher_better
              typedIr:
                summary: Typed IR
                description: Same metric supplied as the structured `query_ir` instead of the DSL.
                value:
                  name: checkouts
                  event_name: checkout_completed
                  query_ir:
                    agg:
                      kind: count_users
                    metric: checkout_completed
                    filters: []
      responses:
        '201':
          description: Create a metric
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateMetricResponse'
              example:
                id: met_01j7w8a1b2c3d4e5f6g7h8i9j0
                name: checkouts
          links:
            GetMetric:
              operationId: getMetric
              parameters:
                id: $response.body#/id
            UpdateMetric:
              operationId: updateMetric
              parameters:
                id: $response.body#/id
            DeleteMetric:
              operationId: deleteMetric
              parameters:
                id: $response.body#/id
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - ALREADY_EXISTS
        - EVENT_PENDING
        - REFERENCED_NOT_FOUND
        - VALIDATION
        - PLAN_LIMIT
      x-cli:
        name: create
        positional:
          - name
  /api/admin/metrics/{id}:
    get:
      operationId: getMetric
      summary: Get a metric
      description: |-
        Fetch one metric by its id or name, including the rendered DSL query and the typed IR.

        **Use case:** Inspect a single metric's full definition before reusing it in an experiment or alert rule.
      tags:
        - Metrics
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque metric id (`met_…`) or the metric's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Get a metric
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMetricResponse'
              example:
                id: met_01j7w8a1b2c3d4e5f6g7h8i9j0
                name: revenue
                folder: checkout
                eventName: purchase
                query: sum(purchase, amount)
                queryIr:
                  agg:
                    kind: sum
                  metric: purchase
                  valueLabel: amount
                  filters: []
                direction: higher_better
                winsorizePct: 99
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: show
        positional:
          - id
    patch:
      operationId: updateMetric
      summary: Update a metric
      description: |-
        Update a metric's definition — folder, source event, query (`query` DSL or typed `query_ir`), winsorisation, minimum detectable effect, or direction. `name` is immutable. Provide at most one of `query` / `query_ir`.

        **Use case:** Refine a metric's query or guardrail direction without recreating it.
      tags:
        - Metrics
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque metric id (`met_…`) or the metric's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMetricRequest'
            example:
              direction: lower_better
              winsorize_pct: 95
      responses:
        '200':
          description: Update a metric
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMetricResponse'
              example:
                id: met_01j7w8a1b2c3d4e5f6g7h8i9j0
                name: revenue
                direction: lower_better
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: update
        positional:
          - id
    delete:
      operationId: deleteMetric
      summary: Archive a metric
      description: |-
        Soft-deletes (archives) the metric. Returns `409` if it is attached to a running experiment — stop those experiments first.

        **Use case:** Retire a metric once no running experiment depends on it (the user-facing verb is `archive`).
      tags:
        - Metrics
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque metric id (`met_…`) or the metric's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Archive a metric
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteMetricResponse'
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - REFERENCED_IN_USE
      x-cli:
        name: archive
        positional:
          - id
  /api/admin/events:
    get:
      operationId: listEvents
      summary: List events
      description: |-
        Returns every catalogued event in the project, including pending auto-discovered names. Each row carries its own `pending` flag, so the unapproved queue can be filtered client-side.

        **Use case:** Snapshot the event catalog — for example to review the pending auto-discovery queue before approving names, or to confirm which events your metrics can reference.
      tags:
        - Events
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/Q'
      responses:
        '200':
          description: List events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEventsResponse'
              example:
                - id: evt_01j7w8a1b2c3d4e5f6g7h8i9j0
                  name: checkout_completed
                  folder: checkout
                  description: Fired when a customer finishes checkout.
                  properties:
                    - name: amount
                      type: number
                      required: true
                      description: ''
                  pending: 0
                  createdAt: '2026-04-12T10:14:08.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: list
    post:
      operationId: createEvent
      summary: Register an event
      description: |-
        Registers a new event name and (optionally) its typed properties. Only `name` is required.

        If the name matches an existing **pending** (auto-discovered) row, this approves that row instead of returning a conflict. Otherwise an already-registered name returns `409`.

        **Use cases**

        - **Register a known event** — `{ "name": "checkout_completed" }` so metrics can reference it.
        - **Declare typed properties** — supply `properties` to document the event's payload shape.
      tags:
        - Events
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEventRequest'
            examples:
              minimal:
                summary: Minimal — name only
                description: Smallest valid body. Registers the event with no properties.
                value:
                  name: checkout_completed
              withProperty:
                summary: With a typed, required property
                description: Declare a required numeric `amount` property and file it under `checkout`.
                value:
                  name: purchase
                  folder: checkout
                  properties:
                    - name: amount
                      type: number
                      required: true
      responses:
        '201':
          description: Register an event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEventResponse'
              example:
                id: evt_01j7w8a1b2c3d4e5f6g7h8i9j0
                name: checkout_completed
          links:
            GetEvent:
              operationId: getEvent
              parameters:
                id: $response.body#/id
            UpdateEvent:
              operationId: updateEvent
              parameters:
                id: $response.body#/id
            ApproveEvent:
              operationId: approveEvent
              parameters:
                id: $response.body#/id
            DeleteEvent:
              operationId: deleteEvent
              parameters:
                id: $response.body#/id
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - ALREADY_EXISTS
        - VALIDATION
        - PLAN_LIMIT
      x-cli:
        name: create
        positional:
          - name
  /api/admin/events/{id}:
    get:
      operationId: getEvent
      summary: Get an event
      description: |-
        Returns one event's full detail. Resolves by exact id, unique id-prefix, or exact (unique) name.

        **Use case:** Inspect one event's declared properties and pending state by id or name.
      tags:
        - Events
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque event id (`evt_…`) or the event's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Get an event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetEventResponse'
              example:
                id: evt_01j7w8a1b2c3d4e5f6g7h8i9j0
                name: checkout_completed
                folder: checkout
                description: Fired when a customer finishes checkout.
                properties:
                  - name: amount
                    type: number
                    required: true
                    description: ''
                pending: 0
                createdAt: '2026-04-12T10:14:08.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: get
        positional:
          - id
    patch:
      operationId: updateEvent
      summary: Update an event
      description: |-
        Partial update of an event's folder, description, or properties. `name` is immutable.

        `properties` replaces the full set (no merge) — omit it to leave properties unchanged.

        **Use case:** Refile an event, update its description, or redeclare its typed properties.
      tags:
        - Events
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque event id (`evt_…`) or the event's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEventRequest'
            examples:
              refile:
                summary: Move to a folder
                description: File the event under `checkout`.
                value:
                  folder: checkout
              setProperties:
                summary: Replace the property set
                description: Overwrite the full property list (no merge).
                value:
                  properties:
                    - name: amount
                      type: number
                      required: true
      responses:
        '200':
          description: Update an event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateEventResponse'
              example:
                id: evt_01j7w8a1b2c3d4e5f6g7h8i9j0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: update
        positional:
          - id
    delete:
      operationId: deleteEvent
      summary: Archive an event
      description: |-
        Soft-deletes (archives) the event. Returns `409` if any metric still references it — delete those metrics first.

        **Use case:** Retire an event from the catalog once no metric depends on it.
      tags:
        - Events
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque event id (`evt_…`) or the event's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Archive an event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteEventResponse'
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - REFERENCED_IN_USE
      x-cli:
        name: archive
        positional:
          - id
  /api/admin/events/{id}/approve:
    post:
      operationId: approveEvent
      summary: Approve a pending event
      description: |-
        Promotes a pending (auto-discovered) event to usable so metrics can query it (`pending` → `0`).

        You may optionally declare the event's folder, description, or properties in the same call — the body is the same shape as update, and may be empty.

        **Use case:** Clear an auto-discovered event out of the pending queue so metrics defined on it start resolving.
      tags:
        - Events
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque event id (`evt_…`) or the event's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApproveEventRequest'
            examples:
              bare:
                summary: Approve as-is
                description: Promote the pending event with no further changes.
                value: {}
              withProperties:
                summary: Approve and declare properties
                description: Promote the event and document its payload shape at the same time.
                value:
                  folder: checkout
                  properties:
                    - name: amount
                      type: number
                      required: true
      responses:
        '200':
          description: Approve a pending event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApproveEventResponse'
              example:
                id: evt_01j7w8a1b2c3d4e5f6g7h8i9j0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: approve
        positional:
          - id
  /api/admin/ops:
    get:
      operationId: listOpsItems
      summary: List the operational queue
      description: |-
        Returns the unified ops queue (bugs, feature requests, errors, alerts) in work order — highest priority first, oldest first within a priority — so consumers work it top-down. Filter by `type` and/or `status`, and cap with `limit`. Human-gated holding states (items awaiting human sign-off in the dashboard) are never returned by `all`/default status.

        **Use case:** Pull the open queue to triage — e.g. every `bug` still `open` — before working items down one by one.
      tags:
        - Ops
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: type
          in: query
          required: false
          description: Filter by item type (`bug`/`feature_request`/`error`/`alert`), or `all`.
          schema:
            anyOf:
              - type: string
                enum:
                  - bug
                  - feature_request
                  - error
                  - alert
                description: Queue item type. `bug` and `feature_request` are user-fileable; `error` and `alert` tickets are auto-filed by the platform.
              - type: string
                const: all
        - name: status
          in: query
          required: false
          description: Filter by lifecycle status, or `all`. The human-gated holding states (`pending_approval`, `triage`) are excluded from `all`/default and returned only when requested as the exact status.
          schema:
            anyOf:
              - $ref: '#/components/schemas/OpsItemStatus'
              - type: string
                const: all
        - name: limit
          in: query
          required: false
          description: Max items to return (1–500).
          schema:
            type: integer
            minimum: 1
            maximum: 500
      responses:
        '200':
          description: List the operational queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOpsItemsResponse'
              example:
                - id: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
                  number: 7
                  type: bug
                  title: Checkout button misaligned on mobile
                  status: open
                  priority: high
                  createdAt: '2026-06-20T09:14:08.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: list
    post:
      operationId: createOpsItem
      summary: File a queue item
      description: |-
        Files one queue item — a bug report or a feature request — and fires the project's connectors (GitHub issue / Slack). `type` selects which; only the two user-fileable types are accepted (`error`/`alert` tickets are auto-filed by the platform). Returns the new id and per-project number.

        **Use cases**

        - **File a bug** — `{ "type": "bug", "title": "Checkout 500s on Safari", "stepsToReproduce": "…" }`.
        - **File a feature request** — `{ "type": "feature_request", "title": "Dark mode", "priority": "nice_to_have" }`.
      tags:
        - Ops
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOpsItemRequest'
            examples:
              bug:
                summary: File a bug report
                value:
                  type: bug
                  title: Checkout button misaligned on mobile
                  stepsToReproduce: Open the cart on iOS Safari and tap the price row.
                  actualResult: The primary CTA overlaps the price.
                  expectedResult: The CTA sits below the price with clear spacing.
                  priority: high
              featureRequest:
                summary: File a feature request
                value:
                  type: feature_request
                  title: Dark mode for the dashboard
                  description: Add a theme toggle that persists per user.
                  useCase: Reduce eye strain for users working at night.
                  priority: nice_to_have
      responses:
        '201':
          description: File a queue item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOpsItemResponse'
              example:
                id: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
                number: 7
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - ALREADY_EXISTS
        - VALIDATION
      x-cli:
        name: create
        positional:
          - title
        commands:
          - name: create
            summary: File a queue item (bug or feature request) — pass --type.
          - name: bug
            summary: File a bug report.
            preset:
              type: bug
          - name: feature
            summary: File a feature request.
            preset:
              type: feature_request
  /api/admin/ops/{handle}:
    get:
      operationId: getOpsItem
      summary: Get one queue item
      description: |-
        Fetch a single queue item by its per-project `number` or full id.

        **Use case:** Inspect one item's full detail before updating its status or linking a PR.
      tags:
        - Ops
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: handle
          in: path
          required: true
          description: Per-project item number (e.g. `7`) or the full ops item id.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Get one queue item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOpsItemResponse'
              example:
                id: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
                number: 7
                type: bug
                title: Checkout button misaligned on mobile
                status: open
                priority: high
                createdAt: '2026-06-20T09:14:08.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: get
        positional:
          - handle
    patch:
      operationId: updateOpsItem
      summary: Update a queue item
      description: |-
        Update a queue item. The body is validated against the item's stored type: a `bug` accepts its content fields (title, steps-to-reproduce, actual/expected result) plus `status`/`priority`/`notify` and a GitHub PR link; a `feature_request` its content (title, description, use-case) plus the same triage fields; `error`/`alert`/`measure_plan` accept `status`/`priority`/`notify` only (their content is platform-owned). Pass at least one field.

        Completing an `error` ticket (status `resolved` or `ready_for_qa`) also resolves the tracked error it links to; the error reopens automatically if it recurs — so completing is safe pre-deploy.

        **Use cases**

        - **Start working an item** — `{ "status": "in_progress" }`.
        - **Hand off for review** — `{ "status": "ready_for_qa" }` once the fix landed (the mode PR-based loops use).
        - **Triage** — `{ "priority": "high" }`, content edits on bug/feature items.
      tags:
        - Ops
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: handle
          in: path
          required: true
          description: Per-project item number (e.g. `7`) or the full ops item id.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOpsItemRequest'
            examples:
              startWork:
                summary: Flip an item to in_progress when starting it
                value:
                  status: in_progress
              handOff:
                summary: Hand a fixed item off for human review
                value:
                  status: ready_for_qa
              triage:
                summary: Set priority while triaging
                value:
                  priority: high
      responses:
        '200':
          description: Update a queue item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateOpsItemResponse'
              example:
                id: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: update
        positional:
          - handle
  /api/admin/ops/{handle}/link-pr:
    post:
      operationId: linkPrToOpsItem
      summary: Link a fixing PR
      description: |-
        Record the pull request that fixes a queue item (and clears the link with `prNumber: null`).

        **Use case:** Tie the fixing PR to the item so closing the PR can flip it to ready_for_qa.
      tags:
        - Ops
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: handle
          in: path
          required: true
          description: Per-project item number (e.g. `7`) or the full ops item id.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkPrToOpsItemRequest'
            example:
              prNumber: 412
              prUrl: https://github.com/acme/app/pull/412
      responses:
        '200':
          description: Link a fixing PR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkPrToOpsItemResponse'
              example:
                id: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: link-pr
        positional:
          - handle
  /api/admin/ops/{handle}/comments:
    get:
      operationId: listOpsComments
      summary: List an item's comments
      description: |-
        List the comment thread on a queue item, oldest first. Each comment
        carries its author (a teammate email, or `system` for a comment authored by
        Jarvis — the AI agent), its markdown body, and `parentId` for the single
        level of threaded replies. Removed comments are omitted.

        **Use case:** Read the discussion on an item before replying or acting on it.
      tags:
        - Comments
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: handle
          in: path
          required: true
          description: Per-project item number (e.g. `7`) or the full ops item id.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: List an item's comments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOpsCommentsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: list
        positional:
          - handle
    post:
      operationId: createOpsComment
      summary: Comment on an item
      description: |-
        Append a comment to a queue item's thread. The body is markdown (mentions
        like `@teammate` notify that person; `@shipeasy` asks Jarvis, the AI agent,
        to reply). Pass `parentId` to reply under an existing top-level comment
        (one level of threading — a reply to a reply attaches to the same parent).

        Create-only and append-only, so it is safe for restricted ops keys — the
        same channel the ops loop and Jarvis use to leave a note on an item.
      tags:
        - Comments
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: handle
          in: path
          required: true
          description: Per-project item number (e.g. `7`) or the full ops item id.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOpsCommentRequest'
            examples:
              comment:
                summary: Leave a comment
                value:
                  body: Repro'd on iOS Safari 17 — the button overflows its container. cc @alice
              reply:
                summary: Reply under an existing comment
                value:
                  body: Agreed, let's ship the fix behind @shipeasy's suggested flag.
                  parentId: cm_01j7w8a1b2c3d4e5f6g7h8i9j0
      responses:
        '201':
          description: Comment on an item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOpsCommentResponse'
              example:
                id: cm_01j7w8a1b2c3d4e5f6g7h8i9j0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: create
        positional:
          - handle
  /api/admin/notifications:
    post:
      operationId: notifyOps
      summary: Raise an attention notification
      description: |-
        Raise a 'needs your attention' bell notification. Create-only and idempotent on `dedupeKey` — re-raising with the same key updates the one card instead of stacking duplicates. It never reads, marks read, or deletes the feed, so it is safe for restricted ops keys.

        **Use case:** Escalate work that can't land in code (a product decision, a credential only a human has, a resource only a human may edit), deduped so repeats don't spam the bell.
      tags:
        - Ops
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotifyOpsRequest'
            example:
              title: 'Alert rule @alert:checkout-error-rate needs a human edit for #42'
              summary: '#42 is a false positive — the rule fires on the expected nightly batch spike, and rule definitions can only be edited by a human.'
              steps:
                - Open @alert:checkout-error-rate in the dashboard alerts page.
                - Raise the threshold from `2%` to `5%` and widen the window to `1h`.
                - 'Re-run the shipeasy-ops-work loop — #42 will be acknowledged.'
              dedupeKey: feedback:42
              href: /dashboard/prj_0abc/bugs/42
      responses:
        '201':
          description: Raise an attention notification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotifyOpsResponse'
              example:
                dedupeKey: error:checkout:5xx
                dispatched: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - VALIDATION
      x-cli:
        name: notify
  /api/admin/slack/channels:
    get:
      operationId: listSlackChannels
      summary: List Slack channels
      description: |-
        List the project's connected Slack channels — used to resolve an alert rule's notification target.

        **Use case:** Populate a channel picker, or validate an alert rule's `--slack-channel` before saving.
      tags:
        - Alerts
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: List Slack channels
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSlackChannelsResponse'
              example:
                connected: true
                channels:
                  - id: C0123
                    name: alerts
                  - id: C0456
                    name: general
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: channels
  /api/admin/alert-rules:
    get:
      operationId: listAlertRules
      summary: List alert rules
      description: |-
        Returns every alert rule in the project (not paginated). Each rule carries its bound `metricId`, the denormalised `metricName` (or `null` if the metric was removed), the comparator/threshold/window, severity, enabled flag, and delivery target.

        **Use case:** Audit which metrics have alerting configured — for example to confirm an on-call threshold is set before a launch.
      tags:
        - Alerts
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/Q'
      responses:
        '200':
          description: List alert rules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAlertRulesResponse'
              example:
                - id: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
                  name: Checkout error rate
                  metricId: met_01j6abc2d3e4f5g6h7i8j9k0l1
                  metricName: checkout_errors
                  comparator: gt
                  threshold: 50
                  windowHours: 24
                  severity: warn
                  enabled: true
                  notify: null
                  createdAt: '2026-04-12T10:14:08.000Z'
                  updatedAt: '2026-04-12T10:14:08.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: list
    post:
      operationId: createAlertRule
      summary: Create an alert rule
      description: |-
        Creates a metric-threshold alert rule. `name`, `metricId`, `comparator`, and `threshold` are required; `windowHours` defaults to `24`, `severity` to `warn`, and `enabled` to `true`.

        Returns `404` if `metricId` does not resolve, and `400` for a metric with no scalar form over a window (e.g. retention metrics) — the cron can't evaluate those.

        **Use cases**

        - **Threshold alert** — warn when an error/latency metric crosses a value over a rolling window.
        - **Routed alert** — set `notify` to page a specific Slack channel or on-call email instead of the project default.
      tags:
        - Alerts
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAlertRuleRequest'
            examples:
              minimal:
                summary: Minimal — alert when a metric exceeds a threshold
                description: Smallest valid body. Warns when the metric exceeds 50 over the default 24h window, with no per-rule delivery target.
                value:
                  name: Checkout error rate
                  metricId: met_01j6abc2d3e4f5g6h7i8j9k0l1
                  comparator: gt
                  threshold: 50
              targeted:
                summary: Full — custom window, severity, and Slack/email target
                description: A `danger` rule over a 1h window that posts to a Slack channel and emails on-call. The Slack channel must come from a connected connector.
                value:
                  name: Checkout error spike
                  metricId: met_01j6abc2d3e4f5g6h7i8j9k0l1
                  comparator: gt
                  threshold: 100
                  windowHours: 1
                  severity: danger
                  notify:
                    slackChannel:
                      id: C0123ABCD
                      name: incidents
                    email: oncall@acme.com
      responses:
        '201':
          description: Create an alert rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAlertRuleResponse'
              example:
                id: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
          links:
            UpdateAlertRule:
              operationId: updateAlertRule
              parameters:
                id: $response.body#/id
            DeleteAlertRule:
              operationId: deleteAlertRule
              parameters:
                id: $response.body#/id
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - ALREADY_EXISTS
        - METRIC_NOT_FOUND
        - REFERENCED_NOT_FOUND
        - VALIDATION
      x-cli:
        name: create
  /api/admin/alert-rules/{id}:
    patch:
      operationId: updateAlertRule
      summary: Update an alert rule
      description: |-
        Partial update of a rule's tunable knobs. `metricId` is immutable — the metric also pins the aggregation, so a body carrying `metricId` is rejected with `409 IMMUTABLE_FIELD`; create a new rule bound to the other metric instead (rule deletion is dashboard-only).

        Pass `"notify": null` to revert the rule's delivery target back to the project default.

        **Use cases**

        - **Tune sensitivity** — change `threshold`/`comparator`/`windowHours` as the metric's baseline shifts.
        - **Pause without losing config** — `{ "enabled": false }` instead of deleting the rule.
      tags:
        - Alerts
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque alert-rule id (`ar_…`) or the rule's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAlertRuleRequest'
            examples:
              raiseThreshold:
                summary: Raise the threshold
                description: Bump the alerting threshold without touching anything else.
                value:
                  threshold: 100
              disable:
                summary: Disable the rule
                description: Stop the cron from evaluating the rule.
                value:
                  enabled: false
              clearTarget:
                summary: Revert to the project default target
                description: Drop the per-rule Slack/email target and fall back to project defaults.
                value:
                  notify: null
      responses:
        '200':
          description: Update an alert rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateAlertRuleResponse'
              example:
                id: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - IMMUTABLE_FIELD
        - VALIDATION
      x-cli:
        name: update
        positional:
          - id
    delete:
      operationId: deleteAlertRule
      summary: Delete an alert rule
      description: |-
        Deletes the alert rule. The cron stops evaluating it immediately. Use this (then create a new rule) to repoint alerting at a different metric, since `metricId` is immutable.

        **Use case:** Remove an alert rule that is no longer needed, or as the first half of repointing a rule at a different metric.
      tags:
        - Alerts
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque alert-rule id (`ar_…`) or the rule's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Delete an alert rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteAlertRuleResponse'
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: archive
        positional:
          - id
  /api/admin/projects/current:
    get:
      operationId: getCurrentProject
      summary: Show the current project
      description: |-
        Returns the project the caller's auth header resolves to — plan, status, billing, and which modules are enabled. The server reads the project from the credential, so there is no id parameter. Powers `whoami`.

        **Use case:** Resolve who you are — the project, plan, and enabled modules tied to the current credential — without passing an id. Backs a registry-driven `whoami`.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Show the current project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCurrentProjectResponse'
              example:
                id: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
                name: Acme
                domain: acme.com
                ownerEmail: owner@acme.com
                plan: pro
                status: active
                subscriptionStatus: active
                billingInterval: monthly
                currentPeriodEnd: '2026-07-12T00:00:00.000Z'
                trialEndsAt: null
                cancelAtPeriodEnd: 0
                moduleTranslations: true
                moduleConfigs: true
                moduleGates: true
                moduleExperiments: true
                moduleFeedback: true
                createdAt: '2026-04-12T10:14:08.000Z'
                updatedAt: '2026-06-12T08:01:55.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: current
        topLevelAlias: whoami
  /api/admin/projects/upsert:
    post:
      operationId: upsertProject
      summary: Find-or-create a project by domain
      description: |-
        Find-or-creates a project keyed by `(owner_email, domain)` under the session's owner, and returns it. Idempotent: a second call with the same domain returns the existing project with `created: false`.

        Only `domain` is required — `name` defaults to the domain on first create. Recording the result in a local `.shipeasy` binding is a consumer side-effect; this endpoint never performs it.

        **Use cases**

        - **Install flow** — provision a per-app project without a trip to the dashboard. Run it on every install; the idempotent key means a re-run returns the existing project rather than duplicating it.
        - **Name explicitly** — pass `name` to label the project distinctly from its `domain`.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertProjectRequest'
            examples:
              minimal:
                summary: Minimal — domain only
                description: Smallest valid body. Names the project after the domain on first create.
                value:
                  domain: acme.com
              named:
                summary: Named project
                description: Supply a human-readable `name` distinct from the domain.
                value:
                  domain: shouks.app
                  name: Shouks
      responses:
        '200':
          description: Find-or-create a project by domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertProjectResponse'
              example:
                id: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
                name: Acme
                domain: acme.com
                owner_email: owner@acme.com
                created: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - VALIDATION
      x-cli:
        name: upsert
  /api/admin/projects/{id}:
    patch:
      operationId: updateProject
      summary: Update the current project
      description: |-
        Update the current project's settings — name, domain, slug, default environment, timezone, experiment-analysis knobs (statistical method, significance threshold, auto-rollback, minimum sample days), and the per-module enable flags. Partial: only the fields you send change.

        The project id in the path must match the project the caller's credential resolves to (a credential can only edit its own project). Changing `domain` re-stamps the allowed origin into every live SDK key.

        **Use case:** Rename a project, move its domain, toggle a module on/off, or tune the experiment-analysis defaults without leaving the CLI.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque project id. Must match the caller's own project.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectRequest'
            examples:
              rename:
                summary: Rename the project
                value:
                  name: Acme Rockets
              toggleModule:
                summary: Turn a module off
                value:
                  moduleExperiments: false
      responses:
        '200':
          description: The updated project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCurrentProjectResponse'
              example:
                id: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
                name: Acme Rockets
                domain: acme.com
                ownerEmail: owner@acme.com
                plan: pro
                status: active
                subscriptionStatus: active
                billingInterval: monthly
                currentPeriodEnd: '2026-07-12T00:00:00.000Z'
                trialEndsAt: null
                cancelAtPeriodEnd: 0
                moduleTranslations: true
                moduleConfigs: true
                moduleGates: true
                moduleExperiments: false
                moduleFeedback: true
                createdAt: '2026-04-12T10:14:08.000Z'
                updatedAt: '2026-06-12T08:01:55.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: update
        positional:
          - id
  /api/admin/i18n/profiles:
    get:
      operationId: listI18nProfiles
      summary: List i18n profiles
      description: |-
        Returns every locale profile in the project (e.g. `en:prod`, `fr:prod`).

        **Use case:** Discover which locale profiles exist before pushing keys or publishing a chunk.
      tags:
        - Profiles
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: List i18n profiles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListI18nProfilesResponse'
              example:
                - id: i18n_01j7w8a1b2c3
                  name: en:prod
                  locales:
                    - en
                  default_locale: en
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: list
    post:
      operationId: createI18nProfile
      summary: Create an i18n profile
      description: |-
        Create a locale profile. `name` is the stable handle (e.g. `fr:prod`).

        **Use case:** Stand up a new locale before seeding its keys.
      tags:
        - Profiles
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateI18nProfileRequest'
            example:
              name: fr:prod
              locales:
                - fr
              default_locale: fr
      responses:
        '201':
          description: Create an i18n profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateI18nProfileResponse'
              example:
                id: i18n_01j7w8a1b2c4
                name: fr:prod
          links:
            PublishI18nProfile:
              operationId: publishI18nProfile
              parameters:
                profileId: $response.body#/id
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - ALREADY_EXISTS
        - VALIDATION
      x-cli:
        name: create
  /api/admin/i18n/keys:
    get:
      operationId: listI18nKeys
      summary: List i18n keys
      description: |-
        List keys for a profile, optionally filtered to a name `prefix`.

        **Use case:** Read the current keys (and values) for a profile — e.g. to diff before a push.
      tags:
        - Keys
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: profile_id
          in: query
          required: false
          description: Profile id to list keys for.
          schema:
            type: string
        - name: prefix
          in: query
          required: false
          description: Only keys whose name starts with this.
          schema:
            type: string
        - name: q
          in: query
          required: false
          description: Free-text search — matches keys whose name, value, OR description contains this substring (case-insensitive). Use it to find the key behind a piece of on-screen copy.
          schema:
            type: string
            maxLength: 100
        - name: limit
          in: query
          required: false
          description: Max keys to return (1–500).
          schema:
            type: integer
            minimum: 1
            maximum: 500
        - name: offset
          in: query
          required: false
          description: Number of keys to skip before returning `limit` rows (offset pagination).
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: List i18n keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListI18nKeysResponse'
              example:
                keys:
                  - id: key_01j7
                    key: checkout.cta
                    value: Buy now
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: list
    post:
      operationId: pushI18nKeys
      summary: Push new i18n keys (insert-only)
      description: |-
        Add NEW keys to a profile. Insert-only — existing keys are left untouched (overwrite one with `updateI18nKey`).

        **Use case:** Seed newly-extracted keys without clobbering translations already in the profile.
      tags:
        - Keys
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PushI18nKeysRequest'
            example:
              profile_id: i18n_01j7w8a1b2c3
              keys:
                - key: checkout.cta
                  value: Buy now
      responses:
        '201':
          description: Push new i18n keys (insert-only)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushI18nKeysResponse'
              example:
                added:
                  - checkout.cta
                skipped: []
                pushed_count: 1
                skipped_count: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - ALREADY_EXISTS
        - VALIDATION
      x-cli:
        name: push
  /api/admin/i18n/keys/{id}:
    put:
      operationId: updateI18nKey
      summary: Update one i18n key
      description: |-
        Overwrite a single existing key's value — the only overwrite path.

        The change goes live on its own: the profile's KV snapshot is rebuilt and the CDN purged as part of this call, so no separate profile publish is needed.

        **Use case:** Correct or re-translate a single string in place.
      tags:
        - Keys
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: The key's id.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateI18nKeyRequest'
            example:
              value: Buy it now
      responses:
        '200':
          description: Update one i18n key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateI18nKeyResponse'
              example:
                id: key_01j7
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: update
        positional:
          - id
  /api/admin/i18n/drafts:
    get:
      operationId: listI18nDrafts
      summary: List translation drafts
      description: |-
        List staged translation drafts awaiting review/publish.

        **Use case:** Review machine-translation drafts before publishing them to a locale.
      tags:
        - Drafts
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: List translation drafts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListI18nDraftsResponse'
              example:
                - id: draft_01j7
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: list
    post:
      operationId: createI18nDraft
      summary: Create a translation draft
      description: |-
        Stage a new translation draft against a target profile, optionally seeding its keys from a source profile.

        **Use case:** Open a machine-translation draft for review before publishing it to a locale.
      tags:
        - Drafts
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateI18nDraftRequest'
            example:
              name: fr:prod
              profile_id: 3f1a6c2e-1b2c-4d5e-8f90-0a1b2c3d4e5f
      responses:
        '200':
          description: Create a translation draft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/I18nDraft'
              example:
                id: draft_01j7
                name: fr:prod
                profileId: 3f1a6c2e-1b2c-4d5e-8f90-0a1b2c3d4e5f
                status: open
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: create
  /api/admin/i18n/drafts/{draftId}:
    patch:
      operationId: updateI18nDraft
      summary: Update a translation draft
      description: |-
        Transition a draft's lifecycle state (`open` / `merged` / `abandoned`).

        **Use case:** Mark a reviewed draft as merged, or abandon one that should not ship.
      tags:
        - Drafts
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: draftId
          in: path
          required: true
          description: The draft id to update.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateI18nDraftRequest'
            example:
              status: merged
      responses:
        '200':
          description: Update a translation draft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/I18nDraft'
              example:
                id: draft_01j7
                status: merged
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: update
        positional:
          - draftId
  /api/admin/i18n/profiles/{profileId}/publish:
    post:
      operationId: publishI18nProfile
      summary: Publish a profile live
      description: |-
        Publish a profile to the CDN — rebuild its KV snapshot + purge the edge. Publishing is PROFILE-WIDE: the whole profile is snapshotted into one KV blob, so the optional `chunk` in the body is an audit label only (it does not scope what ships).

        **Use case:** Ship the latest translations live after pushing/updating keys.
      tags:
        - Profiles
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: profileId
          in: path
          required: true
          description: The profile id to publish.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishI18nProfileRequest'
            example:
              chunk: default
      responses:
        '200':
          description: Publish a profile chunk
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishI18nProfileResponse'
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: publish
        positional:
          - profileId
  /api/admin/i18n/set:
    post:
      operationId: setI18nLabel
      summary: Set a key's value and publish it live
      description: |-
        Upsert a single key's value into a profile and immediately publish the whole profile (KV rebuild + CDN purge) so the new value is live in one call. The key is inserted when new and overwritten when it already exists. `profile` is a profile name — omit it to target the project's default-marked profile, or pass a name to target another locale.

        **Use case:** Correct or replace one live string and ship it without a separate `push` + `publish`.
      tags:
        - Keys
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetI18nLabelRequest'
            example:
              key: home.cta
              value: Get started
      responses:
        '200':
          description: Set a key's value and publish it live
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetI18nLabelResponse'
              example:
                ok: true
                profile: en:prod
                key: home.cta
                value: Get started
                version: '7'
                key_count: 42
                changed: true
                purged: purged
                kv_verified: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: set
        positional:
          - key
          - value
  /api/admin/errors:
    get:
      operationId: listErrors
      summary: List tracked errors
      description: |-
        Returns a single page of tracked production errors as a **bare JSON array** (no pagination envelope), ordered by `lastSeenAt desc`. Filter with `status`, free-text-search with `q`, and cap the page with `limit`.

        Tracked errors are never filed by hand — an ingestion path (worker log drain / the `see()` SDK reporter) folds each occurrence into a row keyed by `fingerprint`, bumping `count` and `lastSeenAt`. This surface only reads them and (via PATCH) flips their `status`.

        **Use case:** Snapshot the project's open issues for a triage dashboard, or drive a CI gate that fails the build when any `open` error of `kind: uncaught` exists in `prod`.
      tags:
        - Errors
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: status
          in: query
          required: false
          description: Filter by triage state. `all` (the default) returns every status.
          schema:
            type: string
            enum:
              - open
              - resolved
              - ignored
              - all
            default: all
        - name: q
          in: query
          required: false
          description: Case-insensitive substring match against `message`, `errorType`, and `subject`.
          schema:
            type: string
            maxLength: 200
        - name: limit
          in: query
          required: false
          description: Maximum number of rows to return (1–500). Defaults to 200.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 200
      responses:
        '200':
          description: List tracked errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListErrorsResponse'
              example:
                - id: err_01j7w7m9q4hxbf6npe6s9zr3vc
                  projectId: e976b15e-2f0d-4c6e-9b1a-3a7c1f2d8e90
                  fingerprint: 9c1f4f1f2c0c4a5fa1c2b6d3e7c8e3a1
                  causedByFingerprint: null
                  message: Cannot read properties of undefined (reading 'id')
                  errorType: TypeError
                  stack: |-
                    TypeError: Cannot read properties of undefined (reading 'id')
                        at GateEditor (/app/gates/[id]/page.tsx:42:18)
                  source: shipeasy
                  url: https://app.example.com/dashboard/gat_01j7/edit
                  seenUrls: '["https://app.example.com/dashboard/#/edit"]'
                  subject: gate editor
                  outcome: crash on load
                  side: client
                  env: prod
                  kind: uncaught
                  lastExtrasJson: '{"gateId":"gat_01j7"}'
                  sdkVersion: 6.0.0
                  count: 137
                  status: open
                  firstSeenAt: '2026-06-20T08:11:02.000Z'
                  lastSeenAt: '2026-06-28T14:55:31.000Z'
                  createdAt: '2026-06-20T08:11:02.000Z'
                  updatedAt: '2026-06-28T14:55:31.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: list
  /api/admin/errors/{id}:
    get:
      operationId: getError
      summary: Get a tracked error
      description: |-
        Returns a single tracked error by its id, including the latest occurrence's stack, extras, and consequence. Returns `404` if no such error exists in the project.

        **Use case:** Drill into one issue — fetch its full stack and `seenUrls` to investigate, or to render the detail panel behind a row in the errors list.
      tags:
        - Errors
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque error id (`err_…`).
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Get a tracked error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRecord'
              example:
                id: err_01j7w7m9q4hxbf6npe6s9zr3vc
                projectId: e976b15e-2f0d-4c6e-9b1a-3a7c1f2d8e90
                fingerprint: 9c1f4f1f2c0c4a5fa1c2b6d3e7c8e3a1
                causedByFingerprint: null
                message: Cannot read properties of undefined (reading 'id')
                errorType: TypeError
                stack: |-
                  TypeError: Cannot read properties of undefined (reading 'id')
                      at GateEditor (/app/gates/[id]/page.tsx:42:18)
                source: shipeasy
                url: https://app.example.com/dashboard/gat_01j7/edit
                seenUrls: '["https://app.example.com/dashboard/#/edit"]'
                subject: gate editor
                outcome: crash on load
                side: client
                env: prod
                kind: uncaught
                lastExtrasJson: '{"gateId":"gat_01j7"}'
                sdkVersion: 6.0.0
                count: 137
                status: open
                firstSeenAt: '2026-06-20T08:11:02.000Z'
                lastSeenAt: '2026-06-28T14:55:31.000Z'
                createdAt: '2026-06-20T08:11:02.000Z'
                updatedAt: '2026-06-28T14:55:31.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: get
        positional:
          - id
    patch:
      operationId: updateErrorStatus
      summary: Update a tracked error's status
      description: |-
        Flips the triage state of one error — the only mutation this surface allows. Valid transitions are between `open`, `resolved`, and `ignored`; the body must carry exactly `{ "status": … }`.

        A `resolved` error reopens automatically (ingestion-side) if it recurs; `ignored` is sticky until flipped back here. Returns the updated row.

        **Use cases**

        - **Triage** — `{ "status": "ignored" }` to suppress a known-benign issue from the open list.
        - **Close out** — `{ "status": "resolved" }` once the fix lands; it reopens on its own if the error recurs.
      tags:
        - Errors
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque error id (`err_…`).
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateErrorStatusRequest'
            examples:
              resolve:
                summary: Mark resolved
                description: Close the error once the fix is deployed. It reopens automatically if it recurs.
                value:
                  status: resolved
              ignore:
                summary: Ignore a benign issue
                description: Suppress a known-benign error from the open list. Sticky until flipped back.
                value:
                  status: ignored
      responses:
        '200':
          description: Update a tracked error's status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRecord'
              example:
                id: err_01j7w7m9q4hxbf6npe6s9zr3vc
                projectId: e976b15e-2f0d-4c6e-9b1a-3a7c1f2d8e90
                fingerprint: 9c1f4f1f2c0c4a5fa1c2b6d3e7c8e3a1
                causedByFingerprint: null
                message: Cannot read properties of undefined (reading 'id')
                errorType: TypeError
                stack: null
                source: shipeasy
                url: https://app.example.com/dashboard/gat_01j7/edit
                seenUrls: null
                subject: gate editor
                outcome: crash on load
                side: client
                env: prod
                kind: uncaught
                lastExtrasJson: null
                sdkVersion: 6.0.0
                count: 137
                status: resolved
                firstSeenAt: '2026-06-20T08:11:02.000Z'
                lastSeenAt: '2026-06-28T14:55:31.000Z'
                createdAt: '2026-06-20T08:11:02.000Z'
                updatedAt: '2026-06-28T15:02:10.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: update
        positional:
          - id
  /api/admin/errors/{id}/file:
    post:
      operationId: fileErrorTicket
      summary: File a feedback ticket for an error
      description: |-
        Files a feedback ticket (`type: "error"`) for a tracked production error — the "File an issue" action on the errors dashboard. The ticket carries the error's fingerprint as its `sourceRef` so it dedupes against, and joins back to, the tracked error. Takes no body.

        Idempotent: if an open `error` ticket already tracks this fingerprint (hand- or auto-filed), that existing ticket is returned instead of creating a duplicate. Returns `404` if the error does not exist.

        **Use case:** Promote a noisy tracked error into an actionable ticket in the ops queue (the same item the worker auto-files once an error crosses its occurrence threshold), so it can be triaged, assigned, and burned down via the `shipeasy-ops-work` skill.
      tags:
        - Errors
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque error id (`err_…`).
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '201':
          description: File a feedback ticket for an error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileErrorTicketResponse'
              example:
                id: 3f2a9b1c-7d4e-4a8f-9c2b-1e5d6f7a8b90
                number: 42
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: file
        positional:
          - id
  /api/admin/errors/{id}/series:
    post:
      operationId: getErrorSeries
      summary: Get an error's occurrence series
      description: |-
        Returns a bucketed occurrence timeseries for one tracked error (by its fingerprint), read from the `shipeasy_errors` Analytics Engine dataset (near-real-time; ingest lag is seconds). The window bounds are epoch **seconds**; `to` must be strictly greater than `from`. The response echoes the SQL that produced the rows.

        **Use case:** Render the trend sparkline / occurrence chart on the error detail panel, or pull the raw bucketed counts to alert when an issue's rate spikes.
      tags:
        - Errors
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque error id (`err_…`).
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ErrorSeriesRequest'
            examples:
              lastDayHourly:
                summary: Last 24h, hourly buckets
                description: Hourly occurrence counts over a one-day window (bounds in epoch seconds).
                value:
                  from: 1751000400
                  to: 1751086800
                  bucket: 3600
      responses:
        '200':
          description: Get an error's occurrence series
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSeriesResponse'
              example:
                sql: |-
                  SELECT intDiv(toUInt32(double2), 3600) * 3600 AS t,
                    sum(double1 * _sample_interval) AS v
                  FROM shipeasy_errors
                  WHERE index1 = 'e976b15e-2f0d-4c6e-9b1a-3a7c1f2d8e90'
                    AND blob1 = '9c1f4f1f2c0c4a5fa1c2b6d3e7c8e3a1'
                    AND double2 >= 1751000400 AND double2 < 1751086800
                  GROUP BY t
                  ORDER BY t
                rows:
                  - t: 1751000400
                    v: 12
                  - t: 1751004000
                    v: 31
                  - t: 1751007600
                    v: 27
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: series
        positional:
          - id
  /api/admin/connectors:
    get:
      operationId: listConnectors
      summary: List connectors
      description: |-
        Returns every connector in the project as a bare array (no pagination envelope).

        The encrypted credentials backing each connector are never serialised — only the connector's non-secret `config`, `accountLabel`, and last-attempt health (`lastError`, `lastAttemptAt`, `lastSuccessAt`) are returned.

        **Use case:** Render the integrations/triggers settings page, or drive a CI check that asserts every `github` connector is `enabled` and last dispatched without error.
      tags:
        - Connectors
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/Q'
      responses:
        '200':
          description: List connectors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListConnectorsResponse'
              example:
                - id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
                  projectId: prj_01j7w7m9q4hxbf6npe6s9zr3vc
                  provider: github
                  name: Bugs → acme/app issues
                  enabled: true
                  events:
                    - bug.created
                  config:
                    owner: acme
                    repo: app
                  accountLabel: acme/app
                  lastError: null
                  lastAttemptAt: '2026-06-27T18:04:11.000Z'
                  lastSuccessAt: '2026-06-27T18:04:11.000Z'
                  createdAt: '2026-06-01T09:12:00.000Z'
                  updatedAt: '2026-06-27T18:04:11.000Z'
                - id: 2d44f0aa-9c81-4e6b-8a17-7b3e0f9c1a22
                  projectId: prj_01j7w7m9q4hxbf6npe6s9zr3vc
                  provider: claude_trigger
                  name: Nightly ops sweep
                  enabled: true
                  events: []
                  config:
                    routineId: rtn_8fk20
                  accountLabel: rtn_8fk20
                  lastError: null
                  lastAttemptAt: null
                  lastSuccessAt: null
                  createdAt: '2026-06-20T22:00:00.000Z'
                  updatedAt: '2026-06-20T22:00:00.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: list
    post:
      operationId: createConnector
      summary: Create a connector
      description: |-
        Creates a connector. The request body is discriminated on `provider`.

        - **OAuth/app providers** (`google_sheets`, `github`, `slack`) — supply `{ provider, name, events }`. The connector is created `enabled: false` with empty `config` and no credentials; the provider's OAuth flow then attaches credentials and enables it.
        - **Trigger providers** (`claude_trigger`, `cursor_trigger`, `copilot_trigger`, `jules_trigger`) — supply `config` plus the provider's credential field(s) and the connector is fireable immediately. Trigger creates are **idempotent** by their natural key (`config.routineId` / `config.repoUrl` / `config.owner`+`config.repo` / `config.source`): re-creating updates the existing row rather than duplicating it.

        **Use cases**

        - **File bugs as GitHub Issues** — `{ "provider": "github", "name": "Bugs → acme/app", "events": ["bug.created"] }`, then finish the GitHub App install.
        - **Nightly ops sweep** — register a `claude_trigger` with its `routineId` and (optionally) a fire `token`; subscribe `events` later to auto-fire on new bugs.
        - **Cold cloud-agent run** — register a `cursor_trigger`/`jules_trigger` with the repo coordinates plus both keys, or a `copilot_trigger` with the repo + user PAT.
      tags:
        - Connectors
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConnectorRequest'
            examples:
              githubStub:
                summary: GitHub — OAuth/app stub
                description: Creates a disabled `github` connector subscribed to `bug.created`. Finish the GitHub App install to attach credentials and enable it.
                value:
                  provider: github
                  name: Bugs → acme/app issues
                  events:
                    - bug.created
              claudeTrigger:
                summary: Claude trigger — tokened
                description: Registers a Claude Code routine trigger with its fire token. Idempotent by `config.routineId`. `events` left empty so it does not auto-fire paid runs yet.
                value:
                  provider: claude_trigger
                  name: Nightly ops sweep
                  config:
                    routineId: rtn_8fk20
                    fireText: Burn down the open bug + feature-request queue.
                  token: rtk_live_3f9a…
              cursorTrigger:
                summary: Cursor trigger — cold cloud agent
                description: 'Both keys required up front: the Cursor `apiKey` launches the run, the `opsKey` is injected as SHIPEASY_CLI_TOKEN. Idempotent by `config.repoUrl`.'
                value:
                  provider: cursor_trigger
                  name: Cursor ops agent
                  config:
                    repoUrl: https://github.com/acme/app
                    projectId: prj_01j7w7m9q4hxbf6npe6s9zr3vc
                  apiKey: cur_live_…
                  opsKey: ops_…
      responses:
        '201':
          description: Create a connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateConnectorResponse'
              example:
                id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
          links:
            GetConnector:
              operationId: getConnector
              parameters:
                id: $response.body#/id
            UpdateConnector:
              operationId: updateConnector
              parameters:
                id: $response.body#/id
            TestConnector:
              operationId: testConnector
              parameters:
                id: $response.body#/id
            DeleteConnector:
              operationId: deleteConnector
              parameters:
                id: $response.body#/id
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - UNAUTHORIZED
        - FORBIDDEN
        - VALIDATION
      x-cli:
        name: create
  /api/admin/connectors/{id}:
    get:
      operationId: getConnector
      summary: Get a connector
      description: |-
        Returns a single connector by id. The encrypted credentials are never serialised.

        **Use case:** Inspect one connector's health — its `enabled` state, subscribed `events`, and last-attempt outcome (`lastError`/`lastSuccessAt`).
      tags:
        - Connectors
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque connector id.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Get a connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorRecord'
              example:
                id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
                projectId: prj_01j7w7m9q4hxbf6npe6s9zr3vc
                provider: github
                name: Bugs → acme/app issues
                enabled: true
                events:
                  - bug.created
                config:
                  owner: acme
                  repo: app
                accountLabel: acme/app
                lastError: null
                lastAttemptAt: '2026-06-27T18:04:11.000Z'
                lastSuccessAt: '2026-06-27T18:04:11.000Z'
                createdAt: '2026-06-01T09:12:00.000Z'
                updatedAt: '2026-06-27T18:04:11.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: get
        positional:
          - id
    patch:
      operationId: updateConnector
      summary: Update a connector
      description: |-
        Partial update — only supplied fields change. `events` and `config` **replace** wholesale; there is no merge or append. Secrets cannot be set through this endpoint (credential rotation goes through the provider-specific re-register flow).

        The response carries only `{ id }` — re-fetch via `GET /api/admin/connectors/{id}` for the new row.

        **Use cases**

        - **Pause a connector** — `{ "enabled": false }`. Stops all dispatch / auto-fire without deleting it.
        - **Change subscribed events** — send the full new `events` array. An empty array unsubscribes the connector from every event.
        - **Rename** — `{ "name": "Bugs → acme/app issues" }`.
        - **Retarget** — send a new `config` (e.g. a different Sheets `sheetTitle`); it replaces the stored config wholesale.
      tags:
        - Connectors
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque connector id.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConnectorRequest'
            examples:
              pause:
                summary: Pause — disable the connector
                description: 'Stops all dispatch / auto-fire. Re-enable with `{ "enabled": true }`.'
                value:
                  enabled: false
              resubscribe:
                summary: Replace subscribed events
                description: Array fields replace wholesale. Send the full new list; an empty array unsubscribes from everything.
                value:
                  events:
                    - bug.created
                    - feature_request.created
              retarget:
                summary: Retarget config
                description: Replaces the stored non-secret config wholesale.
                value:
                  config:
                    spreadsheetId: 1AbC…
                    sheetTitle: Bugs Q3
      responses:
        '200':
          description: Update a connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateConnectorResponse'
              example:
                id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: update
        positional:
          - id
    delete:
      operationId: deleteConnector
      summary: Delete a connector
      description: |-
        Permanently removes the connector and its stored credentials.

        **Use case:** Disconnect an integration for good — e.g. tear down a `github` connector after migrating bug routing elsewhere.
      tags:
        - Connectors
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque connector id.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Delete a connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteConnectorResponse'
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: archive
        positional:
          - id
  /api/admin/connectors/{id}/fire:
    post:
      operationId: fireConnector
      summary: Fire a trigger connector
      description: |-
        Manually kicks a trigger connector's run — Claude (kicks its preconfigured routine) or Cursor / Copilot / Jules (launches a cold cloud-agent run). Firing is event-less: it kicks the run with an optional caller-supplied prompt override rather than dispatching a single lifecycle payload.

        Only trigger providers can be fired, and only once authenticated (a tokenless trigger cannot fire). The attempt's outcome is recorded on the connector's `lastAttemptAt` / `lastError` / `lastSuccessAt`.

        **Use case:** Kick a one-off ops sweep on demand from the dashboard's "Fire now" button, optionally overriding the routine's default prompt.
      tags:
        - Connectors
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque connector id.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FireConnectorRequest'
            examples:
              default:
                summary: Fire with the provider default prompt
                description: Empty body — kicks the run with the provider's own default (Claude → configured `fireText`, others → built cold-start prompt).
                value: {}
              override:
                summary: Fire with a prompt override
                value:
                  text: Triage only the P0 bugs reported in the last 24h.
      responses:
        '200':
          description: The trigger run was successfully kicked off.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FireConnectorResponse'
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '502':
          $ref: '#/components/responses/BadGateway'
      x-error-codes:
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: fire
        positional:
          - id
  /api/admin/connectors/{id}/test:
    post:
      operationId: testConnector
      summary: Test a connector
      description: |-
        Dispatches a single synthetic `bug.created` payload to the connector's destination so you can verify the integration end-to-end. Unlike `fire`, this runs the real dispatch path (posts a Slack message / appends a Sheets row / files a GitHub Issue) with throwaway test content. The attempt's outcome is recorded on the connector's `lastAttemptAt` / `lastError` / `lastSuccessAt`.

        When the provider produces a linkable artifact (e.g. a GitHub Issue), its URL is returned as `issueUrl`; otherwise `issueUrl` is `null`.

        **Use case:** Click "Send test" after wiring up a connector to confirm credentials and config are correct before relying on it for real events.
      tags:
        - Connectors
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque connector id.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: The test dispatch reached the destination.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestConnectorResponse'
              example:
                ok: true
                issueUrl: https://github.com/acme/app/issues/4217
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '502':
          $ref: '#/components/responses/BadGateway'
      x-error-codes:
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: test
        positional:
          - id
  /api/admin/connectors/{id}/trigger:
    patch:
      operationId: updateTriggerConnector
      summary: Update a trigger connector
      description: |-
        Edit an existing coding-agent **trigger** connector (`claude_trigger` / `cursor_trigger` / `copilot_trigger` / `jules_trigger`) — replace its non-secret `config` and, optionally, rotate its credential secret(s). Discriminated on `provider`; the id in the path selects the connector and its `provider` must match the body.

        Unlike the generic `PATCH /api/admin/connectors/{id}` (which cannot touch secrets), this endpoint always replaces the non-secret `config` wholesale and merges any supplied secret over the stored credential cipher — so a single half of a two-key pair (e.g. just the ops key) can be rotated on its own. A blank/omitted secret leaves the stored cipher untouched.

        The response carries only `{ id }` — re-fetch via `GET /api/admin/connectors/{id}` for the new row.

        **Use case:** Re-point a Cursor trigger at a new repo ref, or rotate a Claude trigger's fire token, without deleting and re-creating the connector.
      tags:
        - Connectors
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque connector id. Its stored `provider` must match the body's `provider`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTriggerConnectorRequest'
            examples:
              claude:
                summary: Claude — repoint routine, rotate token
                description: Replaces the routine config and rotates the fire token.
                value:
                  provider: claude_trigger
                  config:
                    routineId: rtn_9f2c
                  token: fire_live_a1b2c3
              cursor:
                summary: Cursor — rotate just the ops key
                description: Leaves the launch key untouched, rotates only the restricted ops key.
                value:
                  provider: cursor_trigger
                  config:
                    repoUrl: https://github.com/acme/app
                    projectId: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
                  opsKey: sdk_ops_live_x9y8z7
      responses:
        '200':
          description: Update a trigger connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateConnectorResponse'
              example:
                id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: trigger
        positional:
          - id
  /api/admin/connectors/trigger:
    post:
      operationId: createTriggerConnector
      summary: Create a recurring coding-agent trigger
      description: |-
        Creates (or idempotently updates) a coding-agent **trigger** connector — the recurring, unattended run that burns down the ops queue in `--pr` mode. Discriminated on `provider`; only the four Shipeasy-fireable providers are accepted (`claude_trigger`, `cursor_trigger`, `copilot_trigger`, `jules_trigger`). Config + credential(s) arrive together; creates are idempotent by the provider's natural key, so re-creating updates the existing row.

        Platforms without a fire endpoint (Codex, Windsurf, Cline, OpenClaw, OpenCode, Continue) cannot be created here — they are scheduled on their own platform (typically a GitHub Actions `schedule:` cron running the platform's headless CLI with the trigger prompt).

        **Use cases**

        - **Register a Claude routine** — after `RemoteTrigger {action:"create"}` returns `trig_…`, `{ "provider": "claude_trigger", "config": { "routineId": "trig_…" } }` (tokenless is fine; add the fire token later).
        - **Cold Cursor/Jules run** — repo coordinates + both keys; Shipeasy launches the run and the PR opens via the provider's GitHub App.
        - **Copilot cloud agent** — repo + a Copilot-licensed user PAT with the "Agent tasks" permission.
      tags:
        - Trigger
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTriggerConnectorRequest'
            examples:
              claude:
                summary: Claude routine (tokenless)
                value:
                  provider: claude_trigger
                  name: Nightly ops sweep
                  config:
                    routineId: trig_8fk20
              cursor:
                summary: Cursor cold cloud agent
                value:
                  provider: cursor_trigger
                  name: Cursor ops agent
                  config:
                    repoUrl: https://github.com/acme/app
                    projectId: prj_01j7w7m9q4hxbf6npe6s9zr3vc
                  apiKey: cur_live_…
                  opsKey: ops_…
      responses:
        '201':
          description: Trigger connector created (or idempotently updated)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateConnectorResponse'
              example:
                id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
          links:
            FireConnector:
              operationId: fireConnector
              parameters:
                id: $response.body#/id
            TestConnector:
              operationId: testConnector
              parameters:
                id: $response.body#/id
            GetConnector:
              operationId: getConnector
              parameters:
                id: $response.body#/id
            UpdateTriggerConnector:
              operationId: updateTriggerConnector
              parameters:
                id: $response.body#/id
            DeleteConnector:
              operationId: deleteConnector
              parameters:
                id: $response.body#/id
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - UNAUTHORIZED
        - FORBIDDEN
        - VALIDATION
      x-cli:
        helpPreamble: |-
          A trigger is an unattended, scheduled agent run: on a cron cadence it runs the
          shipeasy-ops-work loop in --pr mode against your project — one atomic diff and
          ONE pull request per fixed item, nothing auto-merges.

          Whatever the provider, the scheduled run executes this trigger prompt (headless
          CLIs take it as the prompt; cloud agents as the task body):

            You are an unattended Shipeasy maintenance run. Authenticate every `shipeasy`
            call with these env vars (the CLI reads them directly — do NOT run
            `shipeasy login`, never echo the token). Put them at the top of EVERY shell
            invocation that calls `shipeasy`; each command runs in a fresh shell:

            export SHIPEASY_CLI_TOKEN="<OPS_KEY>"
            export SHIPEASY_PROJECT_ID="<PROJECT_ID>"

            Ensure the repo is bound: test -f .shipeasy || printf '{"project_id":"<PROJECT_ID>"}\n' > .shipeasy
            (never commit .shipeasy).

            Refresh to the latest plugin + CLI, then run the ops work loop in --pr mode:
              <PLUGIN-INSTALL-FOR-THIS-HOST>       # plugin install for claude/copilot, or `npx -y skills add …`
              npm install -g @shipeasy/cli@latest
            Then follow the installed shipeasy-ops-work (--pr) workflow verbatim: burn down
            the queue, one atomic diff per item, open ONE PR per item from a safe branch
            prefix, flip each to ready_for_qa, add "Closes #<issue>" where an item has a
            connected GitHub issue. If the queue is empty, exit cleanly. Never merge.

          <OPS_KEY> is a restricted `ops` key — mint with
          `npx -y @shipeasy/cli@latest keys create --type ops`. It reads the queue, flips
          status, links the PR it opens, and creates resources only; it can never edit or
          delete existing resources, and auto-extends its 7-day expiry on each run.
          <PROJECT_ID> comes from the bound .shipeasy. Never print either value.

          Safety: auto-approve flags (--approval-mode=yolo, --dangerously-skip-permissions,
          …) remove the human gate — run only in an isolated env. Unattended loops spend
          tokens/credits on a cadence: start weekly/daily and watch the first runs.
        commands:
          - name: create claude
            summary: Register a Claude Code scheduled routine as the trigger connector
            preset:
              provider: claude_trigger
            help: |-
              The reference implementation — a routine in Anthropic's cloud, no GitHub
              Actions. The routines API is reachable only by the agent's in-process
              RemoteTrigger tool, so provisioning is a hybrid split:

              1. `shipeasy ops trigger prep --frequency <4h|6h|daily|weekdays|weekly|cron>`
                 mints the restricted ops key, resolves repo + cron, and writes the exact
                 RemoteTrigger create body to a 0600 temp file (the key is never printed).
              2. The agent picks an environment_id from its RemoteTrigger env list — the
                 environment's network access must allow shipeasy.ai + api.shipeasy.ai
                 (Custom network; new envs default to Trusted, which fails every shipeasy
                 call) — then calls RemoteTrigger {action:"create"} and captures trig_….
                 Verify with {action:"run"} (confirm first — it spends tokens and may open
                 a real PR).
              3. Register the connector (idempotent by routineId; tokenless is fine):

                   shipeasy ops trigger create claude --config '{"routineId":"trig_…"}'

              The fire token ("Fire now" + event auto-fire) is web-UI-only: open
              https://claude.ai/code/routines → the routine → add an API trigger →
              Generate token, then re-run the create with --token <token> and optionally
              --events '["bug.created","feature_request.created"]' — the same row is
              upgraded in place. GitHub access is connected once via /web-setup or the
              Claude GitHub App. Manage/pause the routine at claude.ai/code/routines.
          - name: create cursor
            summary: Register a Cursor cloud-agent trigger (cold-fire; Shipeasy launches the run)
            preset:
              provider: cursor_trigger
            help: |-
              Cursor cloud agents are cold-fireable: one authenticated POST to
              https://api.cursor.com/v1/agents starts a run from nothing, and
              autoCreatePR opens the PR via Cursor's GitHub App. Registering the
              connector stores both credentials, so Shipeasy can fire it on demand and
              on subscribed events; the ops key rides the launch envVars (never the
              prompt):

                shipeasy ops trigger create cursor \
                  --config '{"repoUrl":"https://github.com/<owner>/<repo>","projectId":"<prj_…>"}' \
                  --api-key <CURSOR_API_KEY> --ops-key <ops_…>

              For a fixed cadence (nightly runs without new feedback) add a Cursor
              Automation (cursor.com/automations) with the same trigger prompt — cron +
              "Pull request creation" enabled. Note: Automations always run in Max Mode
              (billed on cloud-agent usage).
          - name: create copilot
            summary: Register a GitHub Copilot cloud-agent trigger
            preset:
              provider: copilot_trigger
            help: |-
              Copilot's cloud agent starts from one authenticated POST to
              https://api.github.com/agents/repos/<owner>/<repo>/tasks with
              { prompt, create_pull_request: true }. Auth is a user-to-server token
              ONLY: a fine-grained user PAT with the "Agent tasks" repo permission
              (read+write) for a Copilot-licensed account — the Actions GITHUB_TOKEN and
              GitHub App installation tokens are rejected. The agent reads
              SHIPEASY_CLI_TOKEN from the repo's own Agents secret store, so Shipeasy
              stores only the PAT:

                shipeasy ops trigger create copilot \
                  --config '{"owner":"<owner>","repo":"<repo>"}' --token <fine-grained PAT>

              Set SHIPEASY_CLI_TOKEN (the restricted ops key) + SHIPEASY_PROJECT_ID in
              the repo's Agents secrets first. For a fixed cadence use Copilot
              automations (repo Agents tab; hourly/daily/weekly, private/internal repos
              only) or a scheduled Actions job running `gh agent-task create`.
          - name: create jules
            aliases:
              - gemini
            summary: Register a Google Jules (Gemini) trigger
            preset:
              provider: jules_trigger
            help: |-
              Jules — Google's async coding agent (the fireable Gemini path) — starts a
              session from one POST to https://jules.googleapis.com/v1alpha/sessions
              (header X-Goog-Api-Key) with sourceContext.source =
              sources/github/<owner>/<repo> and automationMode: "AUTO_CREATE_PR". Jules
              exposes no env channel, so the restricted ops key is embedded in the
              session prompt (safe — it is the limited ops key):

                shipeasy ops trigger create jules \
                  --config '{"source":"sources/github/<owner>/<repo>"}' \
                  --api-key <JULES_API_KEY> --ops-key <ops_…>

              Connect the repo to Jules once (jules.google.com → connect GitHub). For a
              fixed cadence use Jules scheduled tasks (UI-only), or fall back to the
              Gemini CLI in a GitHub Actions schedule: job
              (`gemini -p "<TRIGGER PROMPT>" --approval-mode=yolo`; auth GEMINI_API_KEY).
        fallback:
          argument: provider
          platforms:
            - codex
            - windsurf
            - cline
            - openclaw
            - opencode
            - continue
          help: |-
            Direct (Shipeasy-fired) triggers are not supported for this platform — it
            exposes no HTTP "start a run" endpoint our Worker can call. Supported here:
            claude, cursor, copilot, jules (alias: gemini) — see
            `shipeasy ops trigger create <provider> --help`.

            Platform-scheduled setup instead (the platform's own scheduler fires the
            run; nothing to register in Shipeasy):

            1. Mint the restricted ops key (`shipeasy sdk keys create --type ops --json`)
               and read the project id from .shipeasy. Never print either.
            2. Build the trigger prompt (run `shipeasy ops trigger create claude --help`
               for the shared template) with the key, project id, and your platform's
               install line substituted.
            3. Schedule a headless run with it — a GitHub Actions `schedule:` cron
               (always-on; credentials as repo secrets incl. a GH_TOKEN/PAT with
               contents:write + pull-requests:write) or a local cron/daemon (machine
               must stay awake):

                 codex     GitHub Actions cron → `codex cloud exec --env <ENV_ID> "<PROMPT>"`
                           (submits a Codex Cloud task — machine-off; configure network +
                           SHIPEASY_* secrets once at chatgpt.com/codex/cloud/settings/environments)
                 windsurf  Devin Scheduled Sessions (cloud cron; WINDSURF/DEVIN API key)
                 cline     `cline schedule create --cron "…" --prompt "<PROMPT>"` (local daemon)
                 openclaw  `openclaw cron create "…" "<PROMPT>"` (local gateway; static API key)
                 opencode  `opencode run "<PROMPT>"` + external cron (permission: "allow")
                 continue  `cn -p --auto "<PROMPT>"` + external cron (CONTINUE_API_KEY)

            4. Verify one manual fire (expect a PR or a clean empty-queue exit) and
               manage/pause it on that platform's scheduler.
  /api/admin/keys:
    get:
      operationId: listKeys
      summary: List API keys
      description: |-
        Returns a single page of the project's API keys ordered by `created_at desc, id desc`, in the standard `{ data, next_cursor }` envelope. Use the `cursor` query parameter to paginate.

        Response fields are **snake_case** (`created_at`, `revoked_at`, `created_by_email`, `last4`). The raw token is never returned — only its `last4` tail, so a held key can be matched against the masked row. Revoked keys are included (with a non-null `revoked_at`).

        **Use case:** Audit which keys exist for a project — surface stale or never-expiring keys, or drive a CI check that asserts no `client` key is still active in `prod` after a rotation.
      tags:
        - API Keys
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/PaginationLimit'
        - $ref: '#/components/parameters/PaginationCursor'
        - $ref: '#/components/parameters/Q'
      responses:
        '200':
          description: List API keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListKeysResponse'
              example:
                data:
                  - id: 3f2a9b1c-7d4e-4a8f-9c2b-1e5d6f7a8b90
                    type: server
                    env: prod
                    created_at: '2026-05-09T16:01:22.000Z'
                    revoked_at: null
                    expires_at: null
                    created_by_email: ana@example.com
                    name: production back-end
                    scopes:
                      - gates:evaluate
                      - events:write
                    last4: a1b2
                next_cursor: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: list
    post:
      operationId: createKey
      summary: Create an API key
      description: |-
        Mints a new API key and returns the plaintext token **once** — it is stored hashed and can never be retrieved again, so capture it on creation.

        Only `type` is required. `env` is **required** for `server` and `client` keys (the key is bound to one environment, which is the read-env isolation boundary); for `admin` and `ops` keys `env` is ignored and the key is pinned to `prod`. Expiry is fixed for some types: `admin` keys always get a 90-day expiry and `ops` keys a short sliding window, regardless of `expiresInDays`. Only `server`/`client` keys count toward the plan key limit.

        **Use cases**

        - **Back-end key** — `{ "type": "server", "env": "prod" }` for the production server SDK.
        - **Public browser key** — `{ "type": "client", "env": "prod", "name": "marketing site" }` to embed in the browser SDK.
        - **Scoped, expiring key** — `{ "type": "server", "env": "staging", "scopes": ["gates:evaluate"], "expiresInDays": 30 }` for a time-boxed integration.
      tags:
        - API Keys
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateKeyRequest'
            examples:
              serverKey:
                summary: Server key — bound to an environment
                description: A back-end SDK key. `env` is required for `server`/`client` keys.
                value:
                  type: server
                  env: prod
                  name: production back-end
              scopedExpiring:
                summary: Scoped, expiring server key
                description: A time-boxed key limited to gate evaluation, expiring in 30 days.
                value:
                  type: server
                  env: staging
                  scopes:
                    - gates:evaluate
                  expiresInDays: 30
              opsKey:
                summary: Ops key — restricted, env-agnostic
                description: The unattended-trigger credential. `env` is ignored (pinned to `prod`); expiry is a short sliding window.
                value:
                  type: ops
      responses:
        '201':
          description: Create an API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateKeyResponse'
              example:
                id: 3f2a9b1c-7d4e-4a8f-9c2b-1e5d6f7a8b90
                type: server
                env: prod
                key: sdk_server_9c1f4f1f2c0c4a5fa1c2b6d3e7c8e3a1
                expires_at: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - UNAUTHORIZED
        - FORBIDDEN
        - VALIDATION
        - PLAN_LIMIT
      x-cli:
        name: create
  /api/admin/keys/{id}/revoke:
    post:
      operationId: revokeKey
      summary: Revoke an API key
      description: |-
        Revokes a key by id — stamps its `revoked_at` and deletes the hot-path KV entry so the token stops authenticating immediately. Takes no body.

        Idempotent: revoking an already-revoked key is a no-op and returns the same `{ id, revoked: true }`. Returns `404` if no such key exists in the project.

        **Use case:** Rotate a leaked or stale credential — mint the replacement, then revoke the old key.
      tags:
        - API Keys
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque key id (UUID) returned by `create` / `list`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Revoke an API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeKeyResponse'
              example:
                id: 3f2a9b1c-7d4e-4a8f-9c2b-1e5d6f7a8b90
                revoked: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
      x-cli:
        name: revoke
        positional:
          - id
  /api/admin/search:
    get:
      operationId: searchResources
      summary: Search project resources
      description: |-
        Universal substring search across the project's primary resources — feature gates, experiments, dynamic configs, killswitches, metrics, and team members. Matches the trimmed `q` against each resource's immutable `name` and its human title/display name (members match on display name or email), newest-first, capped per resource family so one noisy type can't crowd out the rest.

        Returns a flat, ranked-by-type list of hits (members first); an empty or whitespace-only `q` returns no hits. Each hit carries a project-relative `href` that deep-links to the row.

        **Use case:** Back a command-palette / quick-switcher in the dashboard, or look up the id of a resource by a fragment of its name before driving another API call.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: q
          in: query
          required: false
          description: Search query. Matched as a case-insensitive substring against each resource's `name` and title/display name. Trimmed; empty returns no hits.
          schema:
            type: string
      responses:
        '200':
          description: Search project resources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              example:
                hits:
                  - type: member
                    id: ana@example.com
                    name: Ana Ng
                    title: ana@example.com
                    href: /team
                  - type: gate
                    id: gat_01j7w7m9q4hxbf6npe6s9zr3vc
                    name: checkout_v2
                    title: Checkout v2
                    href: /gates?open=gat_01j7w7m9q4hxbf6npe6s9zr3vc
                  - type: experiment
                    id: exp_01j7w7m9q4hxbf6npe6s9zr3vd
                    name: checkout_button_color
                    title: Checkout button colour test
                    href: /experiments?open=exp_01j7w7m9q4hxbf6npe6s9zr3vd
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: search
components:
  securitySchemes:
    bearerSdkKey:
      type: http
      scheme: bearer
      bearerFormat: sdk_admin_*
      description: 'Pass an admin SDK key as `Authorization: Bearer sdk_admin_…`. Mint via `POST /api/admin/keys` with `type: "admin"`.'
  parameters:
    ProjectId:
      name: X-Project-Id
      in: header
      required: false
      description: Project the request operates on. Optional — defaults to the project the SDK key belongs to; pass it only to scope a multi-project key (the generated client sets it once from its configuration, so per-call callers never thread it).
      schema:
        type: string
    PaginationLimit:
      name: limit
      in: query
      required: false
      description: Page size (1–500). Defaults to 100.
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
    PaginationCursor:
      name: cursor
      in: query
      required: false
      description: Opaque cursor returned in the previous page's `next_cursor`. Omit for the first page.
      schema:
        type: string
    Q:
      name: q
      in: query
      required: false
      description: Case-insensitive substring filter across the resource's human-readable text columns (e.g. `name`, `title`, `description`). OR-matched across those columns; omit to return everything.
      schema:
        type: string
        maxLength: 100
  schemas:
    ListGatesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Stable opaque gate id (`gat_…`).
              name:
                type: string
                maxLength: 128
                pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
                description: Stable gate key used by SDKs (`Shipeasy.checkGate(user, '<name>')`). Single segment or `folder.name`. Lowercase letters, digits, `_` or `-`; max 128 chars. Immutable after create — rename = delete + recreate.
              enabled:
                anyOf:
                  - type: boolean
                  - type: integer
                    minimum: 0
                    maximum: 1
                description: Master switch. Returned as `1`/`0` from D1; treat truthy as enabled.
              type:
                type: string
                enum:
                  - targeting
                  - holdout
                description: Gate kind — `targeting` (normal flag) or `holdout` (restricted public % + whitelist).
              rolloutPct:
                type: integer
                minimum: 0
                maximum: 10000
                description: Current rollout in basis points (0–10000).
              rules:
                type: array
                items:
                  type: object
                  properties:
                    attr:
                      type: string
                      minLength: 1
                      description: Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input.
                    op:
                      type: string
                      enum:
                        - eq
                        - neq
                        - in
                        - not_in
                        - gt
                        - gte
                        - lt
                        - lte
                        - contains
                        - regex
                        - semver_gt
                        - semver_gte
                        - semver_lt
                        - semver_lte
                        - gate_pass
                        - exp_in
                      description: 'Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte` (value is a dotted version like `4.2.0`). String: `contains` (substring), `regex` (JS-flavour pattern, value is the pattern string). Cross-resource references (evaluated only on the worker hot path, where both KV blobs load): `gate_pass` (`value` is another gate''s name — true when that gate passes for the same caller); `exp_in` (`attr` is a running experiment''s name, `value` is a group name, `"$holdout"`, or `"$any"` — true when the caller is in that variant / the universe holdout / any variant).'
                    value:
                      description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; group name / `"$holdout"` / `"$any"` for `exp_in`.'
                  required:
                    - attr
                    - op
                    - value
                  additionalProperties: false
                  description: Single targeting predicate. A gate's `rules` array is evaluated with AND semantics; use the gatekeeper `stack` for OR / fall-through logic.
              salt:
                description: Hash salt used for percentage bucketing.
                type: string
              title:
                anyOf:
                  - type: string
                  - type: 'null'
              description:
                anyOf:
                  - type: string
                  - type: 'null'
              folder:
                anyOf:
                  - type: string
                  - type: 'null'
              groupName:
                description: 'Group label (note: `groupName` in response, `group` in request).'
                anyOf:
                  - type: string
                  - type: 'null'
              ownerEmail:
                description: 'Owner email (note: `ownerEmail` in response, `owner_email` in request).'
                anyOf:
                  - type: string
                  - type: 'null'
              stack:
                anyOf:
                  - type: array
                    items:
                      oneOf:
                        - type: object
                          properties:
                            id:
                              type: string
                              minLength: 1
                              description: Client-supplied stable id for the stack entry (used for React keys, audit diffs, and as the default per-condition rollout salt).
                            type:
                              type: string
                              const: condition
                              description: Discriminator. `condition` = rule-based predicate sub-gate.
                            name:
                              description: Human label shown in the dashboard.
                              type: string
                            fromTemplate:
                              description: Id of the project template this entry was seeded from, or `null` if hand-authored.
                              anyOf:
                                - type: string
                                - type: 'null'
                            pass:
                              description: Combinator across `rules`. `all` = AND (default), `any` = OR.
                              type: string
                              enum:
                                - all
                                - any
                            rules:
                              default: []
                              description: Predicates evaluated under `pass`. Empty array = match nothing.
                              type: array
                              items:
                                type: object
                                properties:
                                  attr:
                                    type: string
                                    minLength: 1
                                    description: Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input.
                                  op:
                                    type: string
                                    enum:
                                      - eq
                                      - neq
                                      - in
                                      - not_in
                                      - gt
                                      - gte
                                      - lt
                                      - lte
                                      - contains
                                      - regex
                                      - semver_gt
                                      - semver_gte
                                      - semver_lt
                                      - semver_lte
                                      - gate_pass
                                      - exp_in
                                    description: 'Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte` (value is a dotted version like `4.2.0`). String: `contains` (substring), `regex` (JS-flavour pattern, value is the pattern string). Cross-resource references (evaluated only on the worker hot path, where both KV blobs load): `gate_pass` (`value` is another gate''s name — true when that gate passes for the same caller); `exp_in` (`attr` is a running experiment''s name, `value` is a group name, `"$holdout"`, or `"$any"` — true when the caller is in that variant / the universe holdout / any variant).'
                                  value:
                                    description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; group name / `"$holdout"` / `"$any"` for `exp_in`.'
                                required:
                                  - attr
                                  - op
                                  - value
                                additionalProperties: false
                                description: Single targeting predicate. A gate's `rules` array is evaluated with AND semantics; use the gatekeeper `stack` for OR / fall-through logic.
                            rolloutPct:
                              description: Per-condition rollout in basis points. After the rules match, the caller is bucketed at this %; in-bucket → gate `true`, otherwise fall through to the next entry. Absent ⇒ 10000 (100%, every matching caller passes).
                              type: integer
                              minimum: 0
                              maximum: 10000
                            bucketBy:
                              description: Attribute used to hash the caller into the per-condition bucket. Default `userID`.
                              type: string
                            salt:
                              description: Per-condition hash salt. Defaults to the entry `id`, then the gate salt.
                              type: string
                            ramp:
                              type: object
                              properties:
                                from:
                                  type: integer
                                  minimum: 0
                                  maximum: 10000
                                  description: Start of the ramp in basis points (0–10000).
                                to:
                                  type: integer
                                  minimum: 0
                                  maximum: 10000
                                  description: End of the ramp in basis points (0–10000).
                                startAt:
                                  type: integer
                                  minimum: 0
                                  maximum: 9007199254740991
                                  description: Ramp start, epoch milliseconds (UTC).
                                durationMs:
                                  type: integer
                                  exclusiveMinimum: 0
                                  maximum: 9007199254740991
                                  description: Ramp length in milliseconds.
                              required:
                                - from
                                - to
                                - startAt
                                - durationMs
                              additionalProperties: false
                              description: Linear rollout ramp. The effective rollout % interpolates `from`→`to` over `[startAt, startAt+durationMs]`, clamped outside that window, evaluated against the wall-clock at eval time. Overrides the entry's static `rolloutPct` while present.
                            locked:
                              description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
                              type: boolean
                          required:
                            - id
                            - type
                          additionalProperties: false
                          description: Rule-based sub-gate. When the rules match and the caller falls in the per-condition rollout bucket, evaluation short-circuits and the gate returns `true`; otherwise it falls through to the next entry.
                        - type: object
                          properties:
                            id:
                              type: string
                              minLength: 1
                              description: Client-supplied stable id for the stack entry.
                            type:
                              type: string
                              const: rollout
                              description: Discriminator. `rollout` = percentage-bucket sub-gate.
                            name:
                              description: Human label shown in the dashboard.
                              type: string
                            fromTemplate:
                              description: Source template id, or `null`.
                              anyOf:
                                - type: string
                                - type: 'null'
                            rolloutPct:
                              type: integer
                              minimum: 0
                              maximum: 10000
                              description: Bucket size in basis points (0–10000 = 0%–100%). `5000` = 50%, `100` = 1%, allows sub-1% precision.
                            bucketBy:
                              description: Attribute used to hash the caller into a bucket. Defaults to `user.userID`. Use e.g. `accountID` to bucket whole accounts together.
                              type: string
                            salt:
                              description: Per-entry hash salt. Defaults to the gate's salt. Set explicitly to keep two rollouts independent or correlated across gates.
                              type: string
                            ramp:
                              type: object
                              properties:
                                from:
                                  type: integer
                                  minimum: 0
                                  maximum: 10000
                                  description: Start of the ramp in basis points (0–10000).
                                to:
                                  type: integer
                                  minimum: 0
                                  maximum: 10000
                                  description: End of the ramp in basis points (0–10000).
                                startAt:
                                  type: integer
                                  minimum: 0
                                  maximum: 9007199254740991
                                  description: Ramp start, epoch milliseconds (UTC).
                                durationMs:
                                  type: integer
                                  exclusiveMinimum: 0
                                  maximum: 9007199254740991
                                  description: Ramp length in milliseconds.
                              required:
                                - from
                                - to
                                - startAt
                                - durationMs
                              additionalProperties: false
                              description: Linear rollout ramp. The effective rollout % interpolates `from`→`to` over `[startAt, startAt+durationMs]`, clamped outside that window, evaluated against the wall-clock at eval time. Overrides the entry's static `rolloutPct` while present.
                            locked:
                              description: If `true`, dashboard hides edit controls.
                              type: boolean
                          required:
                            - id
                            - type
                            - rolloutPct
                          additionalProperties: false
                          description: Percentage-rollout sub-gate. Hashes `bucketBy` (default `userID`) with `salt` and returns `true` for `rolloutPct/10000` fraction of callers (or the ramp's effective % when `ramp` is set).
                      description: One entry in the ordered gatekeeper stack. Evaluated top-to-bottom; first matching entry decides. Mix `condition` and `rollout` entries to express `internal-only` + `1% beta` + `50% public` in a single gate.
                  - type: 'null'
              updatedAt:
                type: string
                description: ISO-8601 timestamp of last mutation.
            required:
              - id
              - name
              - enabled
              - rolloutPct
              - updatedAt
            additionalProperties: false
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - data
        - next_cursor
      additionalProperties: false
    ErrorCode:
      type: string
      description: Stable, machine-readable error code. Mirrors the `ErrorCode` catalogue in `@shipeasy/core`. Each operation lists the subset it can return under `x-error-codes`.
      enum:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - PLAN_REQUIRED
        - NOT_FOUND
        - ALREADY_EXISTS
        - INVALID_TRANSITION
        - IMMUTABLE_FIELD
        - READ_ONLY
        - REFERENCED_IN_USE
        - VALIDATION
        - REFERENCED_NOT_FOUND
        - GROUPS_WEIGHT_SUM
        - EVENT_PENDING
        - INTERNAL
        - PLAN_LIMIT
        - EXPERIMENT_NO_GOAL_METRIC
        - EXPERIMENT_ARCHIVED_RESTART
        - EXPERIMENT_RESTORE_INVALID
        - EXPERIMENT_NOT_RUNNING
        - EXPERIMENT_RUNNING_ARCHIVE
        - EXPERIMENT_IMMUTABLE_FIELD
        - METRIC_NOT_FOUND
        - METRIC_UNKNOWN_ID
      x-enum-descriptions:
        BAD_REQUEST: Malformed request (bad JSON, missing project scope).
        UNAUTHORIZED: Missing or invalid admin SDK key.
        FORBIDDEN: Key is valid but not allowed to act on this project.
        PLAN_REQUIRED: The requested feature requires a higher plan tier (e.g. sequential testing, custom alpha, holdout, group count).
        NOT_FOUND: The resource does not exist or is not visible to the caller.
        ALREADY_EXISTS: A resource with this name already exists in the project.
        INVALID_TRANSITION: The requested lifecycle transition is not allowed from the current state.
        IMMUTABLE_FIELD: A field that is immutable in the current state was modified (e.g. editing allocation while running).
        READ_ONLY: The resource is a read-only built-in (e.g. a built-in gate-rule template) and cannot be modified or deleted.
        REFERENCED_IN_USE: The resource cannot be archived/deleted while another resource still references it.
        VALIDATION: The request body failed structural (schema) validation.
        REFERENCED_NOT_FOUND: A referenced entity (universe, metric, gate, event) does not exist.
        GROUPS_WEIGHT_SUM: Experiment group weights must sum to 10000 (basis points).
        EVENT_PENDING: The referenced event is still pending review and cannot back a metric yet.
        INTERNAL: Unexpected server error.
        PLAN_LIMIT: The action would exceed a plan quota (e.g. the tier's maximum experiments, metrics, or configs). Upgrade the plan or archive an existing resource.
        EXPERIMENT_NO_GOAL_METRIC: The experiment has no goal metric set, which the requested action requires.
        EXPERIMENT_ARCHIVED_RESTART: An archived experiment cannot be restarted.
        EXPERIMENT_RESTORE_INVALID: The experiment cannot be restored from its current state.
        EXPERIMENT_NOT_RUNNING: The action requires the experiment to be running.
        EXPERIMENT_RUNNING_ARCHIVE: A running experiment cannot be archived — stop it first.
        EXPERIMENT_IMMUTABLE_FIELD: A field that is immutable while the experiment is running was modified.
        METRIC_NOT_FOUND: The referenced metric does not exist or is not visible to the caller.
        METRIC_UNKNOWN_ID: The supplied metric id is malformed or not recognised.
    Error:
      type: object
      description: Uniform error envelope returned by every admin endpoint on a non-2xx status. `error` is the human-readable message; `code` is the stable machine code (present whenever the failure maps to a catalogued `ErrorCode`); `detail` carries extra context (validation paths, conflicting field); `fields` maps each failing input field to its own message; `instructions` is optional actionable guidance for resolving the error; `schema` echoes back the expected JSON Schema when a value failed schema validation.
      required:
        - error
      additionalProperties: false
      properties:
        error:
          type: string
          description: Human-readable error message.
        code:
          $ref: '#/components/schemas/ErrorCode'
        detail:
          type: string
          description: Extra context (validation details, conflicting field, referenced row).
        fields:
          type: object
          additionalProperties:
            type: string
          description: Per-field validation messages, keyed by the submitted field's path (dot-notation for nested fields, e.g. `groups.0.weight`). Present when structural validation failed on one or more specific input fields, so a client form can attach each message to its own input instead of collapsing everything into one banner.
        instructions:
          type: string
          description: Actionable guidance for resolving this error — what to check or change next.
        schema:
          type: object
          additionalProperties: true
          description: The expected JSON Schema (draft 2020-12) the submitted value must satisfy. Returned only when a value failed schema validation (e.g. a config `value` that does not match its config's saved schema), so the caller can correct the value and retry without re-fetching.
    Folder:
      anyOf:
        - type: string
          maxLength: 256
          pattern: ^[a-zA-Z0-9_-]+$
        - type: 'null'
      description: Optional folder name grouping items in the dashboard. Alphanumeric, `_` or `-` (no `/`). Part of the SDK lookup key (`<folder>/<name>`).
    CreateGateRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 128
          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
          description: Stable gate key used by SDKs (`Shipeasy.checkGate(user, '<name>')`). Single segment or `folder.name`. Lowercase letters, digits, `_` or `-`; max 128 chars. Immutable after create — rename = delete + recreate.
        type:
          default: targeting
          type: string
          enum:
            - targeting
            - holdout
          description: Gate kind. `targeting` (default) is a normal flag with the full builder. `holdout` is a **restricted** flag — only a public rollout % and a whitelist are allowed; attribute rules and a gatekeeper stack are rejected. Used as an experiment's `holdout_gate`.
        enabled:
          default: true
          description: Master switch. Defaults to `true`. Set `false` to create the gate disabled (evaluates to `false` regardless of rules/rollout); flip on via `POST /{id}/enable` or PATCH.
          type: boolean
        rollout_pct:
          default: 0
          description: Initial rollout in **basis points** (0–10000 = 0%–100%) — `100` here means **1%**, not 100%. Use `rollout_percent` (0–100) below if you'd rather think in percent. Use `0` to create the gate dark and ramp via PATCH after deploy validation.
          type: integer
          minimum: 0
          maximum: 10000
        rollout_percent:
          description: Initial rollout as a **percentage** (0–100, fractional ok). Friendlier alias for `rollout_pct`; converted internally to basis points (e.g. `100` here = 10000 bp = 100%). If both `rollout_pct` and `rollout_percent` are set, `rollout_percent` wins.
          type: number
          minimum: 0
          maximum: 100
        rules:
          default: []
          description: Targeting predicates. AND-combined. If non-empty, the gate returns `true` only for callers that satisfy every rule **and** fall under `rollout_pct`.
          type: array
          items:
            type: object
            properties:
              attr:
                type: string
                minLength: 1
                description: Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input.
              op:
                type: string
                enum:
                  - eq
                  - neq
                  - in
                  - not_in
                  - gt
                  - gte
                  - lt
                  - lte
                  - contains
                  - regex
                  - semver_gt
                  - semver_gte
                  - semver_lt
                  - semver_lte
                  - gate_pass
                  - exp_in
                description: 'Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte` (value is a dotted version like `4.2.0`). String: `contains` (substring), `regex` (JS-flavour pattern, value is the pattern string). Cross-resource references (evaluated only on the worker hot path, where both KV blobs load): `gate_pass` (`value` is another gate''s name — true when that gate passes for the same caller); `exp_in` (`attr` is a running experiment''s name, `value` is a group name, `"$holdout"`, or `"$any"` — true when the caller is in that variant / the universe holdout / any variant).'
              value:
                description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; group name / `"$holdout"` / `"$any"` for `exp_in`.'
            required:
              - attr
              - op
              - value
            additionalProperties: false
            description: Single targeting predicate. A gate's `rules` array is evaluated with AND semantics; use the gatekeeper `stack` for OR / fall-through logic.
        salt:
          description: Hash salt for percentage bucketing. Auto-generated if omitted. Provide explicitly to keep a gate's buckets stable across delete/recreate. **Immutable after create** — there is no PATCH for `salt` because changing it would re-bucket every caller.
          type: string
          minLength: 1
          maxLength: 64
        stack:
          description: Optional gatekeeper stack. When provided, takes precedence over `rules` + `rollout_pct` at evaluation time. Omit (or pass `null`) for a flat gate.
          anyOf:
            - type: array
              items:
                oneOf:
                  - type: object
                    properties:
                      id:
                        type: string
                        minLength: 1
                        description: Client-supplied stable id for the stack entry (used for React keys, audit diffs, and as the default per-condition rollout salt).
                      type:
                        type: string
                        const: condition
                        description: Discriminator. `condition` = rule-based predicate sub-gate.
                      name:
                        description: Human label shown in the dashboard.
                        type: string
                      fromTemplate:
                        description: Id of the project template this entry was seeded from, or `null` if hand-authored.
                        anyOf:
                          - type: string
                          - type: 'null'
                      pass:
                        description: Combinator across `rules`. `all` = AND (default), `any` = OR.
                        type: string
                        enum:
                          - all
                          - any
                      rules:
                        default: []
                        description: Predicates evaluated under `pass`. Empty array = match nothing.
                        type: array
                        items:
                          type: object
                          properties:
                            attr:
                              type: string
                              minLength: 1
                              description: Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input.
                            op:
                              type: string
                              enum:
                                - eq
                                - neq
                                - in
                                - not_in
                                - gt
                                - gte
                                - lt
                                - lte
                                - contains
                                - regex
                                - semver_gt
                                - semver_gte
                                - semver_lt
                                - semver_lte
                                - gate_pass
                                - exp_in
                              description: 'Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte` (value is a dotted version like `4.2.0`). String: `contains` (substring), `regex` (JS-flavour pattern, value is the pattern string). Cross-resource references (evaluated only on the worker hot path, where both KV blobs load): `gate_pass` (`value` is another gate''s name — true when that gate passes for the same caller); `exp_in` (`attr` is a running experiment''s name, `value` is a group name, `"$holdout"`, or `"$any"` — true when the caller is in that variant / the universe holdout / any variant).'
                            value:
                              description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; group name / `"$holdout"` / `"$any"` for `exp_in`.'
                          required:
                            - attr
                            - op
                            - value
                          additionalProperties: false
                          description: Single targeting predicate. A gate's `rules` array is evaluated with AND semantics; use the gatekeeper `stack` for OR / fall-through logic.
                      rolloutPct:
                        description: Per-condition rollout in basis points. After the rules match, the caller is bucketed at this %; in-bucket → gate `true`, otherwise fall through to the next entry. Absent ⇒ 10000 (100%, every matching caller passes).
                        type: integer
                        minimum: 0
                        maximum: 10000
                      bucketBy:
                        description: Attribute used to hash the caller into the per-condition bucket. Default `userID`.
                        type: string
                      salt:
                        description: Per-condition hash salt. Defaults to the entry `id`, then the gate salt.
                        type: string
                      ramp:
                        type: object
                        properties:
                          from:
                            type: integer
                            minimum: 0
                            maximum: 10000
                            description: Start of the ramp in basis points (0–10000).
                          to:
                            type: integer
                            minimum: 0
                            maximum: 10000
                            description: End of the ramp in basis points (0–10000).
                          startAt:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                            description: Ramp start, epoch milliseconds (UTC).
                          durationMs:
                            type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                            description: Ramp length in milliseconds.
                        required:
                          - from
                          - to
                          - startAt
                          - durationMs
                        additionalProperties: false
                        description: Linear rollout ramp. The effective rollout % interpolates `from`→`to` over `[startAt, startAt+durationMs]`, clamped outside that window, evaluated against the wall-clock at eval time. Overrides the entry's static `rolloutPct` while present.
                      locked:
                        description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
                        type: boolean
                    required:
                      - id
                      - type
                    additionalProperties: false
                    description: Rule-based sub-gate. When the rules match and the caller falls in the per-condition rollout bucket, evaluation short-circuits and the gate returns `true`; otherwise it falls through to the next entry.
                  - type: object
                    properties:
                      id:
                        type: string
                        minLength: 1
                        description: Client-supplied stable id for the stack entry.
                      type:
                        type: string
                        const: rollout
                        description: Discriminator. `rollout` = percentage-bucket sub-gate.
                      name:
                        description: Human label shown in the dashboard.
                        type: string
                      fromTemplate:
                        description: Source template id, or `null`.
                        anyOf:
                          - type: string
                          - type: 'null'
                      rolloutPct:
                        type: integer
                        minimum: 0
                        maximum: 10000
                        description: Bucket size in basis points (0–10000 = 0%–100%). `5000` = 50%, `100` = 1%, allows sub-1% precision.
                      bucketBy:
                        description: Attribute used to hash the caller into a bucket. Defaults to `user.userID`. Use e.g. `accountID` to bucket whole accounts together.
                        type: string
                      salt:
                        description: Per-entry hash salt. Defaults to the gate's salt. Set explicitly to keep two rollouts independent or correlated across gates.
                        type: string
                      ramp:
                        type: object
                        properties:
                          from:
                            type: integer
                            minimum: 0
                            maximum: 10000
                            description: Start of the ramp in basis points (0–10000).
                          to:
                            type: integer
                            minimum: 0
                            maximum: 10000
                            description: End of the ramp in basis points (0–10000).
                          startAt:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                            description: Ramp start, epoch milliseconds (UTC).
                          durationMs:
                            type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                            description: Ramp length in milliseconds.
                        required:
                          - from
                          - to
                          - startAt
                          - durationMs
                        additionalProperties: false
                        description: Linear rollout ramp. The effective rollout % interpolates `from`→`to` over `[startAt, startAt+durationMs]`, clamped outside that window, evaluated against the wall-clock at eval time. Overrides the entry's static `rolloutPct` while present.
                      locked:
                        description: If `true`, dashboard hides edit controls.
                        type: boolean
                    required:
                      - id
                      - type
                      - rolloutPct
                    additionalProperties: false
                    description: Percentage-rollout sub-gate. Hashes `bucketBy` (default `userID`) with `salt` and returns `true` for `rolloutPct/10000` fraction of callers (or the ramp's effective % when `ramp` is set).
                description: One entry in the ordered gatekeeper stack. Evaluated top-to-bottom; first matching entry decides. Mix `condition` and `rollout` entries to express `internal-only` + `1% beta` + `50% public` in a single gate.
            - type: 'null'
        title:
          description: Human-readable title shown in the dashboard. Free-form, no key format constraint.
          type: string
          maxLength: 140
        description:
          description: Long-form description / runbook. Markdown is rendered in the dashboard.
          type: string
          maxLength: 2000
        folder:
          $ref: '#/components/schemas/Folder'
        group:
          description: Group label for dashboard organisation (e.g. team or product area).
          type: string
          maxLength: 64
        owner_email:
          description: Owner contact. Displayed verbatim; not used for auth.
          type: string
          maxLength: 190
      required:
        - name
      additionalProperties: false
      description: Body for `POST /api/admin/gates`. At minimum supply `name`; everything else has sensible defaults.
    CreateGateResponse:
      type: object
      properties:
        id:
          type: string
          description: Newly assigned gate id (`gat_…`).
        name:
          type: string
          maxLength: 128
          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
          description: Stable gate key used by SDKs (`Shipeasy.checkGate(user, '<name>')`). Single segment or `folder.name`. Lowercase letters, digits, `_` or `-`; max 128 chars. Immutable after create — rename = delete + recreate.
      required:
        - id
        - name
      additionalProperties: false
    ResourceId:
      type: string
      minLength: 1
      maxLength: 128
      description: A resource path identifier — an opaque `xxx_<ULID>` id (~30 chars) or the resource's `name`/`key`. 1–128 characters; the upper bound matches the longest name/key any resource accepts, so an over-long value can never name a real row.
    DeleteGateResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
      required:
        - ok
      additionalProperties: false
    UpdateGateRequest:
      type: object
      properties:
        type:
          type: string
          enum:
            - targeting
            - holdout
          description: Gate kind. Switching to `holdout` requires the gate carry only a public rollout % + whitelist (attribute rules / stack are rejected).
        rollout_pct:
          description: New rollout in **basis points** (0–10000 = 0%–100%) — `100` here means **1%**. Use `rollout_percent` (0–100) below for percent. Omit both to leave unchanged.
          type: integer
          minimum: 0
          maximum: 10000
        rollout_percent:
          description: New rollout as a **percentage** (0–100). Friendlier alias for `rollout_pct`; converted internally. Wins over `rollout_pct` if both are supplied. Omit both to leave unchanged.
          type: number
          minimum: 0
          maximum: 100
        rules:
          description: Replaces the rule list wholesale. To add a value to an `in` rule, send the full new `rules` array with the augmented `value` (e.g. previous `['US','CA']` → `['US','CA','GB']`).
          type: array
          items:
            type: object
            properties:
              attr:
                type: string
                minLength: 1
                description: Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input.
              op:
                type: string
                enum:
                  - eq
                  - neq
                  - in
                  - not_in
                  - gt
                  - gte
                  - lt
                  - lte
                  - contains
                  - regex
                  - semver_gt
                  - semver_gte
                  - semver_lt
                  - semver_lte
                  - gate_pass
                  - exp_in
                description: 'Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte` (value is a dotted version like `4.2.0`). String: `contains` (substring), `regex` (JS-flavour pattern, value is the pattern string). Cross-resource references (evaluated only on the worker hot path, where both KV blobs load): `gate_pass` (`value` is another gate''s name — true when that gate passes for the same caller); `exp_in` (`attr` is a running experiment''s name, `value` is a group name, `"$holdout"`, or `"$any"` — true when the caller is in that variant / the universe holdout / any variant).'
              value:
                description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; group name / `"$holdout"` / `"$any"` for `exp_in`.'
            required:
              - attr
              - op
              - value
            additionalProperties: false
            description: Single targeting predicate. A gate's `rules` array is evaluated with AND semantics; use the gatekeeper `stack` for OR / fall-through logic.
        enabled:
          description: Master switch. `false` makes the gate evaluate to `false` for every caller regardless of `rollout_pct`, `rules`, or `stack` — use as kill switch.
          type: boolean
        stack:
          description: Replaces the gatekeeper stack wholesale. Send `null` to revert to flat `rules` + `rollout_pct` evaluation.
          anyOf:
            - type: array
              items:
                oneOf:
                  - type: object
                    properties:
                      id:
                        type: string
                        minLength: 1
                        description: Client-supplied stable id for the stack entry (used for React keys, audit diffs, and as the default per-condition rollout salt).
                      type:
                        type: string
                        const: condition
                        description: Discriminator. `condition` = rule-based predicate sub-gate.
                      name:
                        description: Human label shown in the dashboard.
                        type: string
                      fromTemplate:
                        description: Id of the project template this entry was seeded from, or `null` if hand-authored.
                        anyOf:
                          - type: string
                          - type: 'null'
                      pass:
                        description: Combinator across `rules`. `all` = AND (default), `any` = OR.
                        type: string
                        enum:
                          - all
                          - any
                      rules:
                        default: []
                        description: Predicates evaluated under `pass`. Empty array = match nothing.
                        type: array
                        items:
                          type: object
                          properties:
                            attr:
                              type: string
                              minLength: 1
                              description: Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input.
                            op:
                              type: string
                              enum:
                                - eq
                                - neq
                                - in
                                - not_in
                                - gt
                                - gte
                                - lt
                                - lte
                                - contains
                                - regex
                                - semver_gt
                                - semver_gte
                                - semver_lt
                                - semver_lte
                                - gate_pass
                                - exp_in
                              description: 'Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte` (value is a dotted version like `4.2.0`). String: `contains` (substring), `regex` (JS-flavour pattern, value is the pattern string). Cross-resource references (evaluated only on the worker hot path, where both KV blobs load): `gate_pass` (`value` is another gate''s name — true when that gate passes for the same caller); `exp_in` (`attr` is a running experiment''s name, `value` is a group name, `"$holdout"`, or `"$any"` — true when the caller is in that variant / the universe holdout / any variant).'
                            value:
                              description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; group name / `"$holdout"` / `"$any"` for `exp_in`.'
                          required:
                            - attr
                            - op
                            - value
                          additionalProperties: false
                          description: Single targeting predicate. A gate's `rules` array is evaluated with AND semantics; use the gatekeeper `stack` for OR / fall-through logic.
                      rolloutPct:
                        description: Per-condition rollout in basis points. After the rules match, the caller is bucketed at this %; in-bucket → gate `true`, otherwise fall through to the next entry. Absent ⇒ 10000 (100%, every matching caller passes).
                        type: integer
                        minimum: 0
                        maximum: 10000
                      bucketBy:
                        description: Attribute used to hash the caller into the per-condition bucket. Default `userID`.
                        type: string
                      salt:
                        description: Per-condition hash salt. Defaults to the entry `id`, then the gate salt.
                        type: string
                      ramp:
                        type: object
                        properties:
                          from:
                            type: integer
                            minimum: 0
                            maximum: 10000
                            description: Start of the ramp in basis points (0–10000).
                          to:
                            type: integer
                            minimum: 0
                            maximum: 10000
                            description: End of the ramp in basis points (0–10000).
                          startAt:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                            description: Ramp start, epoch milliseconds (UTC).
                          durationMs:
                            type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                            description: Ramp length in milliseconds.
                        required:
                          - from
                          - to
                          - startAt
                          - durationMs
                        additionalProperties: false
                        description: Linear rollout ramp. The effective rollout % interpolates `from`→`to` over `[startAt, startAt+durationMs]`, clamped outside that window, evaluated against the wall-clock at eval time. Overrides the entry's static `rolloutPct` while present.
                      locked:
                        description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
                        type: boolean
                    required:
                      - id
                      - type
                    additionalProperties: false
                    description: Rule-based sub-gate. When the rules match and the caller falls in the per-condition rollout bucket, evaluation short-circuits and the gate returns `true`; otherwise it falls through to the next entry.
                  - type: object
                    properties:
                      id:
                        type: string
                        minLength: 1
                        description: Client-supplied stable id for the stack entry.
                      type:
                        type: string
                        const: rollout
                        description: Discriminator. `rollout` = percentage-bucket sub-gate.
                      name:
                        description: Human label shown in the dashboard.
                        type: string
                      fromTemplate:
                        description: Source template id, or `null`.
                        anyOf:
                          - type: string
                          - type: 'null'
                      rolloutPct:
                        type: integer
                        minimum: 0
                        maximum: 10000
                        description: Bucket size in basis points (0–10000 = 0%–100%). `5000` = 50%, `100` = 1%, allows sub-1% precision.
                      bucketBy:
                        description: Attribute used to hash the caller into a bucket. Defaults to `user.userID`. Use e.g. `accountID` to bucket whole accounts together.
                        type: string
                      salt:
                        description: Per-entry hash salt. Defaults to the gate's salt. Set explicitly to keep two rollouts independent or correlated across gates.
                        type: string
                      ramp:
                        type: object
                        properties:
                          from:
                            type: integer
                            minimum: 0
                            maximum: 10000
                            description: Start of the ramp in basis points (0–10000).
                          to:
                            type: integer
                            minimum: 0
                            maximum: 10000
                            description: End of the ramp in basis points (0–10000).
                          startAt:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                            description: Ramp start, epoch milliseconds (UTC).
                          durationMs:
                            type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                            description: Ramp length in milliseconds.
                        required:
                          - from
                          - to
                          - startAt
                          - durationMs
                        additionalProperties: false
                        description: Linear rollout ramp. The effective rollout % interpolates `from`→`to` over `[startAt, startAt+durationMs]`, clamped outside that window, evaluated against the wall-clock at eval time. Overrides the entry's static `rolloutPct` while present.
                      locked:
                        description: If `true`, dashboard hides edit controls.
                        type: boolean
                    required:
                      - id
                      - type
                      - rolloutPct
                    additionalProperties: false
                    description: Percentage-rollout sub-gate. Hashes `bucketBy` (default `userID`) with `salt` and returns `true` for `rolloutPct/10000` fraction of callers (or the ramp's effective % when `ramp` is set).
                description: One entry in the ordered gatekeeper stack. Evaluated top-to-bottom; first matching entry decides. Mix `condition` and `rollout` entries to express `internal-only` + `1% beta` + `50% public` in a single gate.
            - type: 'null'
        title:
          description: Human-readable title shown in the dashboard. Free-form, no key format constraint.
          type: string
          maxLength: 140
        description:
          description: Long-form description / runbook. Markdown is rendered in the dashboard.
          type: string
          maxLength: 2000
        folder:
          $ref: '#/components/schemas/Folder'
        group:
          description: Group label for dashboard organisation (e.g. team or product area).
          type: string
          maxLength: 64
        owner_email:
          description: Owner contact. Displayed verbatim; not used for auth.
          type: string
          maxLength: 190
      additionalProperties: false
      description: Body for `PATCH /api/admin/gates/{id}`. Partial — only supplied fields change. Array fields (`rules`, `stack`) replace, not merge.
    UpdateGateResponse:
      type: object
      properties:
        id:
          type: string
          description: Gate id that was updated.
      required:
        - id
      additionalProperties: false
      description: Update returns only the id — re-fetch via `GET /api/admin/gates` for the full row.
    EnableGateResponse:
      type: object
      properties:
        id:
          type: string
        enabled:
          type: boolean
      required:
        - id
        - enabled
      additionalProperties: false
    DisableGateResponse:
      type: object
      properties:
        id:
          type: string
        enabled:
          type: boolean
      required:
        - id
        - enabled
      additionalProperties: false
    ListExperimentsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Stable opaque experiment id (`exp_…`).
              name:
                type: string
                maxLength: 128
                pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
                description: Stable experiment key. Single segment or `folder.name` (a-z, 0-9, `_`/`-`; max 128 chars). Used by SDKs as `Shipeasy.getExperiment(user, '<name>')`. Immutable after create.
              description:
                anyOf:
                  - type: string
                  - type: 'null'
              hypothesis:
                anyOf:
                  - type: string
                  - type: 'null'
              tag:
                anyOf:
                  - type: string
                  - type: 'null'
              ownerEmail:
                anyOf:
                  - type: string
                  - type: 'null'
              audience:
                anyOf:
                  - type: string
                  - type: 'null'
              bucketBy:
                anyOf:
                  - type: string
                    minLength: 1
                    maxLength: 128
                    pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
                    description: User-attribute name used as the bucketing key — e.g. `user_id` (default), `session_id`, `device_id`, or a custom attribute like `company_id` to keep a whole org on one variant. Defaults to `user_id` when omitted.
                  - type: 'null'
              folder:
                anyOf:
                  - type: string
                  - type: 'null'
              status:
                type: string
                enum:
                  - draft
                  - running
                  - stopped
                  - archived
              universe:
                type: string
                description: Universe name this experiment draws from.
              targetingGate:
                anyOf:
                  - type: string
                  - type: 'null'
              holdoutGate:
                anyOf:
                  - type: string
                  - type: 'null'
                description: Per-experiment holdout gate name (a `holdout`-type flag), or `null`.
              allocationPct:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
                description: Allocation in basis points (0–10000).
              reservedHeadroom:
                type: integer
                minimum: 0
                maximum: 10000
                description: Basis points of the split reserved for appended variants (group weights sum to 10000 − this).
              salt:
                type: string
              params:
                type: object
                additionalProperties:
                  type: string
                  enum:
                    - string
                    - bool
                    - number
              groups:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 64
                      description: Group label (e.g. `control`, `treatment_a`). Max 64 chars.
                    weight:
                      type: integer
                      minimum: 0
                      maximum: 10000
                      description: Allocation weight in basis points (0–10000). The sum across all groups must equal exactly **10000** (100%).
                    params:
                      default: {}
                      description: Per-group parameter values delivered to the SDK when a caller is hashed into this group. Keys must match the experiment's `params` schema.
                      type: object
                      additionalProperties: {}
                  required:
                    - name
                    - weight
                  additionalProperties: false
                  description: One variant in the experiment. Weights across all groups must sum to 10000.
              significanceThreshold:
                type: number
              minRuntimeDays:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
              minSampleSize:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
              sequentialTesting:
                type: boolean
              startedAt:
                anyOf:
                  - type: string
                  - type: 'null'
                description: ISO-8601 timestamp the experiment last transitioned to `running`, or `null`.
              stoppedAt:
                anyOf:
                  - type: string
                  - type: 'null'
              updatedAt:
                type: string
            required:
              - id
              - name
              - description
              - hypothesis
              - tag
              - ownerEmail
              - audience
              - bucketBy
              - folder
              - status
              - universe
              - targetingGate
              - allocationPct
              - salt
              - params
              - groups
              - significanceThreshold
              - minRuntimeDays
              - minSampleSize
              - sequentialTesting
              - startedAt
              - updatedAt
            additionalProperties: false
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - data
        - next_cursor
      additionalProperties: false
    MetricName:
      type: string
      maxLength: 128
      pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
      description: Stable metric key. Single segment or `folder.name`; lowercase letters, digits, `_`/`-`; max 128 chars.
    ExperimentInlineMetric:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/MetricName'
        query:
          type: string
          minLength: 1
          maxLength: 4096
          description: Metric DSL string. Provide this OR `event`.
        event:
          type: string
          minLength: 1
          maxLength: 256
          description: Event name to build the metric from server-side. Auto-created if missing.
        aggregation:
          type: string
          enum:
            - count_users
            - count_events
            - retention_7d
            - retention_30d
            - sum
            - avg
          description: Reducer for the `event` form. Defaults to `count_users`.
        value:
          type: string
          minLength: 1
          maxLength: 256
          description: Numeric event property for `sum`/`avg` (with `event`).
        min_effect_of_interest:
          description: Per-experiment override of the metric's default minimum effect of interest (relative, 0–1) — the smallest change worth acting on for this experiment's decision. `null`/omitted inherits the metric default. For a guardrail, the non-inferiority margin.
          default: null
          anyOf:
            - type: number
            - type: 'null'
      additionalProperties: false
      description: Inline metric — a DSL `query`, or an `event` (+ `aggregation`/`value`) the server compiles into one.
    CreateExperimentRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 128
          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
          description: Stable experiment key. Single segment or `folder.name` (a-z, 0-9, `_`/`-`; max 128 chars). Used by SDKs as `Shipeasy.getExperiment(user, '<name>')`. Immutable after create.
        description:
          default: null
          description: Free-form description. Max 2000 chars, markdown rendered in the dashboard.
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
        hypothesis:
          default: null
          description: Hypothesis statement shown in the editor. Display-only.
          anyOf:
            - type: string
              maxLength: 4000
            - type: 'null'
        tag:
          default: null
          description: Short tag chip rendered next to the name. Display-only.
          anyOf:
            - type: string
              maxLength: 64
            - type: 'null'
        owner_email:
          default: null
          description: Owner email. Display-only.
          anyOf:
            - type: string
              maxLength: 254
            - type: 'null'
        audience:
          default: null
          description: Audience label shown in the editor. Display-only.
          anyOf:
            - type: string
              maxLength: 256
            - type: 'null'
        bucket_by:
          default: null
          anyOf:
            - type: string
              minLength: 1
              maxLength: 128
              pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
              description: User-attribute name used as the bucketing key — e.g. `user_id` (default), `session_id`, `device_id`, or a custom attribute like `company_id` to keep a whole org on one variant. Defaults to `user_id` when omitted.
            - type: 'null'
        folder:
          $ref: '#/components/schemas/Folder'
        universe:
          type: string
          minLength: 1
          description: Name of an existing universe in the project. Returns `422` if the universe doesn't exist.
        targeting_gate:
          default: null
          description: Optional gate name (a `targeting`-type flag). Only callers that pass the gate are enrolled in the experiment.
          anyOf:
            - type: string
            - type: 'null'
        holdout_gate:
          default: null
          description: Optional per-experiment holdout gate — the name of a `holdout`-type flag (public % + whitelist). A caller the flag passes is *held out* (never assigned, sees the universe defaults). Distinct from the universe-level holdout.
          anyOf:
            - type: string
            - type: 'null'
        allocation_pct:
          default: 0
          description: Share of the (gated) audience allocated to the experiment, in basis points (0–10000 = 0%–100%). `0` = unallocated. Under pooled assignment this is the size of the universe-pool slice claimed. Use `allocation_percent` (0–100) below to think in percent. Immutable while the experiment is running.
          type: integer
          minimum: 0
          maximum: 10000
        allocation_percent:
          description: Allocation as a **percentage** (0–100, fractional ok). Friendlier alias for `allocation_pct`; converted to basis points server-side (e.g. `50` = 5000 bp). If both are set, `allocation_percent` wins.
          type: number
          minimum: 0
          maximum: 100
        reserved_headroom:
          description: Basis points of this experiment's split kept empty (0–10000) so a new variant can be appended into it while running without reshuffling. Group weights must sum to `10000 − reserved_headroom`. Defaults to the universe's `recommended_headroom` when omitted.
          type: integer
          minimum: 0
          maximum: 10000
        salt:
          description: Hash salt for bucketing. Auto-generated if omitted. Immutable while running.
          type: string
          minLength: 1
          maxLength: 64
        params:
          default: {}
          type: object
          additionalProperties:
            type: string
            enum:
              - string
              - bool
              - number
          description: '**Deprecated** — the universe now owns the config schema (`param_schema`). Retained for back-compat; new experiments should leave this empty and declare params on the universe. Map of param-name → scalar type.'
        groups:
          minItems: 2
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                minLength: 1
                maxLength: 64
                description: Group label (e.g. `control`, `treatment_a`). Max 64 chars.
              weight:
                type: integer
                minimum: 0
                maximum: 10000
                description: Allocation weight in basis points (0–10000). Weights across all groups must sum to `10000 − reserved_headroom` (100% minus any reserved tail).
              params:
                default: {}
                description: Per-variant **override map** — a subset of the universe's `param_schema` keys. A key the variant doesn't set inherits the universe default. Unknown keys (not in the universe schema) are rejected.
                type: object
                additionalProperties: {}
            required:
              - name
              - weight
            additionalProperties: false
            description: One variant. Its `params` may only override keys declared on the universe schema.
          description: Two or more variants. Weights must sum to `10000 − reserved_headroom`. Existing weights are immutable while running, but a new variant may be appended into the reserved tail.
        significance_threshold:
          default: 0.05
          description: p-value cutoff used by the analysis pass. Defaults to `0.05`. Values other than 0.05 require Pro plan or higher.
          type: number
          minimum: 0.0001
          maximum: 0.5
        min_runtime_days:
          default: 0
          description: Minimum days the experiment must run before results are considered conclusive.
          type: integer
          minimum: 0
          maximum: 365
        min_sample_size:
          default: 100
          description: Minimum exposures per group before results are considered conclusive.
          type: integer
          minimum: 1
          maximum: 9007199254740991
        sequential_testing:
          default: false
          description: Enable sequential testing (always-valid p-values). Requires Premium plan or higher.
          type: boolean
        goal_metric:
          description: Single goal metric defined inline — either a DSL `query` or an `event` (+`aggregation`/`value`) the server compiles. Attaching one is required before the experiment can be started. The underlying event is auto-created if missing.
          $ref: '#/components/schemas/ExperimentInlineMetric'
        guardrail_metrics:
          default: []
          description: Up to 10 guardrail metrics defined inline. Each is upserted (event + metric) and attached with role=guardrail.
          maxItems: 10
          type: array
          items:
            $ref: '#/components/schemas/ExperimentInlineMetric'
      required:
        - name
        - universe
        - groups
      additionalProperties: false
      description: Body for `POST /api/admin/experiments`. `name`, `universe`, and `groups` (≥2, weights sum to 10000) required.
    CreateExperimentResponse:
      type: object
      properties:
        id:
          type: string
          description: Newly assigned experiment id.
        name:
          type: string
          maxLength: 128
          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
          description: Stable experiment key. Single segment or `folder.name` (a-z, 0-9, `_`/`-`; max 128 chars). Used by SDKs as `Shipeasy.getExperiment(user, '<name>')`. Immutable after create.
      required:
        - id
        - name
      additionalProperties: false
    GetExperimentResponse:
      type: object
      properties:
        id:
          type: string
          description: Stable opaque experiment id (`exp_…`).
        name:
          type: string
          maxLength: 128
          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
          description: Stable experiment key. Single segment or `folder.name` (a-z, 0-9, `_`/`-`; max 128 chars). Used by SDKs as `Shipeasy.getExperiment(user, '<name>')`. Immutable after create.
        description:
          anyOf:
            - type: string
            - type: 'null'
        hypothesis:
          anyOf:
            - type: string
            - type: 'null'
        tag:
          anyOf:
            - type: string
            - type: 'null'
        ownerEmail:
          anyOf:
            - type: string
            - type: 'null'
        audience:
          anyOf:
            - type: string
            - type: 'null'
        bucketBy:
          anyOf:
            - type: string
              minLength: 1
              maxLength: 128
              pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
              description: User-attribute name used as the bucketing key — e.g. `user_id` (default), `session_id`, `device_id`, or a custom attribute like `company_id` to keep a whole org on one variant. Defaults to `user_id` when omitted.
            - type: 'null'
        folder:
          anyOf:
            - type: string
            - type: 'null'
        status:
          type: string
          enum:
            - draft
            - running
            - stopped
            - archived
        universe:
          type: string
          description: Universe name this experiment draws from.
        targetingGate:
          anyOf:
            - type: string
            - type: 'null'
        allocationPct:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Allocation in basis points (0–10000).
        salt:
          type: string
        params:
          type: object
          additionalProperties:
            type: string
            enum:
              - string
              - bool
              - number
        groups:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                minLength: 1
                maxLength: 64
                description: Group label (e.g. `control`, `treatment_a`). Max 64 chars.
              weight:
                type: integer
                minimum: 0
                maximum: 10000
                description: Allocation weight in basis points (0–10000). The sum across all groups must equal exactly **10000** (100%).
              params:
                default: {}
                description: Per-group parameter values delivered to the SDK when a caller is hashed into this group. Keys must match the experiment's `params` schema.
                type: object
                additionalProperties: {}
            required:
              - name
              - weight
            additionalProperties: false
            description: One variant in the experiment. Weights across all groups must sum to 10000.
        significanceThreshold:
          type: number
        minRuntimeDays:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        minSampleSize:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        sequentialTesting:
          type: boolean
        startedAt:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-8601 timestamp the experiment last transitioned to `running`, or `null`.
        stoppedAt:
          anyOf:
            - type: string
            - type: 'null'
        updatedAt:
          type: string
      required:
        - id
        - name
        - description
        - hypothesis
        - tag
        - ownerEmail
        - audience
        - bucketBy
        - folder
        - status
        - universe
        - targetingGate
        - allocationPct
        - salt
        - params
        - groups
        - significanceThreshold
        - minRuntimeDays
        - minSampleSize
        - sequentialTesting
        - startedAt
        - updatedAt
      additionalProperties: false
    DeleteExperimentResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
      required:
        - ok
      additionalProperties: false
    UpdateExperimentRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 128
          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
          description: Stable experiment key. Single segment or `folder.name` (a-z, 0-9, `_`/`-`; max 128 chars). Used by SDKs as `Shipeasy.getExperiment(user, '<name>')`. Immutable after create.
        description:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
        hypothesis:
          anyOf:
            - type: string
              maxLength: 4000
            - type: 'null'
        tag:
          anyOf:
            - type: string
              maxLength: 64
            - type: 'null'
        owner_email:
          anyOf:
            - type: string
              maxLength: 254
            - type: 'null'
        audience:
          anyOf:
            - type: string
              maxLength: 256
            - type: 'null'
        bucket_by:
          anyOf:
            - type: string
              minLength: 1
              maxLength: 128
              pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
              description: User-attribute name used as the bucketing key — e.g. `user_id` (default), `session_id`, `device_id`, or a custom attribute like `company_id` to keep a whole org on one variant. Defaults to `user_id` when omitted.
            - type: 'null'
        folder:
          $ref: '#/components/schemas/Folder'
        targeting_gate:
          anyOf:
            - type: string
            - type: 'null'
        holdout_gate:
          description: Per-experiment holdout gate — the name of a `holdout`-type flag, or `null` to clear. A caller the flag passes is held out.
          anyOf:
            - type: string
            - type: 'null'
        allocation_pct:
          description: Basis-points allocation (0–10000). Use `allocation_percent` (0–100) for percent. Immutable while the experiment is running.
          type: integer
          minimum: 0
          maximum: 10000
        reserved_headroom:
          description: Basis points of the split kept empty for appended variants. Group weights must sum to `10000 − reserved_headroom`. May be shrunk (never grown into existing weights) while running when appending a variant.
          type: integer
          minimum: 0
          maximum: 10000
        allocation_percent:
          description: Allocation as a **percentage** (0–100). Friendlier alias for `allocation_pct`; converted to basis points server-side. Wins over `allocation_pct` if both are supplied. Immutable while running.
          type: number
          minimum: 0
          maximum: 100
        salt:
          description: Hash salt. Immutable while running.
          type: string
          minLength: 1
          maxLength: 64
        universe:
          description: New universe name. Immutable while running. Returns `422` if the universe doesn't exist.
          type: string
        params:
          type: object
          additionalProperties:
            type: string
            enum:
              - string
              - bool
              - number
          description: '**Deprecated** — the universe owns the config schema (`param_schema`). Retained for back-compat. Map of param-name → scalar type.'
        groups:
          description: Replacement groups. Weights must sum to `10000 − reserved_headroom`. Existing weights/values are immutable while running; a new variant may be appended into the reserved tail.
          minItems: 2
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                minLength: 1
                maxLength: 64
                description: Group label (e.g. `control`, `treatment_a`). Max 64 chars.
              weight:
                type: integer
                minimum: 0
                maximum: 10000
                description: Allocation weight in basis points (0–10000). Weights across all groups must sum to `10000 − reserved_headroom`.
              params:
                default: {}
                description: Per-variant **override map** — a subset of the universe's `param_schema` keys. Unknown keys are rejected; unset keys inherit the universe default.
                type: object
                additionalProperties: {}
            required:
              - name
              - weight
            additionalProperties: false
            description: One variant. Its `params` may only override keys declared on the universe schema.
        significance_threshold:
          type: number
          minimum: 0.0001
          maximum: 0.5
        min_runtime_days:
          type: integer
          minimum: 0
          maximum: 365
        min_sample_size:
          type: integer
          minimum: 1
          maximum: 9007199254740991
        sequential_testing:
          type: boolean
        goal_metric:
          description: Replaces the goal metric — DSL `query` or `event` (+`aggregation`/`value`) the server compiles (event auto-upserted).
          $ref: '#/components/schemas/ExperimentInlineMetric'
        guardrail_metrics:
          description: Replaces the guardrail set wholesale (event auto-upserted per entry).
          maxItems: 10
          type: array
          items:
            $ref: '#/components/schemas/ExperimentInlineMetric'
      additionalProperties: false
      description: Body for `PATCH /api/admin/experiments/{id}`. Partial — only supplied fields change. `allocation_pct`, `salt`, `universe` and existing group weights/values are immutable while running (stop first); a new variant may still be appended into the reserved tail.
    UpdateExperimentResponse:
      type: object
      properties:
        id:
          type: string
          description: Experiment id that was updated.
      required:
        - id
      additionalProperties: false
    SetExperimentStatusRequest:
      type: object
      properties:
        status:
          type: string
          enum:
            - draft
            - running
            - stopped
            - archived
          description: 'Target status. Allowed transitions: `draft → running`, `running → stopped`, `stopped → archived`, `draft → archived`, and `archived → draft` (restore — only if the experiment never started). Restarting an archived experiment directly is not allowed; restore it to draft first, then start.'
      required:
        - status
      additionalProperties: false
      description: Body for `POST /api/admin/experiments/{id}/status`.
    SetExperimentStatusResponse:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - draft
            - running
            - stopped
            - archived
      required:
        - id
        - status
      additionalProperties: false
    SetExperimentMetricsRequest:
      type: object
      properties:
        metrics:
          type: array
          items:
            type: object
            properties:
              metric_id:
                type: string
                description: Existing metric id in the project.
              role:
                type: string
                enum:
                  - goal
                  - guardrail
                  - secondary
                description: Metric role. `goal` drives the decision, `guardrail` blocks ship if degraded, `secondary` is informational.
              min_effect_of_interest:
                description: Per-experiment override of the metric's `default_min_effect_of_interest` (relative, 0–1) — the smallest change worth acting on for THIS experiment's decision, which depends on the intervention's cost/risk. `null`/omitted falls back to the metric default. For a `guardrail` this is the non-inferiority margin (how large a regression is tolerated); for a `goal` it is the superiority threshold.
                default: null
                anyOf:
                  - type: number
                  - type: 'null'
            required:
              - metric_id
              - role
            additionalProperties: false
          description: Replacement metrics list — replaces the current attachments wholesale.
      required:
        - metrics
      additionalProperties: false
      description: Body for `POST /api/admin/experiments/{id}/metrics`. Replaces the experiment's metric attachments wholesale. Returns `422` if any `metric_id` is unknown.
    SetExperimentMetricsResponse:
      type: object
      properties:
        id:
          type: string
        metrics:
          type: array
          items:
            type: object
            properties:
              metric_id:
                type: string
              role:
                type: string
                enum:
                  - goal
                  - guardrail
                  - secondary
              min_effect_of_interest:
                description: The resolved per-experiment override, or `null` when this attachment inherits the metric's `default_min_effect_of_interest`.
                anyOf:
                  - type: number
                  - type: 'null'
            required:
              - metric_id
              - role
              - min_effect_of_interest
            additionalProperties: false
      required:
        - id
        - metrics
      additionalProperties: false
    GetExperimentResultsResponse:
      type: object
      properties:
        experiment:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
              maxLength: 128
              pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
              description: Stable experiment key. Single segment or `folder.name` (a-z, 0-9, `_`/`-`; max 128 chars). Used by SDKs as `Shipeasy.getExperiment(user, '<name>')`. Immutable after create.
            status:
              type: string
              enum:
                - draft
                - running
                - stopped
                - archived
          required:
            - id
            - name
            - status
          additionalProperties: false
        results:
          type: array
          items:
            type: object
            properties:
              metric:
                type: string
              group_name:
                type: string
              ds:
                type: string
                description: Date slice (`YYYY-MM-DD`).
              'n':
                anyOf:
                  - type: number
                  - type: 'null'
              mean:
                anyOf:
                  - type: number
                  - type: 'null'
              delta_pct:
                anyOf:
                  - type: number
                  - type: 'null'
              p_value:
                anyOf:
                  - type: number
                  - type: 'null'
              srm_detected:
                anyOf:
                  - type: number
                  - type: 'null'
                description: '`1` if sample-ratio mismatch detected, else `0`.'
              realized_mde:
                anyOf:
                  - type: number
                  - type: 'null'
                description: Realized minimum detectable effect (absolute, in metric units) — the smallest true effect this run could detect at the experiment's significance level and target power GIVEN the observed variance and per-arm sample sizes. A derived OUTPUT, not an input knob; compare it against the metric's minimum effect of interest to judge whether the run is adequately powered. `null` on the control row and on empty arms.
            required:
              - metric
              - group_name
              - ds
              - 'n'
              - mean
              - delta_pct
              - p_value
              - srm_detected
              - realized_mde
            additionalProperties: false
        verdict:
          type: string
          enum:
            - ship
            - hold
            - wait
            - invalid
            - draft
          description: 'Server-computed decision from the goal metric + guardrails + SRM vs. the significance threshold and min runtime: `ship` (goal significant + guardrails pass), `hold` (a guardrail regressed), `wait` (inconclusive / under-powered), `invalid` (sample-ratio mismatch), `draft` (never started).'
      required:
        - experiment
        - results
        - verdict
      additionalProperties: false
    GetExperimentTimeseriesResponse:
      type: object
      properties:
        experiment:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
              maxLength: 128
              pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
              description: Stable experiment key. Single segment or `folder.name` (a-z, 0-9, `_`/`-`; max 128 chars). Used by SDKs as `Shipeasy.getExperiment(user, '<name>')`. Immutable after create.
            status:
              type: string
              enum:
                - draft
                - running
                - stopped
                - archived
          required:
            - id
            - name
            - status
          additionalProperties: false
        series:
          type: array
          items:
            type: object
            properties:
              metric:
                type: string
              group_name:
                type: string
              ds:
                type: string
                description: Date slice (`YYYY-MM-DD`).
              'n':
                anyOf:
                  - type: number
                  - type: 'null'
              mean:
                anyOf:
                  - type: number
                  - type: 'null'
              delta_pct:
                anyOf:
                  - type: number
                  - type: 'null'
              p_value:
                anyOf:
                  - type: number
                  - type: 'null'
              srm_detected:
                anyOf:
                  - type: number
                  - type: 'null'
                description: '`1` if sample-ratio mismatch detected, else `0`.'
            required:
              - metric
              - group_name
              - ds
              - 'n'
              - mean
              - delta_pct
              - p_value
              - srm_detected
            additionalProperties: false
      required:
        - experiment
        - series
      additionalProperties: false
    ReanalyzeExperimentResponse:
      type: object
      properties:
        id:
          type: string
        queued:
          type: boolean
          const: true
      required:
        - id
        - queued
      additionalProperties: false
    ListConfigsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Stable opaque config id (`cfg_…`).
              name:
                type: string
                maxLength: 128
                description: Stable config key in `folder.name` form (two lowercase segments separated by a dot, e.g. `pricing.tiers`). Used by SDKs as `Shipeasy.getConfig('<name>')`. Immutable after create.
              description:
                anyOf:
                  - type: string
                  - type: 'null'
              schema:
                type: object
                additionalProperties: {}
                description: JSON Schema (draft 2020-12) describing the shape of the config value. Top-level `type` must be `'object'`; every published value is validated against this schema.
              updatedAt:
                type: string
                description: ISO-8601 timestamp of last mutation.
              envs:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    version:
                      type: integer
                      minimum: -9007199254740991
                      maximum: 9007199254740991
                      description: Monotonically increasing version per env.
                    publishedAt:
                      type: string
                      description: ISO-8601 publish timestamp.
                    publishedBy:
                      type: string
                      description: Email/id of the actor who published this version.
                  required:
                    - version
                    - publishedAt
                    - publishedBy
                  additionalProperties: false
                description: Per-env latest published version metadata.
              drafts:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    updatedAt:
                      type: string
                      description: ISO-8601 last-edit timestamp on the draft.
                    authorEmail:
                      type: string
                      description: Email/id of the actor who last edited the draft.
                    baseVersion:
                      type: integer
                      minimum: -9007199254740991
                      maximum: 9007199254740991
                      description: Published version the draft was forked from.
                  required:
                    - updatedAt
                    - authorEmail
                    - baseVersion
                  additionalProperties: false
                description: Per-env active drafts (if any).
              values:
                description: Per-env latest published values (only returned by `GET /{id}`, not list).
                type: object
                additionalProperties: {}
              draftValues:
                description: Per-env draft values (only returned by `GET /{id}`).
                type: object
                additionalProperties: {}
            required:
              - id
              - name
              - description
              - schema
              - updatedAt
              - envs
              - drafts
            additionalProperties: false
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - data
        - next_cursor
      additionalProperties: false
    ConfigName:
      type: string
      maxLength: 128
      pattern: ^(?:_default|[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$
      description: Stable config/killswitch key in `folder.name` form (two lowercase segments separated by a dot, e.g. `pricing.tiers`). Immutable after create.
    CreateConfigRequest:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ConfigName'
        description:
          description: Optional free-form description shown in the dashboard. Max 512 chars.
          type: string
          maxLength: 512
        folder:
          $ref: '#/components/schemas/Folder'
        schema:
          type: object
          additionalProperties: {}
          description: JSON Schema (draft 2020-12) describing the shape of the config value. Top-level `type` must be `'object'`; every published value is validated against this schema.
        value:
          description: 'Initial config value. Either a single JSON object applied to every env, or a `{ env: value }` map seeding per-env values. Must match `schema`. Defaults to `{}` on every env when omitted.'
      required:
        - name
        - schema
      additionalProperties: false
      description: Body for `POST /api/admin/configs`. `name` + `schema` required.
    CreateConfigResponse:
      type: object
      properties:
        id:
          type: string
          description: Newly assigned config id.
        name:
          type: string
          maxLength: 128
          description: Stable config key in `folder.name` form (two lowercase segments separated by a dot, e.g. `pricing.tiers`). Used by SDKs as `Shipeasy.getConfig('<name>')`. Immutable after create.
      required:
        - id
        - name
      additionalProperties: false
    GetConfigResponse:
      type: object
      properties:
        id:
          type: string
          description: Stable opaque config id (`cfg_…`).
        name:
          type: string
          maxLength: 128
          description: Stable config key in `folder.name` form (two lowercase segments separated by a dot, e.g. `pricing.tiers`). Used by SDKs as `Shipeasy.getConfig('<name>')`. Immutable after create.
        description:
          anyOf:
            - type: string
            - type: 'null'
        schema:
          type: object
          additionalProperties: {}
          description: JSON Schema (draft 2020-12) describing the shape of the config value. Top-level `type` must be `'object'`; every published value is validated against this schema.
        updatedAt:
          type: string
          description: ISO-8601 timestamp of last mutation.
        envs:
          type: object
          additionalProperties:
            type: object
            properties:
              version:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
                description: Monotonically increasing version per env.
              publishedAt:
                type: string
                description: ISO-8601 publish timestamp.
              publishedBy:
                type: string
                description: Email/id of the actor who published this version.
            required:
              - version
              - publishedAt
              - publishedBy
            additionalProperties: false
          description: Per-env latest published version metadata.
        drafts:
          type: object
          additionalProperties:
            type: object
            properties:
              updatedAt:
                type: string
                description: ISO-8601 last-edit timestamp on the draft.
              authorEmail:
                type: string
                description: Email/id of the actor who last edited the draft.
              baseVersion:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
                description: Published version the draft was forked from.
            required:
              - updatedAt
              - authorEmail
              - baseVersion
            additionalProperties: false
          description: Per-env active drafts (if any).
        values:
          description: Per-env latest published values (only returned by `GET /{id}`, not list).
          type: object
          additionalProperties: {}
        draftValues:
          description: Per-env draft values (only returned by `GET /{id}`).
          type: object
          additionalProperties: {}
      required:
        - id
        - name
        - description
        - schema
        - updatedAt
        - envs
        - drafts
      additionalProperties: false
    DeleteConfigResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
      required:
        - ok
      additionalProperties: false
    UpdateConfigRequest:
      type: object
      properties:
        schema:
          description: Replacement schema. When supplied, the new schema is validated against every published value before it lands.
          type: object
          additionalProperties: {}
        value:
          description: Flat value applied to **every** env. Publishes a new version per env. To target one env, use `PUT /{id}/drafts` then `POST /{id}/publish`.
        folder:
          $ref: '#/components/schemas/Folder'
      additionalProperties: false
      description: Body for `PATCH /api/admin/configs/{id}`. Partial — only supplied fields change. `value` republishes on every env.
    UpdateConfigResponse:
      type: object
      properties:
        id:
          type: string
          description: Config id that was updated.
      required:
        - id
      additionalProperties: false
    Env:
      type: string
      enum:
        - dev
        - staging
        - prod
      description: Target environment. One of the project's configured envs (`dev`, `staging`, `prod`).
    SaveConfigDraftRequest:
      type: object
      properties:
        env:
          $ref: '#/components/schemas/Env'
        value:
          description: Draft value to stage on `env`. Validated against the config's current schema.
      required:
        - env
        - value
      additionalProperties: false
      description: Body for `PUT /api/admin/configs/{id}/drafts`. Stages a value for a single env without publishing.
    SaveConfigDraftResponse:
      type: object
      properties:
        id:
          type: string
        env:
          $ref: '#/components/schemas/Env'
        baseVersion:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Published version the draft is based on.
        updatedAt:
          type: string
      required:
        - id
        - env
        - baseVersion
        - updatedAt
      additionalProperties: false
    DiscardConfigDraftRequest:
      type: object
      properties:
        env:
          $ref: '#/components/schemas/Env'
      required:
        - env
      additionalProperties: false
      description: Body for `POST /api/admin/configs/{id}/publish` and `DELETE /api/admin/configs/{id}/drafts`. Names the target env.
    DiscardConfigDraftResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
      required:
        - ok
      additionalProperties: false
    PublishConfigDraftRequest:
      type: object
      properties:
        env:
          $ref: '#/components/schemas/Env'
      required:
        - env
      additionalProperties: false
      description: Body for `POST /api/admin/configs/{id}/publish` and `DELETE /api/admin/configs/{id}/drafts`. Names the target env.
    PublishConfigDraftResponse:
      type: object
      properties:
        id:
          type: string
        env:
          $ref: '#/components/schemas/Env'
        version:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Newly published version on `env`.
      required:
        - id
        - env
        - version
      additionalProperties: false
    ListConfigActivityResponse:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
          action:
            type: string
            description: Audit action (e.g. `config.create`, `config.publish`).
          actorEmail:
            type: string
          actorType:
            type: string
            enum:
              - user
              - cli
              - system
          payload: {}
          createdAt:
            type: string
            description: ISO-8601 timestamp.
        required:
          - id
          - action
          - actorEmail
          - actorType
          - payload
          - createdAt
        additionalProperties: false
      description: Recent audit rows for one config, newest first.
    UpdateConfigSchemaRequest:
      type: object
      properties:
        schema:
          description: Replacement JSON Schema (draft 2020-12). Validated against every published value before it lands.
          type: object
          additionalProperties: {}
      required:
        - schema
      additionalProperties: false
      description: Body for `PATCH /api/admin/configs/{id}/schema`. Schema-only update — replaces the config's schema and re-validates existing values.
    UpdateConfigSchemaResponse:
      type: object
      properties:
        id:
          type: string
          description: Config id whose schema was updated.
      required:
        - id
      additionalProperties: false
    ListKillswitchesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Stable opaque killswitch id.
              name:
                type: string
                maxLength: 128
                description: Stable config key in `folder.name` form (two lowercase segments separated by a dot, e.g. `pricing.tiers`). Used by SDKs as `Shipeasy.getConfig('<name>')`. Immutable after create.
              description:
                anyOf:
                  - type: string
                  - type: 'null'
                description: Free-form description or `null`.
              updatedAt:
                type: string
                description: ISO-8601 timestamp of last mutation.
              envs:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    value:
                      type: boolean
                      description: Flat boolean published for this env.
                    switches:
                      type: object
                      additionalProperties:
                        type: boolean
                    version:
                      type: integer
                      minimum: -9007199254740991
                      maximum: 9007199254740991
                      description: Monotonically increasing version per env.
                    publishedAt:
                      type: string
                      description: ISO-8601 publish timestamp for this version.
                    publishedBy:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: Email/id of the actor who published this version.
                  required:
                    - value
                    - version
                    - publishedAt
                  additionalProperties: false
                description: Per-env latest value, switches, version, and publish timestamp.
            required:
              - id
              - name
              - description
              - updatedAt
              - envs
            additionalProperties: false
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - data
        - next_cursor
      additionalProperties: false
    CreateKillswitchRequest:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ConfigName'
        description:
          description: Optional free-form description shown in the dashboard. Max 512 chars.
          type: string
          maxLength: 512
        folder:
          $ref: '#/components/schemas/Folder'
        value:
          description: Default value applied to every env at creation. Defaults to `false`. Use `true` to ship the killswitch pre-tripped.
          type: boolean
        switches:
          description: Initial per-switch overrides applied to every env. Empty/omitted leaves the killswitch with only the flat `value`.
          type: object
          additionalProperties:
            type: boolean
      required:
        - name
      additionalProperties: false
      description: Body for `POST /api/admin/killswitches`. Only `name` is required.
    CreateKillswitchResponse:
      type: object
      properties:
        id:
          type: string
          description: Newly assigned killswitch id.
        name:
          type: string
          maxLength: 128
          description: Stable config key in `folder.name` form (two lowercase segments separated by a dot, e.g. `pricing.tiers`). Used by SDKs as `Shipeasy.getConfig('<name>')`. Immutable after create.
      required:
        - id
        - name
      additionalProperties: false
    GetKillswitchResponse:
      type: object
      properties:
        id:
          type: string
          description: Stable opaque killswitch id.
        name:
          type: string
          maxLength: 128
          description: Stable config key in `folder.name` form (two lowercase segments separated by a dot, e.g. `pricing.tiers`). Used by SDKs as `Shipeasy.getConfig('<name>')`. Immutable after create.
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: Free-form description or `null`.
        updatedAt:
          type: string
          description: ISO-8601 timestamp of last mutation.
        envs:
          type: object
          additionalProperties:
            type: object
            properties:
              value:
                type: boolean
                description: Flat boolean published for this env.
              switches:
                type: object
                additionalProperties:
                  type: boolean
              version:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
                description: Monotonically increasing version per env.
              publishedAt:
                type: string
                description: ISO-8601 publish timestamp for this version.
              publishedBy:
                anyOf:
                  - type: string
                  - type: 'null'
                description: Email/id of the actor who published this version.
            required:
              - value
              - version
              - publishedAt
            additionalProperties: false
          description: Per-env latest value, switches, version, and publish timestamp.
      required:
        - id
        - name
        - description
        - updatedAt
        - envs
      additionalProperties: false
    DeleteKillswitchResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
      required:
        - ok
      additionalProperties: false
    UpdateKillswitchRequest:
      type: object
      properties:
        description:
          description: New description, or `null` to clear it. Max 512 chars.
          anyOf:
            - type: string
              maxLength: 512
            - type: 'null'
        folder:
          $ref: '#/components/schemas/Folder'
        value:
          description: Flat value applied to every env. Publishes a new version per env when set. Omit to leave values unchanged.
          type: boolean
        switches:
          description: Replace the switches map wholesale on every env. To edit a single entry on a single env use `PUT /{id}/switch` instead.
          type: object
          additionalProperties:
            type: boolean
      additionalProperties: false
      description: Body for `PATCH /api/admin/killswitches/{id}`. Partial — only supplied fields change. `switches` replaces wholesale (no merge).
    UpdateKillswitchResponse:
      type: object
      properties:
        id:
          type: string
          description: Killswitch id that was updated.
      required:
        - id
      additionalProperties: false
    SetKillswitchSwitchRequest:
      type: object
      properties:
        env:
          $ref: '#/components/schemas/Env'
        switchKey:
          type: string
          maxLength: 64
          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$
          description: Switch key to set.
        value:
          type: boolean
          description: New boolean value for this `switchKey` on this `env`.
      required:
        - env
        - switchKey
        - value
      additionalProperties: false
      description: Body for `PUT /api/admin/killswitches/{id}/switch`. Sets or updates one switch entry on one env.
    SetKillswitchSwitchResponse:
      type: object
      properties:
        id:
          type: string
        env:
          $ref: '#/components/schemas/Env'
        switchKey:
          type: string
          maxLength: 64
          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$
          description: Single-segment switch key (lowercase letters, digits, `_`/`-`; no dots). Used as the nested switch entry inside a killswitch's `switches` map.
        value:
          type: boolean
      required:
        - id
        - env
        - switchKey
        - value
      additionalProperties: false
    UnsetKillswitchSwitchRequest:
      type: object
      properties:
        env:
          $ref: '#/components/schemas/Env'
        switchKey:
          type: string
          maxLength: 64
          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$
          description: Switch key to remove.
      required:
        - env
        - switchKey
      additionalProperties: false
      description: Body for `DELETE /api/admin/killswitches/{id}/switch`. Removes one switch entry from one env.
    UnsetKillswitchSwitchResponse:
      type: object
      properties:
        id:
          type: string
        env:
          $ref: '#/components/schemas/Env'
        switchKey:
          type: string
          maxLength: 64
          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$
          description: Single-segment switch key (lowercase letters, digits, `_`/`-`; no dots). Used as the nested switch entry inside a killswitch's `switches` map.
        removed:
          type: boolean
          description: '`true` if the entry existed and was removed, `false` if no-op.'
      required:
        - id
        - env
        - switchKey
        - removed
      additionalProperties: false
    SetKillswitchValueRequest:
      type: object
      properties:
        env:
          $ref: '#/components/schemas/Env'
        value:
          type: boolean
          description: Flat boolean to publish on `env`. Publishes a new version on that env only.
      required:
        - env
        - value
      additionalProperties: false
      description: Body for `PUT /api/admin/killswitches/{id}/value`. Sets the flat `value` on one env without touching `switches` or other envs.
    KillswitchValue:
      type: object
      properties:
        value:
          type: boolean
          description: Default boolean delivered when no `switches` entry matches.
        switches:
          type: object
          additionalProperties:
            type: boolean
          description: Per-switch overrides; a matching key takes precedence over `value`.
      required:
        - value
      additionalProperties: false
      description: Runtime killswitch payload returned to SDKs.
    SetKillswitchValueResponse:
      type: object
      properties:
        id:
          type: string
        env:
          $ref: '#/components/schemas/Env'
        version:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Newly published version on `env`.
        published:
          $ref: '#/components/schemas/KillswitchValue'
      required:
        - id
        - env
        - version
        - published
      additionalProperties: false
    UniverseParam:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 128
          pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
          description: Param key, referenced by `groups[].params` on every experiment in the universe.
        type:
          type: string
          enum:
            - bool
            - string
            - int
            - number
          description: Scalar type of the param's value.
        default:
          description: 'Universe-wide default. Returned when the assigned variant doesn''t override this param (resolution: variant override → universe default).'
      required:
        - name
        - type
        - default
      additionalProperties: false
    UniverseParamSchema:
      type: array
      items:
        $ref: '#/components/schemas/UniverseParam'
      description: The universe's ordered config schema — the single source of truth for its params.
    ListUniversesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Stable opaque universe id.
              name:
                type: string
                maxLength: 128
                pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
                description: Stable universe key. Single segment or `folder.name`. Lowercase letters, digits, `_` or `-`; max 128 chars. Immutable after create.
              description:
                anyOf:
                  - type: string
                  - type: 'null'
                description: Human-readable blurb shown in the universe picker/hovercard.
              unitType:
                type: string
                description: Unit of randomisation. Snake-case in request (`unit_type`), camelCase in response.
              holdoutRange:
                anyOf:
                  - type: array
                    items:
                      type: number
                    minItems: 2
                    maxItems: 2
                  - type: 'null'
                description: Reserved holdout bucket range, or `null` if none.
              recommendedHeadroom:
                type: integer
                minimum: 0
                maximum: 10000
                description: Basis points of headroom seeded into each new experiment's reserved tail (0 = none).
              paramSchema:
                anyOf:
                  - $ref: '#/components/schemas/UniverseParamSchema'
                  - type: 'null'
                description: The universe-owned config schema, or `null` on pre-rework universes not yet seeded.
              createdAt:
                type: string
                description: ISO-8601 timestamp of creation.
            required:
              - id
              - name
              - unitType
              - holdoutRange
              - createdAt
            additionalProperties: false
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - data
        - next_cursor
      additionalProperties: false
    CreateUniverseRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 128
          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
          description: Stable universe key. Single segment or `folder.name`. Lowercase letters, digits, `_` or `-`; max 128 chars. Immutable after create.
        folder:
          $ref: '#/components/schemas/Folder'
        description:
          default: null
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
          description: Human-readable blurb shown in the universe picker/hovercard.
        unit_type:
          default: user_id
          description: Unit of randomisation. Typically `user_id`. Use `account_id` to keep whole accounts in the same group across an experiment.
          type: string
        holdout_range:
          default: null
          anyOf:
            - type: array
              items:
                type: integer
                minimum: 0
                maximum: 9999
              minItems: 2
              maxItems: 2
            - type: 'null'
          description: Inclusive `[lo, hi]` bucket range (0–9999) reserved as the **holdout** — callers hashed into this slice are excluded from every experiment in the universe. `null` disables the holdout. Pro plan or higher required.
        recommended_headroom:
          default: 0
          type: integer
          minimum: 0
          maximum: 10000
          description: Basis points of reserved headroom seeded into each new experiment created in this universe (0 = none). Lets variants be appended into a running experiment without reshuffling.
        param_schema:
          default: null
          anyOf:
            - $ref: '#/components/schemas/UniverseParamSchema'
            - type: 'null'
          description: The universe-owned config schema — an ordered `{ name, type, default }[]`. Experiments may only override values per variant, never add fields. `null` starts an empty schema.
      required:
        - name
      additionalProperties: false
      description: Body for `POST /api/admin/universes`. Only `name` is required.
    CreateUniverseResponse:
      type: object
      properties:
        id:
          type: string
          description: Newly assigned universe id.
        name:
          type: string
          maxLength: 128
          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
          description: Stable universe key. Single segment or `folder.name`. Lowercase letters, digits, `_` or `-`; max 128 chars. Immutable after create.
      required:
        - id
        - name
      additionalProperties: false
    DeleteUniverseResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
      required:
        - ok
      additionalProperties: false
    UpdateUniverseRequest:
      type: object
      properties:
        folder:
          $ref: '#/components/schemas/Folder'
        description:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
          description: Human-readable blurb shown in the universe picker/hovercard.
        holdout_range:
          anyOf:
            - type: array
              items:
                type: integer
                minimum: 0
                maximum: 9999
              minItems: 2
              maxItems: 2
            - type: 'null'
          description: Inclusive `[lo, hi]` bucket range (0–9999) reserved as the **holdout** — callers hashed into this slice are excluded from every experiment in the universe. `null` disables the holdout. Pro plan or higher required.
        recommended_headroom:
          type: integer
          minimum: 0
          maximum: 10000
          description: Basis points of reserved headroom seeded into new experiments in this universe.
        param_schema:
          anyOf:
            - $ref: '#/components/schemas/UniverseParamSchema'
            - type: 'null'
          description: Replace the universe config schema. Additive changes + default edits are always allowed; removing a param a running experiment overrides is rejected (deprecate-only).
      additionalProperties: false
      description: Body for `PATCH /api/admin/universes/{id}`. `name` and `unit_type` are immutable after create; `holdout_range`, `description`, `recommended_headroom` and `param_schema` are mutable.
    UpdateUniverseResponse:
      type: object
      properties:
        id:
          type: string
          description: Universe id that was updated.
      required:
        - id
      additionalProperties: false
    GateTemplateRuleResponse:
      type: object
      properties:
        attr:
          type: string
          description: Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input. May be empty on a built-in template whose attribute is supplied at substitution time (e.g. the `exp_in` "in any experiment" preset — you fill in the experiment name).
        op:
          type: string
          enum:
            - eq
            - neq
            - in
            - not_in
            - gt
            - gte
            - lt
            - lte
            - contains
            - regex
            - semver_gt
            - semver_gte
            - semver_lt
            - semver_lte
            - gate_pass
            - exp_in
          description: 'Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte`. String: `contains` (substring), `regex` (JS-flavour pattern). Cross-resource: `gate_pass` (value is another gate''s name), `exp_in` (attr is an experiment name, value is a variant / `"$holdout"` / `"$any"`).'
        value:
          description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; variant selector for `exp_in`.'
      required:
        - attr
        - op
      additionalProperties: false
      description: Single targeting predicate as returned by the API. `value` is optional here — read-only built-in templates (e.g. `@owner`, or presets whose operand is supplied at substitution time) legitimately omit it. Request bodies still require `value`.
    GateTemplate:
      type: object
      description: 'A reusable targeting-rule template. Built-ins are read-only (`builtin: true`, stable slug `id`); per-project customer templates are `builtin: false` with a `gtpl_…` id.'
      properties:
        id:
          type: string
          description: Stable slug for built-ins (`country`), `gtpl_…` for customer templates.
        name:
          type: string
          description: Human label shown in pickers (`Country is`).
        description:
          type: string
          description: One-liner — feeds the list `query` filter.
        category:
          type: string
          enum:
            - condition
            - rollout
          description: '`condition` = rule-based predicate, `rollout` = percentage bucket.'
        auto:
          type: boolean
          description: True when the attribute is request-derived (country/browser/…) and resolved at the SDK edge, so the caller need not pass it.
        builtin:
          type: boolean
          description: Read-only built-in (`true`) vs editable customer template (`false`).
        iconKey:
          anyOf:
            - type: string
            - type: 'null'
          description: Display-only icon hint.
        rules:
          type: array
          items:
            $ref: '#/components/schemas/GateTemplateRuleResponse'
          description: The rule definition — copy, substitute the value(s), pass as `rules`.
        createdAt:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-8601 creation timestamp; `null` for built-ins.
        updatedAt:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-8601 last-mutation timestamp; `null` for built-ins.
      required:
        - id
        - name
        - description
        - category
        - auto
        - builtin
        - rules
      additionalProperties: false
    ListGateTemplatesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GateTemplate'
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - data
        - next_cursor
      additionalProperties: false
    GateTemplateRule:
      type: object
      properties:
        attr:
          type: string
          description: Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input. May be empty on a built-in template whose attribute is supplied at substitution time (e.g. the `exp_in` "in any experiment" preset — you fill in the experiment name).
        op:
          type: string
          enum:
            - eq
            - neq
            - in
            - not_in
            - gt
            - gte
            - lt
            - lte
            - contains
            - regex
            - semver_gt
            - semver_gte
            - semver_lt
            - semver_lte
            - gate_pass
            - exp_in
          description: 'Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte`. String: `contains` (substring), `regex` (JS-flavour pattern). Cross-resource: `gate_pass` (value is another gate''s name), `exp_in` (attr is an experiment name, value is a variant / `"$holdout"` / `"$any"`).'
        value:
          description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; variant selector for `exp_in`. Required on every request rule (value-ops need it; the valueless built-in presets are read-only and never created via the API).'
          anyOf:
            - type: string
            - type: number
            - type: boolean
            - type: array
              items: {}
      required:
        - attr
        - op
        - value
      additionalProperties: false
      description: Single targeting predicate. Copy a template's rules, substitute the concrete `value`(s), and pass them as the `rules` arg of `release_flags_create`.
    CreateGateTemplateRequest:
      type: object
      description: Body for `POST /api/admin/gate-templates`. Creates a per-project (customer) template. At minimum supply `name` + `rules`.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 140
          description: Human label. Unique per project.
        description:
          type: string
          maxLength: 2000
          default: ''
          description: One-liner shown in pickers and matched by the list `query` filter.
        category:
          type: string
          enum:
            - condition
            - rollout
          default: condition
        icon_key:
          type: string
          maxLength: 64
          description: Display-only icon hint.
        auto:
          type: boolean
          default: false
          description: Mark the attribute as request-derived (resolved at the SDK edge).
        rules:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/GateTemplateRule'
          description: The rule definition captured by the template.
      required:
        - name
        - rules
      additionalProperties: false
    CreateGateTemplateResponse:
      type: object
      properties:
        id:
          type: string
          description: Newly assigned template id (`gtpl_…`).
        name:
          type: string
      required:
        - id
        - name
      additionalProperties: false
    DeleteGateTemplateResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
      required:
        - ok
      additionalProperties: false
    UpdateGateTemplateRequest:
      type: object
      description: Body for `PATCH /api/admin/gate-templates/{id}`. Partial — only supplied fields change. `rules` replaces wholesale. Built-in templates are read-only (409).
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 140
        description:
          type: string
          maxLength: 2000
        category:
          type: string
          enum:
            - condition
            - rollout
        icon_key:
          anyOf:
            - type: string
            - type: 'null'
        auto:
          type: boolean
        rules:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/GateTemplateRule'
      additionalProperties: false
    UpdateGateTemplateResponse:
      type: object
      properties:
        id:
          type: string
      required:
        - id
      additionalProperties: false
    ListAttributesResponse:
      type: array
      items:
        type: object
        properties:
          name:
            type: string
            description: Attribute key as seen in evaluation context (e.g. `plan`, `country`).
          type:
            description: Inferred value type (`string`, `number`, `boolean`, …) when known.
            type: string
        required:
          - name
        additionalProperties: {}
        description: One auto-inferred targeting attribute.
      description: Every auto-inferred targeting attribute in the project.
    AttributeType:
      type: string
      enum:
        - string
        - number
        - boolean
        - enum
        - date
      description: Declared value type of a targeting attribute.
    CreateAttributeRequest:
      type: object
      properties:
        name:
          type: string
          pattern: ^[a-z0-9][a-z0-9_-]{0,63}$
          description: Attribute key (lowercase alphanumeric start, then letters/digits/`_`/`-`; max 64 chars). Immutable after create.
        type:
          $ref: '#/components/schemas/AttributeType'
        enum_values:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          default: null
          description: Allowed values when `type` is `enum` (required in that case — 422 otherwise); `null` for non-enum types.
        required:
          type: boolean
          default: false
          description: Whether the attribute must be present on the evaluation context.
        description:
          type: string
          description: Optional human note shown in the dashboard.
        sdk_path:
          type: string
          description: Optional dotted path the SDK reads the value from.
      required:
        - name
        - type
      additionalProperties: false
      description: Body for `POST /api/admin/attributes`. Declares a targeting attribute.
    CreateAttributeResponse:
      type: object
      properties:
        id:
          type: string
          description: Newly assigned attribute id.
        name:
          type: string
          description: The attribute key that was created.
      required:
        - id
        - name
      additionalProperties: false
      description: Response for `POST /api/admin/attributes`.
    GetAttributeResponse:
      type: object
      properties:
        id:
          type: string
          description: Stable opaque attribute id.
        name:
          type: string
          description: Attribute key.
        type:
          $ref: '#/components/schemas/AttributeType'
        enumValues:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          description: Allowed values for `enum` attributes, else `null`.
        required:
          type: integer
          enum:
            - 0
            - 1
          description: Whether the attribute is required (D1 stores the flag as `0`/`1`).
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: Human note, or `null`.
        sdkPath:
          anyOf:
            - type: string
            - type: 'null'
          description: Dotted SDK path, or `null`.
        createdAt:
          type: string
          description: ISO-8601 creation timestamp.
      required:
        - id
        - name
        - type
      additionalProperties: {}
      description: One targeting attribute row.
    DeleteAttributeResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: True when the attribute was archived.
      required:
        - ok
      additionalProperties: false
      description: Response for `DELETE /api/admin/attributes/{id}`.
    UpdateAttributeRequest:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/AttributeType'
        enum_values:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          description: Replacement allowed values (for `enum`), or `null` to clear.
        required:
          type: boolean
          description: Whether the attribute must be present on the evaluation context.
        description:
          type: string
          description: Optional human note shown in the dashboard.
        sdk_path:
          type: string
          description: Optional dotted path the SDK reads the value from.
      additionalProperties: false
      description: Body for `PATCH /api/admin/attributes/{id}`. Every field is optional; `name` is immutable.
    UpdateAttributeResponse:
      type: object
      properties:
        id:
          type: string
          description: Id of the attribute that was updated.
      required:
        - id
      additionalProperties: false
      description: Response for `PATCH /api/admin/attributes/{id}`.
    QueryIr:
      description: Typed query IR — the structured alternative to the `query` DSL string. Exactly one of `query` / `query_ir` is supplied per metric body.
      type: object
      properties:
        agg:
          oneOf:
            - type: object
              properties:
                kind:
                  type: string
                  const: count_users
              required:
                - kind
              additionalProperties: false
            - type: object
              properties:
                kind:
                  type: string
                  const: count_events
              required:
                - kind
              additionalProperties: false
            - type: object
              properties:
                kind:
                  type: string
                  const: sum
              required:
                - kind
              additionalProperties: false
            - type: object
              properties:
                kind:
                  type: string
                  const: avg
              required:
                - kind
              additionalProperties: false
            - type: object
              properties:
                kind:
                  type: string
                  const: min
              required:
                - kind
              additionalProperties: false
            - type: object
              properties:
                kind:
                  type: string
                  const: max
              required:
                - kind
              additionalProperties: false
            - type: object
              properties:
                kind:
                  type: string
                  const: unique
              required:
                - kind
              additionalProperties: false
            - type: object
              properties:
                kind:
                  type: string
                  const: quantile
                p:
                  anyOf:
                    - type: number
                      const: 0.5
                    - type: number
                      const: 0.75
                    - type: number
                      const: 0.9
                    - type: number
                      const: 0.95
                    - type: number
                      const: 0.99
                    - type: number
                      const: 0.999
                  description: Quantile fraction (0.5 = p50 … 0.999 = p999).
              required:
                - kind
                - p
              additionalProperties: false
            - type: object
              properties:
                kind:
                  type: string
                  const: retention_Nd
                'n':
                  type: integer
                  minimum: 1
                  maximum: 90
                  description: Retention window in days (1–90).
              required:
                - kind
                - 'n'
              additionalProperties: false
            - type: object
              properties:
                kind:
                  type: string
                  const: ratio
                numerator:
                  type: object
                  properties:
                    agg:
                      type: string
                      enum:
                        - count_users
                        - count_events
                      description: Counting mode for this ratio arm.
                    metric:
                      type: string
                      minLength: 1
                      maxLength: 128
                      description: Source event name for this ratio arm.
                    filters:
                      description: Optional label filters.
                      maxItems: 16
                      type: array
                      items:
                        type: object
                        properties:
                          label:
                            type: string
                            pattern: ^[a-z_][a-z0-9_]{0,63}$
                            description: Event property / label identifier.
                          op:
                            type: string
                            enum:
                              - '='
                              - '!='
                              - '=~'
                              - '!~'
                            description: Match operator (`=~`/`!~` are regex).
                          value:
                            type: string
                            maxLength: 512
                            description: Quoted filter value (coerced for numeric labels).
                        required:
                          - label
                          - op
                          - value
                        additionalProperties: false
                        description: One label filter on the source event.
                  required:
                    - agg
                    - metric
                  additionalProperties: false
                  description: Numerator or denominator arm of a `ratio` aggregation.
                denominator:
                  type: object
                  properties:
                    agg:
                      type: string
                      enum:
                        - count_users
                        - count_events
                      description: Counting mode for this ratio arm.
                    metric:
                      type: string
                      minLength: 1
                      maxLength: 128
                      description: Source event name for this ratio arm.
                    filters:
                      description: Optional label filters.
                      maxItems: 16
                      type: array
                      items:
                        type: object
                        properties:
                          label:
                            type: string
                            pattern: ^[a-z_][a-z0-9_]{0,63}$
                            description: Event property / label identifier.
                          op:
                            type: string
                            enum:
                              - '='
                              - '!='
                              - '=~'
                              - '!~'
                            description: Match operator (`=~`/`!~` are regex).
                          value:
                            type: string
                            maxLength: 512
                            description: Quoted filter value (coerced for numeric labels).
                        required:
                          - label
                          - op
                          - value
                        additionalProperties: false
                        description: One label filter on the source event.
                  required:
                    - agg
                    - metric
                  additionalProperties: false
                  description: Numerator or denominator arm of a `ratio` aggregation.
              required:
                - kind
                - numerator
                - denominator
              additionalProperties: false
          description: Aggregation function applied to the source event.
        metric:
          type: string
          minLength: 1
          maxLength: 128
          description: Source event name (must equal `event_name`).
        valueLabel:
          description: Numeric property summed/averaged for `sum`/`avg`/quantile aggregations.
          type: string
          minLength: 1
          maxLength: 128
        filters:
          default: []
          description: Label filters on the event.
          maxItems: 16
          type: array
          items:
            type: object
            properties:
              label:
                type: string
                pattern: ^[a-z_][a-z0-9_]{0,63}$
                description: Event property / label identifier.
              op:
                type: string
                enum:
                  - '='
                  - '!='
                  - '=~'
                  - '!~'
                description: Match operator (`=~`/`!~` are regex).
              value:
                type: string
                maxLength: 512
                description: Quoted filter value (coerced for numeric labels).
            required:
              - label
              - op
              - value
            additionalProperties: false
            description: One label filter on the source event.
        groupBy:
          type: object
          properties:
            op:
              type: string
              enum:
                - by
                - without
              description: '`by` keeps the listed labels; `without` drops them.'
            labels:
              maxItems: 5
              type: array
              items:
                type: string
                pattern: ^[a-z_][a-z0-9_]{0,63}$
                description: Event property / label identifier.
              description: Labels to group by (max 5).
          required:
            - op
            - labels
          additionalProperties: false
          description: Optional group-by clause (ignored for experiment analysis).
      required:
        - agg
        - metric
      additionalProperties: false
    ListMetricsResponse:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            description: Stable opaque metric id.
          name:
            type: string
            description: Metric key.
          folder:
            anyOf:
              - type: string
              - type: 'null'
            description: Folder grouping the metric, or `null`.
          eventName:
            type: string
            description: Source event name (camelCase in response).
          query:
            description: Rendered DSL text form of the query, or `null` if it could not be rendered.
            anyOf:
              - type: string
              - type: 'null'
          queryIr:
            $ref: '#/components/schemas/QueryIr'
          direction:
            type: string
            enum:
              - higher_better
              - lower_better
              - neutral
            description: Desired direction of movement. `higher_better` (default), `lower_better`, or `neutral` (guardrail).
          winsorizePct:
            description: Winsorise percentile applied to the metric.
            type: number
          defaultMinEffectOfInterest:
            description: Metric-level default minimum effect of interest (relative, 0–1), or `null`.
            anyOf:
              - type: number
              - type: 'null'
          createdAt:
            description: ISO-8601 creation timestamp.
            type: string
          updatedAt:
            description: ISO-8601 last-update timestamp.
            type: string
        required:
          - id
          - name
          - folder
          - eventName
          - query
          - queryIr
        additionalProperties: {}
        description: A metric definition.
      description: Every metric in the project (the list endpoint is not paginated).
    MetricEventName:
      type: string
      minLength: 1
      description: Source event the query reads from.
    MetricQueryDsl:
      description: Metric query DSL string, e.g. `sum(purchase, amount)`. The alternative to `query_ir`. Every label the query references — in filters, the value position, `by (…)`, or `without (…)` — must exist as a property on the tracked event's payload; a query over a label the event never carries validates fine but returns empty results.
      type: string
      minLength: 1
      maxLength: 4096
    MetricWinsorizePct:
      default: 99
      description: Winsorise percentile (1–99) to clamp outliers. Defaults to 99.
      type: integer
      minimum: 1
      maximum: 99
    MetricDefaultMinEffectOfInterest:
      default: null
      description: Default minimum effect of interest (relative, 0–1) — the smallest change in this metric worth acting on, used as the power-planning baseline. Intrinsic to the metric; an experiment overrides it per-attachment with `min_effect_of_interest` when a specific decision has a different cost/risk bar. `null` to omit.
      anyOf:
        - type: number
        - type: 'null'
    MetricDirection:
      default: higher_better
      type: string
      enum:
        - higher_better
        - lower_better
        - neutral
      description: Desired direction of movement. `higher_better` (default), `lower_better`, or `neutral` (guardrail).
    CreateMetricWithQuery:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/MetricName'
        folder:
          $ref: '#/components/schemas/Folder'
        event_name:
          $ref: '#/components/schemas/MetricEventName'
        query:
          $ref: '#/components/schemas/MetricQueryDsl'
        winsorize_pct:
          $ref: '#/components/schemas/MetricWinsorizePct'
        default_min_effect_of_interest:
          $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
        direction:
          $ref: '#/components/schemas/MetricDirection'
      required:
        - name
        - event_name
        - query
      additionalProperties: false
      description: Create a metric, supplying the query as a `query` DSL string.
    CreateMetricWithQueryIr:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/MetricName'
        folder:
          $ref: '#/components/schemas/Folder'
        event_name:
          $ref: '#/components/schemas/MetricEventName'
        query_ir:
          $ref: '#/components/schemas/QueryIr'
        winsorize_pct:
          $ref: '#/components/schemas/MetricWinsorizePct'
        default_min_effect_of_interest:
          $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
        direction:
          $ref: '#/components/schemas/MetricDirection'
      required:
        - name
        - event_name
        - query_ir
      additionalProperties: false
      description: Create a metric, supplying the query as a typed `query_ir`.
    CreateMetricRequest:
      oneOf:
        - $ref: '#/components/schemas/CreateMetricWithQuery'
        - $ref: '#/components/schemas/CreateMetricWithQueryIr'
      description: Body for `POST /api/admin/metrics`. Requires `name`, `event_name`, and exactly one of `query` / `query_ir` — modelled as a `oneOf` of two strict variants, so supplying both (or neither) is rejected.
    CreateMetricResponse:
      type: object
      properties:
        id:
          type: string
          description: Newly assigned metric id.
        name:
          type: string
          description: Metric name that was created.
      required:
        - id
        - name
      additionalProperties: false
      description: Result of a successful metric create.
    GetMetricResponse:
      type: object
      properties:
        id:
          type: string
          description: Stable opaque metric id.
        name:
          type: string
          description: Metric key.
        folder:
          anyOf:
            - type: string
            - type: 'null'
          description: Folder grouping the metric, or `null`.
        eventName:
          type: string
          description: Source event name (camelCase in response).
        query:
          description: Rendered DSL text form of the query, or `null` if it could not be rendered.
          anyOf:
            - type: string
            - type: 'null'
        queryIr:
          $ref: '#/components/schemas/QueryIr'
        direction:
          type: string
          enum:
            - higher_better
            - lower_better
            - neutral
          description: Desired direction of movement. `higher_better` (default), `lower_better`, or `neutral` (guardrail).
        winsorizePct:
          description: Winsorise percentile applied to the metric.
          type: number
        defaultMinEffectOfInterest:
          description: Metric-level default minimum effect of interest (relative, 0–1), or `null`.
          anyOf:
            - type: number
            - type: 'null'
        createdAt:
          description: ISO-8601 creation timestamp.
          type: string
        updatedAt:
          description: ISO-8601 last-update timestamp.
          type: string
      required:
        - id
        - name
        - folder
        - eventName
        - query
        - queryIr
      additionalProperties: {}
      description: A metric definition.
    DeleteMetricResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
      required:
        - ok
      additionalProperties: false
      description: Soft-delete (archive) acknowledgement.
    UpdateMetricWithQuery:
      type: object
      properties:
        folder:
          $ref: '#/components/schemas/Folder'
        event_name:
          $ref: '#/components/schemas/MetricEventName'
        query:
          $ref: '#/components/schemas/MetricQueryDsl'
        winsorize_pct:
          $ref: '#/components/schemas/MetricWinsorizePct'
        default_min_effect_of_interest:
          $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
        direction:
          $ref: '#/components/schemas/MetricDirection'
      required:
        - query
      additionalProperties: false
      description: Update-metric variant that replaces the query with a `query` DSL string.
    UpdateMetricWithQueryIr:
      type: object
      properties:
        folder:
          $ref: '#/components/schemas/Folder'
        event_name:
          $ref: '#/components/schemas/MetricEventName'
        query_ir:
          $ref: '#/components/schemas/QueryIr'
        winsorize_pct:
          $ref: '#/components/schemas/MetricWinsorizePct'
        default_min_effect_of_interest:
          $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
        direction:
          $ref: '#/components/schemas/MetricDirection'
      required:
        - query_ir
      additionalProperties: false
      description: Update-metric variant that replaces the query with a typed `query_ir`.
    UpdateMetricFields:
      type: object
      properties:
        folder:
          $ref: '#/components/schemas/Folder'
        event_name:
          $ref: '#/components/schemas/MetricEventName'
        winsorize_pct:
          $ref: '#/components/schemas/MetricWinsorizePct'
        default_min_effect_of_interest:
          $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
        direction:
          $ref: '#/components/schemas/MetricDirection'
      additionalProperties: false
      description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction).
    UpdateMetricRequest:
      oneOf:
        - $ref: '#/components/schemas/UpdateMetricWithQuery'
        - $ref: '#/components/schemas/UpdateMetricWithQueryIr'
        - $ref: '#/components/schemas/UpdateMetricFields'
      description: Body for `PATCH /api/admin/metrics/{id}`. Every field is optional (`name` is immutable); provide at most one of `query` / `query_ir` — modelled as a `oneOf` of three disjoint strict variants (query-only, query_ir-only, or neither), so supplying both is rejected.
    ListEventsResponse:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            description: Stable opaque event id.
          name:
            type: string
            description: Event name — the handle metric queries reference.
          folder:
            anyOf:
              - description: 'Optional folder name used to group items in the dashboard. Part of the SDK lookup key: an item in folder `checkout` named `new-cart` is referenced as `checkout/new-cart` from the SDK.'
                anyOf:
                  - type: string
                    maxLength: 256
                    pattern: ^[a-zA-Z0-9_-]+$
                  - type: 'null'
              - type: 'null'
            description: Folder the event is filed under, or `null` if at the root.
          description:
            anyOf:
              - type: string
              - type: 'null'
            description: Human-readable description, or `null` if none set.
          properties:
            type: array
            items:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 64
                  description: Property key, e.g. `amount` or `plan`.
                type:
                  type: string
                  enum:
                    - string
                    - number
                    - boolean
                  description: Value type of the property as recorded on the event.
                required:
                  default: false
                  description: Whether the property must be present on every emitted event.
                  type: boolean
                description:
                  default: ''
                  description: Human-readable description of the property.
                  type: string
              required:
                - name
                - type
              additionalProperties: false
              description: One typed property declared on a catalogued event.
            description: Typed properties declared on the event.
          pending:
            type: integer
            minimum: -9007199254740991
            maximum: 9007199254740991
            description: '`1` if this is an auto-discovered name awaiting approval (metrics on it fail until approved), `0` if approved/usable.'
          createdAt:
            type: string
            description: ISO-8601 timestamp of creation.
        required:
          - id
          - name
          - description
          - properties
          - pending
          - createdAt
        additionalProperties: false
        description: A catalogued event.
      description: Every catalogued event in the project (including pending auto-discovered names).
    CreateEventRequest:
      type: object
      properties:
        name:
          type: string
          pattern: ^[a-zA-Z0-9_][a-zA-Z0-9_\-.]{0,127}$
          description: Event name. Starts with a letter, digit, or `_`; letters, digits, `_`, `-`, `.`; max 128 chars. Immutable after create — this is the handle metric queries reference.
        folder:
          $ref: '#/components/schemas/Folder'
        description:
          description: Optional human-readable description of the event.
          type: string
        properties:
          default: []
          description: Typed properties declared on the event. Defaults to an empty list.
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                minLength: 1
                maxLength: 64
                description: Property key, e.g. `amount` or `plan`.
              type:
                type: string
                enum:
                  - string
                  - number
                  - boolean
                description: Value type of the property as recorded on the event.
              required:
                default: false
                description: Whether the property must be present on every emitted event.
                type: boolean
              description:
                default: ''
                description: Human-readable description of the property.
                type: string
            required:
              - name
              - type
            additionalProperties: false
            description: One typed property declared on a catalogued event.
      required:
        - name
      additionalProperties: false
      description: Body for `POST /api/admin/events`. Only `name` is required.
    CreateEventResponse:
      type: object
      properties:
        id:
          type: string
          description: Newly assigned event id.
        name:
          type: string
          description: The event name that was registered.
      required:
        - id
        - name
      additionalProperties: false
      description: Result of creating (or approving an existing pending) event.
    GetEventResponse:
      type: object
      properties:
        id:
          type: string
          description: Stable opaque event id.
        name:
          type: string
          description: Event name — the handle metric queries reference.
        folder:
          anyOf:
            - description: 'Optional folder name used to group items in the dashboard. Part of the SDK lookup key: an item in folder `checkout` named `new-cart` is referenced as `checkout/new-cart` from the SDK.'
              anyOf:
                - type: string
                  maxLength: 256
                  pattern: ^[a-zA-Z0-9_-]+$
                - type: 'null'
            - type: 'null'
          description: Folder the event is filed under, or `null` if at the root.
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: Human-readable description, or `null` if none set.
        properties:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                minLength: 1
                maxLength: 64
                description: Property key, e.g. `amount` or `plan`.
              type:
                type: string
                enum:
                  - string
                  - number
                  - boolean
                description: Value type of the property as recorded on the event.
              required:
                default: false
                description: Whether the property must be present on every emitted event.
                type: boolean
              description:
                default: ''
                description: Human-readable description of the property.
                type: string
            required:
              - name
              - type
            additionalProperties: false
            description: One typed property declared on a catalogued event.
          description: Typed properties declared on the event.
        pending:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: '`1` if this is an auto-discovered name awaiting approval (metrics on it fail until approved), `0` if approved/usable.'
        createdAt:
          type: string
          description: ISO-8601 timestamp of creation.
      required:
        - id
        - name
        - description
        - properties
        - pending
        - createdAt
      additionalProperties: false
      description: A catalogued event.
    DeleteEventResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
      required:
        - ok
      additionalProperties: false
      description: Confirmation that the event was archived.
    UpdateEventRequest:
      type: object
      properties:
        folder:
          $ref: '#/components/schemas/Folder'
        description:
          description: New description for the event.
          type: string
        properties:
          description: Replaces the full property set (no merge). Omit to leave properties unchanged.
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                minLength: 1
                maxLength: 64
                description: Property key, e.g. `amount` or `plan`.
              type:
                type: string
                enum:
                  - string
                  - number
                  - boolean
                description: Value type of the property as recorded on the event.
              required:
                default: false
                description: Whether the property must be present on every emitted event.
                type: boolean
              description:
                default: ''
                description: Human-readable description of the property.
                type: string
            required:
              - name
              - type
            additionalProperties: false
            description: One typed property declared on a catalogued event.
      additionalProperties: false
      description: Body for `PATCH /api/admin/events/{id}` and `POST /api/admin/events/{id}/approve`. All fields optional; `name` is immutable after create.
    UpdateEventResponse:
      type: object
      properties:
        id:
          type: string
          description: Event id that was updated.
      required:
        - id
      additionalProperties: false
      description: Result of updating or approving an event.
    ApproveEventRequest:
      type: object
      properties:
        folder:
          $ref: '#/components/schemas/Folder'
        description:
          description: New description for the event.
          type: string
        properties:
          description: Replaces the full property set (no merge). Omit to leave properties unchanged.
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                minLength: 1
                maxLength: 64
                description: Property key, e.g. `amount` or `plan`.
              type:
                type: string
                enum:
                  - string
                  - number
                  - boolean
                description: Value type of the property as recorded on the event.
              required:
                default: false
                description: Whether the property must be present on every emitted event.
                type: boolean
              description:
                default: ''
                description: Human-readable description of the property.
                type: string
            required:
              - name
              - type
            additionalProperties: false
            description: One typed property declared on a catalogued event.
      additionalProperties: false
      description: Body for `PATCH /api/admin/events/{id}` and `POST /api/admin/events/{id}/approve`. All fields optional; `name` is immutable after create.
    ApproveEventResponse:
      type: object
      properties:
        id:
          type: string
          description: Event id that was updated.
      required:
        - id
      additionalProperties: false
      description: Result of updating or approving an event.
    OpsItemStatus:
      type: string
      enum:
        - open
        - pending_approval
        - triage
        - triaged
        - in_progress
        - ready_for_qa
        - resolved
        - wont_fix
      description: 'Lifecycle status of a queue item. The working flow is `open` → `triaged` → `in_progress` → `ready_for_qa` → `resolved` (or `wont_fix`, terminal from any earlier stage). `ready_for_qa` is what a developer sets once a fix lands; `resolved` is the QA sign-off, normally flipped in the dashboard after verification — set it directly from code only when the fix has been verified end-to-end. Two human-gated holding states park an item OUT of the work queue until a human promotes it to `open` in the dashboard, so `GET /api/admin/ops` excludes them under `status=all`/default and returns them only when requested as an exact `status`: `pending_approval` is the pre-open approval gate for untriaged inbound (e.g. connector requests filed from a customer''s connectors panel) so it never gets auto-implemented — approving = flipping the status to `open`; `triage` is the onboarding-help bucket — questions/errors submitted to the "Stuck in onboarding?" assistant are funnelled into the platform project as `triage` rows so the team can see where people get stuck and follow up, keeping onboarding chatter out of the work queue until a human moves real items to `open`.'
    OpsItemPriority:
      type: string
      enum:
        - nice_to_have
        - medium
        - high
        - critical
      description: Triage priority of a queue item. The lowest tier is `nice_to_have` (not `low`) — carried over from the feature-request "importance" scale this priority set replaced.
    ListOpsItemsResponse:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            description: Stable opaque item id.
          number:
            anyOf:
              - type: number
              - type: 'null'
            description: Per-project item number (the `#7` handle), or `null` if unnumbered.
          type:
            type: string
            enum:
              - bug
              - feature_request
              - error
              - alert
              - measure_plan
            description: Queue item type. `bug` and `feature_request` are user-fileable; `error`, `alert`, and `measure_plan` tickets are auto-filed by the platform (a tracked production error, a metric-threshold alert, and an assistant-proposed measurement plan respectively).
          title:
            type: string
            description: One-line item title.
          status:
            $ref: '#/components/schemas/OpsItemStatus'
          priority:
            anyOf:
              - $ref: '#/components/schemas/OpsItemPriority'
              - type: 'null'
            description: Triage priority, or `null` if not yet set.
          sourceRef:
            description: Source reference for auto-filed tickets (e.g. an error fingerprint).
            anyOf:
              - type: string
              - type: 'null'
          createdAt:
            type: string
            description: ISO-8601 creation timestamp.
        required:
          - id
          - number
          - type
          - title
          - status
          - priority
          - createdAt
        additionalProperties: {}
        description: One queue item — any type.
      description: A page of queue items, newest first.
    NotificationTarget:
      anyOf:
        - type: object
          properties:
            slackChannel:
              anyOf:
                - type: object
                  properties:
                    id:
                      type: string
                      minLength: 1
                    name:
                      type: string
                      minLength: 1
                  required:
                    - id
                    - name
                  additionalProperties: false
                - type: 'null'
            email:
              anyOf:
                - type: string
                  format: email
                - type: 'null'
          additionalProperties: false
        - type: 'null'
      description: Delivery target for a notification; `null` = use the project default.
    CreateBugRequest:
      type: object
      properties:
        type:
          type: string
          enum:
            - bug
          description: Discriminator — files a bug.
        title:
          type: string
          minLength: 1
          maxLength: 200
          pattern: ^\S(.*\S)?$
          description: One-line bug title (no leading/trailing whitespace).
        stepsToReproduce:
          type: string
          maxLength: 8000
          default: ''
          description: How to reproduce the bug.
        actualResult:
          type: string
          maxLength: 8000
          default: ''
          description: What actually happened.
        expectedResult:
          type: string
          maxLength: 8000
          default: ''
          description: What was expected instead.
        priority:
          anyOf:
            - $ref: '#/components/schemas/OpsItemPriority'
            - type: 'null'
          description: Initial triage priority, or `null`.
        reporterEmail:
          anyOf:
            - type: string
              format: email
            - type: 'null'
          description: Email of the reporter, or `null`.
        pageUrl:
          anyOf:
            - type: string
              format: uri
            - type: 'null'
          description: URL of the page the bug relates to, or `null`.
        userAgent:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          description: Reporter's user-agent string, or `null`.
        viewport:
          anyOf:
            - type: string
              maxLength: 40
            - type: 'null'
          description: Reporter's viewport (e.g. `1280x720`), or `null`.
        context:
          anyOf:
            - type: object
              additionalProperties: {}
            - type: 'null'
          description: Arbitrary capture context, or `null`.
        notify:
          anyOf:
            - $ref: '#/components/schemas/NotificationTarget'
            - type: 'null'
          description: Where this bug's completion notification lands.
      required:
        - type
        - title
      additionalProperties: false
      description: 'Bug-kind fields for `POST /api/admin/ops` (sent with `type: bug`).'
    CreateFeatureRequestRequest:
      type: object
      properties:
        type:
          type: string
          enum:
            - feature_request
          description: Discriminator — files a feature request.
        title:
          type: string
          minLength: 1
          maxLength: 200
          pattern: ^\S(.*\S)?$
          description: One-line feature-request title (no leading/trailing whitespace).
        description:
          type: string
          maxLength: 8000
          default: ''
          description: What the feature is.
        useCase:
          type: string
          maxLength: 8000
          default: ''
          description: Why it's needed / the use case.
        priority:
          anyOf:
            - $ref: '#/components/schemas/OpsItemPriority'
            - type: 'null'
          description: Initial triage priority, or `null`.
        reporterEmail:
          anyOf:
            - type: string
              format: email
            - type: 'null'
          description: Email of the reporter, or `null`.
        pageUrl:
          anyOf:
            - type: string
              format: uri
            - type: 'null'
          description: URL of the page the request relates to, or `null`.
        userAgent:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          description: Reporter's user-agent string, or `null`.
        context:
          anyOf:
            - type: object
              additionalProperties: {}
            - type: 'null'
          description: Arbitrary capture context, or `null`.
        notify:
          anyOf:
            - $ref: '#/components/schemas/NotificationTarget'
            - type: 'null'
          description: Where this request's completion notification lands.
      required:
        - type
        - title
      additionalProperties: false
      description: 'Feature-request-kind fields for `POST /api/admin/ops` (sent with `type: feature_request`).'
    CreateOpsItemRequest:
      oneOf:
        - $ref: '#/components/schemas/CreateBugRequest'
        - $ref: '#/components/schemas/CreateFeatureRequestRequest'
      discriminator:
        propertyName: type
        mapping:
          bug: '#/components/schemas/CreateBugRequest'
          feature_request: '#/components/schemas/CreateFeatureRequestRequest'
      description: 'Body for `POST /api/admin/ops`. A discriminated union on `type`: `bug` carries the bug fields, `feature_request` the feature fields. Only these two user-fileable types are accepted — `error`, `alert`, and `measure_plan` tickets are auto-filed by the platform and cannot be created over the API.'
    CreateOpsItemResponse:
      type: object
      properties:
        id:
          type: string
          description: Newly created item id.
        number:
          description: Per-project item number assigned to the new item.
          anyOf:
            - type: number
            - type: 'null'
      required:
        - id
      additionalProperties: false
      description: Response for `POST /api/admin/ops`.
    OpsBrowserContext:
      type: object
      properties:
        pageUrl:
          anyOf:
            - type: string
            - type: 'null'
          description: URL of the page the report was filed from, or `null`.
        userAgent:
          anyOf:
            - type: string
            - type: 'null'
          description: Reporter's user-agent string, or `null`.
        viewport:
          anyOf:
            - type: string
            - type: 'null'
          description: Reporter's viewport (e.g. `1280x720`), or `null`.
      additionalProperties: {}
      description: Auto-collected browser environment for a `bug`/`feature_request`, captured at file time.
    OpsErrorContext:
      type: object
      properties:
        id:
          type: string
          description: The tracked `errors` row id (fetch full detail via `related.error`).
        fingerprint:
          type: string
          description: Stable dedupe key of the tracked error.
        causedByFingerprint:
          anyOf:
            - type: string
            - type: 'null'
          description: Fingerprint of the upstream issue this error descends from (set when the same error was reported at an inner boundary first), or `null` for a root issue.
        errorType:
          anyOf:
            - type: string
            - type: 'null'
          description: Error class/name, e.g. `TypeError`, or `null` when the source didn't supply one.
        message:
          type: string
          description: The error message.
        subject:
          anyOf:
            - type: string
            - type: 'null'
          description: The `see()` consequence subject — the `causes_the(<subject>)` value. Grep the codebase for this to find the throw site. `null` if the error was never instrumented.
        outcome:
          anyOf:
            - type: string
            - type: 'null'
          description: The `see()` consequence outcome — the `.to(<outcome>)` value. `null` if uninstrumented.
        kind:
          anyOf:
            - type: string
            - type: 'null'
          description: '`see()` error kind: `caught` | `uncaught` | `unhandled_rejection` | `network` | `violation`.'
        side:
          anyOf:
            - type: string
            - type: 'null'
          description: 'Which SDK side reported it: `client` | `server`.'
        env:
          anyOf:
            - type: string
            - type: 'null'
          description: Published env the reporting SDK ran against (dev/staging/prod).
        count:
          type: number
          description: Folded occurrence count for this fingerprint.
        firstSeenAt:
          type: string
          description: ISO-8601 timestamp of the first occurrence.
        lastSeenAt:
          type: string
          description: ISO-8601 timestamp of the most recent occurrence.
        seenUrls:
          type: array
          items:
            type: string
          description: Distinct, id-normalized routes this error has surfaced on (UUIDs/ids collapsed to `#`).
        stackTail:
          anyOf:
            - type: string
            - type: 'null'
          description: The last 3 non-empty lines of the latest occurrence's stack — the innermost frames closest to where the throw bubbled out, baked in as an at-a-glance locator. `null` when the source supplied no stack. Fetch the full stack via `related.error`.
        sdkVersion:
          anyOf:
            - type: string
            - type: 'null'
          description: '@shipeasy/sdk version of the latest occurrence, or `null`.'
      required:
        - id
        - fingerprint
        - message
        - count
        - firstSeenAt
        - lastSeenAt
        - seenUrls
      additionalProperties: {}
      description: Hydrated detail for an auto-filed `error` ticket, read from the tracked `errors` row at request time (so `count`/`lastSeenAt` reflect the latest state).
    OpsAlertRuleSummary:
      type: object
      properties:
        id:
          type: string
          description: Alert-rule id.
        name:
          type: string
          description: Alert-rule name.
        comparator:
          type: string
          enum:
            - gt
            - gte
            - lt
            - lte
          description: How `observedValue` is compared to `threshold`.
        threshold:
          type: number
          description: The threshold value the rule fires on.
        windowHours:
          type: number
          description: Rolling evaluation window in hours.
      required:
        - id
        - name
        - comparator
        - threshold
        - windowHours
      additionalProperties: {}
      description: The condition of a metric-rule alert.
    OpsAlertMetricSummary:
      type: object
      properties:
        id:
          type: string
          description: Metric id (fetch full detail via `related.metric`).
        name:
          type: string
          description: Metric name.
        events:
          type: array
          items:
            type: string
          description: The event name(s) the metric aggregates over — one for count metrics, numerator + denominator for ratio metrics. Grep the codebase for `track('<event>')` on each to find the instrumentation feeding the metric.
      required:
        - id
        - name
        - events
      additionalProperties: {}
      description: The metric an alert watches, with its backing events.
    OpsAlertContext:
      type: object
      properties:
        source:
          type: string
          enum:
            - metric_rule
            - experiment_srm
            - experiment_peek
            - guardrail
          description: What kind of alert transitioned to active.
        dedupeKey:
          type: string
          description: Stable per-condition key; with `source` forms the ticket's `sourceRef`.
        severity:
          type: string
          enum:
            - danger
            - warn
            - info
          description: Alert severity.
        observedValue:
          anyOf:
            - type: number
            - type: 'null'
          description: The metric value that tripped the rule, or `null`.
        href:
          anyOf:
            - type: string
            - type: 'null'
          description: Dashboard deep link to the alert, or `null`.
        status:
          anyOf:
            - type: string
              enum:
                - active
                - resolved
                - dismissed
            - type: 'null'
          description: Current status of the underlying alert (`active` while the condition holds), or `null` if the alert row is gone.
        activeSince:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-8601 timestamp the alert became active, or `null`.
        resolvedAt:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-8601 timestamp the alert cleared, or `null` while still active.
        rule:
          anyOf:
            - $ref: '#/components/schemas/OpsAlertRuleSummary'
            - type: 'null'
          description: The alert rule condition that tripped (metric-rule alerts only); `null` for SRM/peek/guardrail alerts with no rule.
        metric:
          anyOf:
            - $ref: '#/components/schemas/OpsAlertMetricSummary'
            - type: 'null'
          description: The metric the alert watches, hydrated with its backing event(s); `null` if not resolvable.
      required:
        - source
        - dedupeKey
        - severity
      additionalProperties: {}
      description: Hydrated detail for an auto-filed `alert` ticket, resolving the rule → metric → event chain at request time.
    MeasurePlanResource:
      type: object
      properties:
        kind:
          type: string
          enum:
            - metric
            - experiment
            - alert_rule
            - event
          description: Resource kind.
        id:
          anyOf:
            - type: string
            - type: 'null'
          description: Resource id when it was created; absent/`null` for resources still to be made.
        name:
          type: string
          description: Resource name.
      required:
        - kind
        - name
      additionalProperties: {}
      description: A resource referenced by a measurement plan.
    MeasurePlanStep:
      type: object
      properties:
        event:
          anyOf:
            - type: string
            - type: 'null'
          description: The event name the instrumentation should emit, when known.
        attribute:
          anyOf:
            - type: string
            - type: 'null'
          description: A new user attribute the project must start sending on its identify/evaluate context (when a gate's targeting needs a field that doesn't exist yet).
        label:
          type: string
          description: Short human-readable name for the moment being instrumented.
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: What to track and why, described conceptually — which user moment/action to capture and what it enables. Deliberately NOT a file path (the assistant has no repo access and can't name real files); you locate the call site yourself.
        properties:
          type: array
          items:
            type: string
          description: Event properties the downstream metric needs attached (e.g. `method`, `plan`).
      required:
        - label
      additionalProperties: {}
      description: One piece of code instrumentation a measurement plan still needs.
    OpsMeasurePlanContext:
      type: object
      properties:
        goal:
          anyOf:
            - type: string
            - type: 'null'
          description: The customer's underlying intent in their own words — WHAT they want to learn or achieve and WHY, independent of the specific steps. The plan below is a best-effort proposal made without repo access; when the code reveals a better path, this goal is the target you optimize for, not literal step-adherence.
        created:
          type: array
          items:
            $ref: '#/components/schemas/MeasurePlanResource'
          description: Resources the assistant already created on approval (live now) — don't recreate them.
        pending:
          type: array
          items:
            $ref: '#/components/schemas/MeasurePlanResource'
          description: Resources the assistant couldn't create yet (usually a metric whose backing event isn't emitted); create these after the instrumentation lands.
        instrumentation:
          type: array
          items:
            $ref: '#/components/schemas/MeasurePlanStep'
          description: The code instrumentation to implement before the metrics can collect data.
      required:
        - created
        - instrumentation
      additionalProperties: {}
      description: 'An assistant-proposed measurement plan: what it already built, what it still needs, and the event instrumentation you implement.'
    OpsItemContext:
      type: object
      properties:
        browser:
          $ref: '#/components/schemas/OpsBrowserContext'
        error:
          $ref: '#/components/schemas/OpsErrorContext'
        alert:
          $ref: '#/components/schemas/OpsAlertContext'
        measurePlan:
          $ref: '#/components/schemas/OpsMeasurePlanContext'
      additionalProperties: {}
      description: Per-type capture context on a queue item. Exactly one of `browser` (bug/feature), `error`, `alert`, or `measurePlan` is populated depending on `type`; other keys (e.g. the AI dedupe block on bugs) may also be present.
    OpsItemAttachment:
      type: object
      properties:
        id:
          type: string
          description: Attachment id.
        kind:
          type: string
          description: '`screenshot` | `video` | `log`.'
        filename:
          type: string
          description: Sanitized original filename.
        mimeType:
          type: string
          description: MIME type, e.g. `image/png`.
        sizeBytes:
          type: number
          description: Upload size in bytes.
        fetchUrl:
          type: string
          description: Admin-API path to download the file (`GET` with the admin/ops key — screenshots render inline; recordings can't be watched).
      required:
        - id
        - kind
        - filename
        - mimeType
        - sizeBytes
        - fetchUrl
      additionalProperties: {}
      description: A file uploaded with a bug/feature report.
    OpsItemRelated:
      type: object
      properties:
        dashboard:
          type: string
          description: Dashboard-relative deep link to this item.
        error:
          type: string
          description: Admin-API path to the tracked error (error tickets only).
        alertRule:
          type: string
          description: Admin-API path to the alert rule (metric-rule alerts only).
        metric:
          type: string
          description: Admin-API path to the metric the alert watches (alert tickets only).
        githubIssue:
          type: string
          description: HTML URL of the connected GitHub issue, if any.
        githubPr:
          type: string
          description: HTML URL of the linked GitHub pull request, if any.
      additionalProperties: {}
      description: Deep links to the resources behind this item — every value is either a dashboard-relative path or an admin-API path fetchable with the same key.
    GithubConnectorData:
      type: object
      properties:
        issue:
          type: object
          properties:
            number:
              type: number
              description: GitHub issue number.
            url:
              type: string
              description: HTML URL of the opened issue.
            owner:
              type: string
              description: Repository owner (org or user).
            repo:
              type: string
              description: Repository name.
            createdAt:
              type: string
              description: ISO-8601 timestamp the issue was opened.
          required:
            - number
            - url
            - owner
            - repo
          additionalProperties: {}
          description: The GitHub issue this item opened.
        pr:
          type: object
          properties:
            number:
              type: number
              description: Pull request number.
            url:
              type: string
              description: HTML URL of the linked pull request.
            linkedAt:
              type: string
              description: ISO-8601 timestamp the PR was linked.
            connectedToIssue:
              type: boolean
              description: Whether the PR was wired to the issue on GitHub (via a closing keyword or a comment).
            method:
              type: string
              enum:
                - closes
                - comment
              description: How the PR was connected to the issue.
          required:
            - number
            - url
          additionalProperties: {}
          description: The pull request linked to this item via `link-pr`.
      additionalProperties: {}
      description: GitHub connector trace — the issue it opened and, once linked, the pull request.
    SlackConnectorData:
      type: object
      properties:
        message:
          type: object
          properties:
            channel:
              type: string
              description: Slack channel id the message was posted to.
            ts:
              type: string
              description: Slack message timestamp (`ts`) — the message handle used for in-place `chat.update`.
            postedAt:
              type: string
              description: ISO-8601 timestamp the message was posted.
          required:
            - channel
            - ts
          additionalProperties: {}
          description: The Slack message the driver posted for this item.
      additionalProperties: {}
      description: Slack connector trace — the message the driver posted for this item. The linked pull request is recorded on `github.pr`, not here.
    ConnectorData:
      type: object
      properties:
        github:
          $ref: '#/components/schemas/GithubConnectorData'
        slack:
          $ref: '#/components/schemas/SlackConnectorData'
      additionalProperties: {}
      description: Connector linkage for one queue item, keyed by provider. Each provider's driver deep-merges its own trace into this blob, so any subset of providers may be present. Unknown/future providers may appear as additional keys.
    GetOpsItemResponse:
      type: object
      properties:
        id:
          type: string
          description: Stable opaque item id.
        number:
          anyOf:
            - type: number
            - type: 'null'
          description: Per-project item number (the `#7` handle), or `null` if unnumbered.
        type:
          type: string
          enum:
            - bug
            - feature_request
            - error
            - alert
            - measure_plan
          description: Queue item type. `bug` and `feature_request` are user-fileable; `error`, `alert`, and `measure_plan` tickets are auto-filed by the platform (a tracked production error, a metric-threshold alert, and an assistant-proposed measurement plan respectively).
        title:
          type: string
          description: One-line item title (all types).
        status:
          $ref: '#/components/schemas/OpsItemStatus'
        priority:
          anyOf:
            - $ref: '#/components/schemas/OpsItemPriority'
            - type: 'null'
          description: Triage priority, or `null` if not yet set (all types).
        source:
          type: string
          enum:
            - team
            - system
          description: 'How the item was filed: `team` (a human admin/teammate — bug/feature) or `system` (auto-filed — error/alert/measure_plan).'
        sourceRef:
          anyOf:
            - type: string
            - type: 'null'
          description: Stable key of the originating record for auto-filed tickets (error fingerprint, `<alert source>:<dedupeKey>`, or measurement-plan ref); `null` for human-filed bugs/features.
        reporterEmail:
          anyOf:
            - type: string
            - type: 'null'
          description: Reporter email (bug/feature), or `null`.
        stepsToReproduce:
          type: string
          description: Reproduction steps — populated for `bug`, empty string otherwise.
        actualResult:
          type: string
          description: What actually happened — `bug` only, empty string otherwise.
        expectedResult:
          type: string
          description: What was expected — `bug` only, empty string otherwise.
        description:
          type: string
          description: Feature description — populated for `feature_request`, empty string otherwise.
        useCase:
          type: string
          description: Feature use case — `feature_request` only, empty string otherwise.
        context:
          anyOf:
            - $ref: '#/components/schemas/OpsItemContext'
            - type: 'null'
          description: Type-specific capture context. For `bug`/`feature_request` it carries `browser` (the auto-collected page URL / user-agent / viewport). For auto-filed tickets it carries the hydrated `error`, `alert`, or `measurePlan` block. `null` only for legacy rows with nothing captured.
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/OpsItemAttachment'
          description: Files attached to the report — screenshots, recordings, logs. Populated for `bug`/`feature_request`; always an empty array for auto-filed `error`/`alert`/`measure_plan` tickets. Fetch each via its `fetchUrl` with the same admin/ops key (the download route is ops-key allow-listed).
        related:
          $ref: '#/components/schemas/OpsItemRelated'
        connectorData:
          anyOf:
            - $ref: '#/components/schemas/ConnectorData'
            - type: 'null'
          description: Per-connector linkage recorded for this item, keyed by connector provider. Populated as connectors act on the item (e.g. GitHub opens an issue, Slack posts a message); more than one provider can be present at once. `null` if no connector has touched the item.
        notify:
          anyOf:
            - $ref: '#/components/schemas/NotificationTarget'
            - type: 'null'
          description: Per-item completion-notification target, or `null` (falls back to the project default).
        createdAt:
          type: string
          description: ISO-8601 creation timestamp.
        updatedAt:
          type: string
          description: ISO-8601 last-update timestamp.
      required:
        - id
        - number
        - type
        - title
        - status
        - priority
        - context
        - attachments
        - related
        - createdAt
      additionalProperties: {}
      description: One queue item, any of the five types. Shared fields apply to all; `stepsToReproduce`/`actualResult`/`expectedResult` are bug-specific, `description`/`useCase` feature-specific. The auto-collected browser fields (page URL, user-agent, viewport) live under `context.browser` for bug/feature. `context` also carries the hydrated per-type payload for auto-filed `error`/`alert`/`measure_plan` tickets, `attachments` lists any uploaded files, and `related` gives deep links to the underlying resources.
    OpsItemPriorityOrNull:
      anyOf:
        - $ref: '#/components/schemas/OpsItemPriority'
        - type: 'null'
      description: Triage priority, or `null` when not set (in an update, `null` clears it).
    OpsItemNotifyOrNull:
      anyOf:
        - $ref: '#/components/schemas/NotificationTarget'
        - type: 'null'
      description: Where this item's completion notification lands, or `null`.
    UpdateBugRequest:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
          pattern: ^\S(.*\S)?$
          description: New bug title (no leading/trailing whitespace).
        stepsToReproduce:
          type: string
          maxLength: 8000
          description: Updated reproduction steps.
        actualResult:
          type: string
          maxLength: 8000
          description: Updated actual result.
        expectedResult:
          type: string
          maxLength: 8000
          description: Updated expected result.
        status:
          $ref: '#/components/schemas/OpsItemStatus'
        priority:
          $ref: '#/components/schemas/OpsItemPriorityOrNull'
        githubPrNumber:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          description: Link (or, when `null`, unlink) a GitHub pull request to this bug.
        notify:
          $ref: '#/components/schemas/OpsItemNotifyOrNull'
      additionalProperties: false
      description: Content + triage update for a `bug` item (`PATCH /api/admin/ops/{handle}` when the item is a bug).
    UpdateFeatureRequestRequest:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
          pattern: ^\S(.*\S)?$
          description: New feature-request title (no leading/trailing whitespace).
        description:
          type: string
          maxLength: 8000
          description: Updated description.
        useCase:
          type: string
          maxLength: 8000
          description: Updated use case.
        status:
          $ref: '#/components/schemas/OpsItemStatus'
        priority:
          $ref: '#/components/schemas/OpsItemPriorityOrNull'
        githubPrNumber:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          description: Link (or, when `null`, unlink) a GitHub pull request to this request.
        notify:
          $ref: '#/components/schemas/OpsItemNotifyOrNull'
      additionalProperties: false
      description: Content + triage update for a `feature_request` item (`PATCH /api/admin/ops/{handle}` when the item is a feature request).
    UpdateOpsItemStatusRequest:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/OpsItemStatus'
        priority:
          $ref: '#/components/schemas/OpsItemPriorityOrNull'
        notify:
          $ref: '#/components/schemas/OpsItemNotifyOrNull'
      additionalProperties: false
      description: Triage-only update — the shape accepted for any item, and the ONLY shape for auto-filed `error`/`alert`/`measure_plan` tickets (their content is not user-editable).
    UpdateOpsItemRequest:
      anyOf:
        - $ref: '#/components/schemas/UpdateBugRequest'
        - $ref: '#/components/schemas/UpdateFeatureRequestRequest'
        - $ref: '#/components/schemas/UpdateOpsItemStatusRequest'
      description: 'Body for `PATCH /api/admin/ops/{handle}`. The body is type-less — the server validates it against the stored item''s type: a `bug` accepts the bug content fields, a `feature_request` the feature fields, and `error`/`alert`/`measure_plan` only `status`/`priority`/`notify`. Pass at least one field.'
    UpdateOpsItemResponse:
      type: object
      properties:
        id:
          type: string
          description: Item id that was updated.
      required:
        - id
      additionalProperties: false
      description: Response for the update / link-pr endpoints.
    LinkPrToOpsItemRequest:
      type: object
      properties:
        prNumber:
          anyOf:
            - type: integer
              exclusiveMinimum: 0
              maximum: 9007199254740991
            - type: 'null'
          description: PR number to record on the item. `null` unlinks the PR.
        prUrl:
          description: Explicit PR URL. Required for error/alert tickets (no GitHub issue to derive the URL from).
          type: string
          format: uri
      required:
        - prNumber
      additionalProperties: false
      description: Body for `POST /api/admin/ops/{handle}/link-pr`.
    LinkPrToOpsItemResponse:
      type: object
      properties:
        id:
          type: string
          description: Item id that was updated.
      required:
        - id
      additionalProperties: false
      description: Response for the update / link-pr endpoints.
    OpsCommentAuthorType:
      type: string
      enum:
        - user
        - system
      description: Who wrote a comment. `user` is a teammate (their email is in `authorEmail`); `system` is Jarvis — the AI agent — which authors comments when an ops-notify escalation lands on the item and when it is `@shipeasy`-mentioned in a thread.
    OpsComment:
      type: object
      properties:
        id:
          type: string
          description: Comment id.
        feedbackId:
          type: string
          description: The queue item this comment hangs off.
        parentId:
          anyOf:
            - type: string
            - type: 'null'
          description: The top-level comment this is a reply to, or `null` for a top-level comment.
        authorType:
          $ref: '#/components/schemas/OpsCommentAuthorType'
        authorEmail:
          anyOf:
            - type: string
            - type: 'null'
          description: The teammate who wrote it, or `null` for a `system` (Jarvis) comment.
        body:
          type: string
          description: Comment body as markdown (may contain sanitised inline image/video embeds).
        createdAt:
          type: string
          description: ISO-8601 creation timestamp.
        updatedAt:
          type: string
          description: ISO-8601 last-edit timestamp.
      required:
        - id
        - feedbackId
        - parentId
        - authorType
        - authorEmail
        - body
        - createdAt
        - updatedAt
      additionalProperties: false
      description: A single comment on a queue item.
    ListOpsCommentsResponse:
      type: object
      properties:
        comments:
          type: array
          items:
            $ref: '#/components/schemas/OpsComment'
      required:
        - comments
      additionalProperties: false
      description: Response for `GET /api/admin/ops/{handle}/comments` — the thread, oldest first.
    CreateOpsCommentRequest:
      type: object
      properties:
        body:
          type: string
          minLength: 1
          maxLength: 10000
          description: The comment body as markdown. Mentions (`@teammate`, `@shipeasy`) are parsed from it.
        parentId:
          anyOf:
            - type: string
            - type: 'null'
          description: Reply under this top-level comment. Omit / `null` for a top-level comment. Replying to a reply attaches to the same top-level parent (threading is one level deep).
      required:
        - body
      additionalProperties: false
      description: Body for `POST /api/admin/ops/{handle}/comments`.
    CreateOpsCommentResponse:
      type: object
      properties:
        id:
          type: string
          description: Newly created comment id.
      required:
        - id
      additionalProperties: false
      description: Response for `POST /api/admin/ops/{handle}/comments`.
    NotifyOpsRequest:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
          description: One-line headline of what's blocked.
        summary:
          type: string
          minLength: 1
          maxLength: 280
          description: 'One sentence: why it can''t be fixed in code. Renders markdown.'
        steps:
          description: Ordered steps the human should take to unblock — self-contained (the human reads only this card, not the agent's transcript), 3–6 steps, each naming the exact file, command, env var, or dashboard page. Renders markdown.
          type: array
          items:
            type: string
        href:
          description: Dashboard-relative deep link to the related item. `null` is accepted and treated as "no link".
          anyOf:
            - type: string
            - type: 'null'
        dedupeKey:
          description: Stable per-escalation key (e.g. `feedback:7`) so re-runs dedupe to one row.
          type: string
      required:
        - title
        - summary
      additionalProperties: false
      description: Body for `POST /api/admin/notifications`. In `title`, `summary`, and each step, reference admin entities inline with tokens — `#42` (feedback item), `@gate:<name>` (alias `@flag:`), `@experiment:<name>` (`@exp:`), `@config:<name>`, `@killswitch:<name>` (`@ks:`), `@metric:<name>`, `@universe:<name>`, `@alert:<name>` — where `<name>` is the entity's immutable name/slug (e.g. `features.checkout`). The dashboard renders each token as a live hover chip deep-linking to the entity; tokens degrade to plain text elsewhere, so they're always safe to use.
    NotifyOpsResponse:
      type: object
      properties:
        dedupeKey:
          type: string
          description: The dedupe key the escalation was recorded under.
        dispatched:
          type: boolean
          description: '`true` if a new escalation was dispatched; `false` on an idempotent repeat.'
      required:
        - dedupeKey
        - dispatched
      additionalProperties: false
      description: Response for `POST /api/admin/notifications`.
    ListSlackChannelsResponse:
      type: object
      properties:
        connected:
          type: boolean
          description: Whether a Slack connector is connected and authenticated.
        channels:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Slack channel id.
              name:
                type: string
                description: Slack channel name (without the leading `#`).
              isPrivate:
                description: Whether the channel is private.
                type: boolean
            required:
              - id
              - name
            additionalProperties: false
            description: One Slack channel the project can post to.
          description: The project's Slack channels (empty when no Slack is connected).
      required:
        - connected
        - channels
      additionalProperties: false
      description: Response for `GET /api/admin/slack/channels`.
    ListAlertRulesResponse:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            description: Stable opaque alert-rule id.
          name:
            type: string
            description: Human label for the rule.
          metricId:
            type: string
            description: Id of the metric the rule evaluates. Immutable after create.
          metricName:
            anyOf:
              - type: string
              - type: 'null'
            description: Display name of the bound metric, or `null` if the metric no longer exists.
          comparator:
            type: string
            enum:
              - gt
              - gte
              - lt
              - lte
            description: How the metric value is compared to the threshold (gt/gte/lt/lte).
          threshold:
            type: number
            description: Threshold the metric value is compared against.
          windowHours:
            type: integer
            minimum: -9007199254740991
            maximum: 9007199254740991
            description: Lookback window (hours) the metric is aggregated over.
          severity:
            type: string
            enum:
              - danger
              - warn
              - info
            description: Severity of the raised alert.
          enabled:
            type: boolean
            description: Whether the rule is evaluated by the cron.
          notify:
            $ref: '#/components/schemas/NotificationTarget'
          createdAt:
            type: string
            description: ISO-8601 timestamp of creation.
          updatedAt:
            type: string
            description: ISO-8601 timestamp of the last update.
        required:
          - id
          - name
          - metricId
          - metricName
          - comparator
          - threshold
          - windowHours
          - severity
          - enabled
          - notify
          - createdAt
          - updatedAt
        additionalProperties: false
        description: One metric-threshold alert rule.
    CreateAlertRuleRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
          description: Human label for the rule, shown on the alert and the rules list.
        metricId:
          type: string
          minLength: 1
          description: Id of the metric to evaluate.
        comparator:
          type: string
          enum:
            - gt
            - gte
            - lt
            - lte
          description: How the metric value is compared to the threshold (gt/gte/lt/lte).
        threshold:
          type: number
          description: Threshold the metric value is compared against.
        windowHours:
          default: 24
          description: Lookback window (hours) the metric is aggregated over. 1–720.
          type: integer
          minimum: 1
          maximum: 720
        severity:
          default: warn
          description: Severity of the raised alert.
          type: string
          enum:
            - danger
            - warn
            - info
        enabled:
          default: true
          description: Whether the rule is evaluated by the cron.
          type: boolean
        notify:
          $ref: '#/components/schemas/NotificationTarget'
      required:
        - name
        - metricId
        - comparator
        - threshold
      additionalProperties: false
    CreateAlertRuleResponse:
      type: object
      properties:
        id:
          type: string
          description: Newly assigned alert-rule id.
      required:
        - id
      additionalProperties: false
    DeleteAlertRuleResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
      required:
        - ok
      additionalProperties: false
    UpdateAlertRuleRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
        comparator:
          type: string
          enum:
            - gt
            - gte
            - lt
            - lte
        threshold:
          type: number
        windowHours:
          type: integer
          minimum: 1
          maximum: 720
        severity:
          type: string
          enum:
            - danger
            - warn
            - info
        enabled:
          type: boolean
        notify:
          $ref: '#/components/schemas/NotificationTarget'
      additionalProperties: false
    UpdateAlertRuleResponse:
      type: object
      properties:
        id:
          type: string
          description: Newly assigned alert-rule id.
      required:
        - id
      additionalProperties: false
    GetCurrentProjectResponse:
      type: object
      properties:
        id:
          type: string
          description: Stable opaque project id.
        name:
          type: string
          description: Project name.
        domain:
          anyOf:
            - type: string
            - type: 'null'
          description: Project domain, or `null` if unset.
        ownerEmail:
          type: string
          description: Email of the account that owns the project.
        plan:
          type: string
          enum:
            - free
            - pro
            - business
            - enterprise
          description: Billing plan tier.
        status:
          type: string
          enum:
            - active
            - inactive
          description: Project lifecycle status.
        subscriptionStatus:
          type: string
          description: Stripe subscription status (`none`, `active`, `trialing`, `past_due`, …).
        billingInterval:
          type: string
          enum:
            - monthly
            - annual
          description: Billing cadence.
        currentPeriodEnd:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-8601 end of the current billing period, or `null`.
        trialEndsAt:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-8601 trial end, or `null` if not trialing.
        cancelAtPeriodEnd:
          type: number
          description: '`1` if the subscription is set to cancel at period end, else `0`.'
        moduleTranslations:
          anyOf:
            - type: boolean
            - type: number
          description: Whether the i18n/translations module is enabled.
        moduleConfigs:
          anyOf:
            - type: boolean
            - type: number
          description: Whether the dynamic-configs module is enabled.
        moduleGates:
          anyOf:
            - type: boolean
            - type: number
          description: Whether the feature-gates module is enabled.
        moduleExperiments:
          anyOf:
            - type: boolean
            - type: number
          description: Whether the experiments module is enabled.
        moduleFeedback:
          anyOf:
            - type: boolean
            - type: number
          description: Whether the feedback/ops module is enabled.
        minSampleSize:
          type: integer
          description: Verdict power guard — minimum users per arm before a ship/hold verdict.
        minRuntimeDays:
          type: integer
          description: Minimum days an experiment must run before a verdict (peeking guard).
        defaultPower:
          type: number
          description: Target statistical power (1−β) feeding the realized-MDE calculation.
        ciConfidence:
          type: number
          description: Confidence level for the interval surfaced on results.
        defaultAllocationPct:
          type: integer
          description: Default traffic allocation (basis points) new experiments start with.
        defaultHoldout:
          type: integer
          description: Default holdout carve-out (basis points) that seeds each new universe's holdout.
        defaultWinsorizePct:
          type: integer
          description: Default winsorization percentile new metrics start with.
        defaultMei:
          anyOf:
            - type: number
            - type: 'null'
          description: Default minimum effect of interest (relative, 0–1) new metrics start with, or null.
        cupedBaselineDays:
          type: integer
          description: CUPED baseline window — days of pre-experiment history, frozen at start.
        cupedMinOverlap:
          type: number
          description: CUPED selection-bias guard — min share of users with a baseline, else skip.
        cupedMinBaselineUsers:
          type: integer
          description: CUPED — minimum users with a baseline before it runs at all.
        msprtTauMeiFactor:
          type: number
          description: mSPRT prior width — τ = minimum effect of interest × this factor.
        msprtTauSdFactor:
          type: number
          description: mSPRT fallback prior width — τ = this × control SD when no MEI is set.
        srmThreshold:
          type: number
          description: SRM chi-square p-value below which the run is called invalid.
        createdAt:
          type: string
          description: ISO-8601 timestamp of project creation.
        updatedAt:
          type: string
          description: ISO-8601 timestamp of last update.
      required:
        - id
        - name
        - domain
        - ownerEmail
        - plan
        - status
        - subscriptionStatus
        - billingInterval
        - currentPeriodEnd
        - trialEndsAt
        - cancelAtPeriodEnd
        - moduleTranslations
        - moduleConfigs
        - moduleGates
        - moduleExperiments
        - moduleFeedback
        - createdAt
        - updatedAt
      additionalProperties: {}
      description: The project the caller's auth header resolves to. The shape is open — additional project fields may be present.
    UpsertProjectRequest:
      type: object
      properties:
        domain:
          type: string
          minLength: 1
          maxLength: 2048
          pattern: ^(\*|(\*\.)?[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+)$
          description: Lowercase bare hostname (e.g. `acme.com`, `app.acme.com`, `*.acme.com`), or `*` to allow any origin. Full URLs with `https://` are not accepted. The project is keyed by `(owner_email, domain)`, so a second call with the same domain returns the existing project.
        name:
          description: Human-readable project name. Defaults to the domain on first create.
          type: string
          minLength: 1
          maxLength: 100
      required:
        - domain
      additionalProperties: false
      description: Body for `POST /api/admin/projects/upsert`. Only `domain` is required; the owner is resolved from the caller's session.
    UpsertProjectResponse:
      type: object
      properties:
        id:
          type: string
          description: Stable opaque project id.
        name:
          type: string
          description: Project name (the supplied `name`, or the domain on first create).
        domain:
          anyOf:
            - type: string
            - type: 'null'
          description: Project domain, or `null` if unset.
        owner_email:
          type: string
          description: Email of the account that owns the project.
        created:
          type: boolean
          description: '`true` if this call created the project, `false` if it returned an existing one.'
      required:
        - id
        - name
        - domain
        - owner_email
        - created
      additionalProperties: false
      description: Result of `POST /api/admin/projects/upsert`.
    domain:
      type: string
      minLength: 1
      maxLength: 2048
      pattern: ^(\*|(\*\.)?[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+)$
      description: Lowercase bare hostname (e.g. `acme.com`, `app.acme.com`, `*.acme.com`), or `*` to allow any origin. Full URLs with `https://` are not accepted. The project is keyed by `(owner_email, domain)`, so a second call with the same domain returns the existing project.
    UpdateProjectRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
          description: New project name.
        domain:
          $ref: '#/components/schemas/domain'
        slug:
          type: string
          minLength: 2
          maxLength: 48
          pattern: ^[a-z0-9](?:[a-z0-9-]{0,46}[a-z0-9])?$
          description: URL-safe identifier used in app URLs and SDK config. Lowercase letters, numbers, and hyphens; 2–48 chars; cannot start or end with a hyphen. The caller lowercases the raw slug before sending.
        defaultEnv:
          type: string
          enum:
            - dev
            - staging
            - prod
          description: Default environment new resources are scoped to.
        timezone:
          type: string
          minLength: 1
          maxLength: 64
          description: IANA timezone the project's daily analysis runs in.
        statMethod:
          type: string
          enum:
            - sequential
            - fixed
            - bayesian
          description: Statistical method the experiment analyzer uses.
        sigThreshold:
          type: string
          enum:
            - '0.01'
            - '0.05'
            - '0.10'
          description: Significance threshold (alpha) for experiment analysis.
        autoRollback:
          type: boolean
          description: Whether a failing guardrail auto-rolls back the experiment.
        minSampleDays:
          type: integer
          minimum: 1
          maximum: 365
          description: Minimum number of days an experiment must run before it can be called.
        moduleTranslations:
          type: boolean
          description: Enable/disable the i18n/translations module.
        moduleConfigs:
          type: boolean
          description: Enable/disable the dynamic-configs module.
        moduleGates:
          type: boolean
          description: Enable/disable the feature-gates module.
        moduleExperiments:
          type: boolean
          description: Enable/disable the experiments module.
        moduleFeedback:
          type: boolean
          description: Enable/disable the feedback/ops module.
        moduleUser:
          type: boolean
          description: Enable/disable the user-management module.
        moduleEvents:
          type: boolean
          description: Enable/disable the events module.
        minSampleSize:
          type: integer
          minimum: 2
          maximum: 1000000
          description: Verdict power guard — minimum users per arm before a ship/hold verdict.
        minRuntimeDays:
          type: integer
          minimum: 0
          maximum: 365
          description: Minimum days an experiment must run before a verdict (peeking guard).
        defaultPower:
          type: number
          minimum: 0.5
          maximum: 0.99
          description: Target statistical power (1−β) feeding the realized-MDE calculation.
        ciConfidence:
          type: number
          minimum: 0.5
          maximum: 0.999
          description: Confidence level for the interval surfaced on results (any value in [0.5, 0.999], e.g. 0.90, 0.95, 0.975, 0.99).
        defaultAllocationPct:
          type: integer
          minimum: 1
          maximum: 10000
          description: Default traffic allocation (basis points, 1000 = 10%) new experiments start with; overridable per experiment.
        defaultHoldout:
          type: integer
          minimum: 0
          maximum: 10000
          description: Default holdout carve-out (basis points) that seeds each new universe's holdout (0 = none).
        defaultWinsorizePct:
          type: integer
          minimum: 1
          maximum: 99
          description: Default winsorization percentile new metrics start with; overridable per metric.
        defaultMei:
          anyOf:
            - type: number
              minimum: 0
              maximum: 1
            - type: 'null'
          description: Default minimum effect of interest (relative, 0–1) new metrics start with; overridable per metric and per experiment. Null clears it.
        cupedBaselineDays:
          type: integer
          minimum: 1
          maximum: 365
          description: CUPED baseline window — days of pre-experiment history, frozen at start.
        cupedMinOverlap:
          type: number
          minimum: 0.01
          maximum: 0.99
          description: CUPED selection-bias guard — min share of users with a baseline, else skip.
        cupedMinBaselineUsers:
          type: integer
          minimum: 10
          maximum: 100000
          description: CUPED — minimum users with a baseline before it runs at all.
        msprtTauMeiFactor:
          type: number
          minimum: 0.1
          maximum: 2
          description: mSPRT prior width — τ = minimum effect of interest × this factor.
        msprtTauSdFactor:
          type: number
          minimum: 0.05
          maximum: 1
          description: mSPRT fallback prior width — τ = this × control SD when no MEI is set.
        srmThreshold:
          type: number
          minimum: 0.0001
          maximum: 0.05
          description: SRM chi-square p-value below which the run is called invalid.
      additionalProperties: false
      description: Body for `PATCH /api/admin/projects/{id}`. Partial — every field is optional; only supplied fields change. The project id in the path must match the caller's own project.
    ListI18nProfilesResponse:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            description: Stable opaque profile id.
          name:
            type: string
            description: Profile handle, e.g. `en:prod` or `fr:prod`.
          isDefault:
            description: '`1` for the project''s single default profile (always seeded as `en:prod`), else `0`.'
            type: number
          createdAt:
            description: ISO-8601 timestamp of creation.
            type: string
          deletedAt:
            description: ISO-8601 soft-delete timestamp, or `null` if live.
            anyOf:
              - type: string
              - type: 'null'
        required:
          - id
          - name
        additionalProperties: false
        description: One i18n locale profile.
    CreateI18nProfileRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^[a-z0-9][a-z0-9_:.-]*$
          description: Profile handle to create, e.g. `en:prod` or `fr:prod`. Lowercase alphanumeric start, then letters/digits/`_`/`:`/`.`/`-`; max 64 chars. The locale is encoded in the handle, so no separate locale fields are accepted.
      required:
        - name
      additionalProperties: false
      description: Body for `POST /api/admin/i18n/profiles`. Only `name` is accepted.
    CreateI18nProfileResponse:
      type: object
      properties:
        id:
          type: string
          description: Newly assigned profile id.
        name:
          type: string
          description: Profile handle that was created.
      required:
        - id
        - name
      additionalProperties: false
      description: Created profile id + name.
    ListI18nKeysResponse:
      type: object
      properties:
        keys:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Stable opaque key id.
              key:
                type: string
                description: Dotted key path, e.g. `home.cta`.
              value:
                type: string
                description: Current translated value for the key.
              description:
                description: Optional human note stored with the key.
                anyOf:
                  - type: string
                  - type: 'null'
              variables:
                description: '`{{var}}` placeholder names in the value, or `null` when there are none.'
                anyOf:
                  - type: array
                    items:
                      type: string
                  - type: 'null'
              profileId:
                description: Owning profile id.
                type: string
              chunkId:
                description: Owning chunk (authoring grouping) id.
                type: string
              updatedAt:
                description: ISO-8601 timestamp of the last edit.
                type: string
              updatedBy:
                description: Actor email that last edited the key.
                type: string
            required:
              - id
              - key
              - value
            additionalProperties: {}
            description: One i18n key row.
          description: The page of matching keys.
        total:
          type: number
          description: Total matching keys across all pages (ignores `limit`/`offset`).
      required:
        - keys
        - total
      additionalProperties: false
      description: A page of i18n keys plus the total count. (The client also tolerates a bare array.)
    PushI18nKeysRequest:
      type: object
      properties:
        profile_id:
          type: string
          format: uuid
          description: Target profile id to add keys to.
        chunk:
          description: Logical grouping the new keys are filed under. Defaults to `default`.
          type: string
          minLength: 1
          maxLength: 64
          default: default
        keys:
          type: array
          minItems: 1
          maxItems: 5000
          items:
            type: object
            properties:
              key:
                type: string
                minLength: 1
                maxLength: 256
                description: Dotted key path, e.g. `home.cta`.
              value:
                type: string
                description: Translated value for the key.
              description:
                type: string
                description: Optional human note stored with the key.
              variables:
                type: array
                maxItems: 32
                items:
                  type: string
                  minLength: 1
                  maxLength: 64
                description: Optional explicit list of `{{var}}` placeholder names in the value. Auto-derived from the value when omitted.
            required:
              - key
              - value
            additionalProperties: false
          description: Keys to add. Insert-only — existing keys are reported back as `skipped`.
      required:
        - profile_id
        - keys
      additionalProperties: false
      description: 'Body for `POST /api/admin/i18n/keys`. Insert-only: keys that already exist are never overwritten — use `PUT /keys/{id}` to change a value.'
    PushI18nKeysResponse:
      type: object
      properties:
        added:
          type: array
          items:
            type: string
          description: Key names that were newly inserted.
        skipped:
          type: array
          items:
            type: string
          description: Key names that already existed and were left untouched.
        pushed_count:
          type: number
          description: Number of keys inserted (== `added.length`).
        skipped_count:
          type: number
          description: Number of keys skipped (== `skipped.length`).
        chunk:
          description: The chunk the keys were filed under.
          type: string
      required:
        - added
        - skipped
        - pushed_count
        - skipped_count
      additionalProperties: false
      description: Result of an insert-only key push.
    UpdateI18nKeyRequest:
      type: object
      properties:
        value:
          type: string
          description: New value for the key (the only overwrite path).
        description:
          description: Optional human note to store with the key.
          type: string
        variables:
          description: Explicit `{{var}}` placeholder names in the value. Omit to auto-derive them from the value.
          type: array
          maxItems: 32
          items:
            type: string
            minLength: 1
            maxLength: 64
      required:
        - value
      additionalProperties: false
      description: Body for `PUT /api/admin/i18n/keys/{id}`. Updates one existing key's value.
    UpdateI18nKeyResponse:
      type: object
      properties:
        id:
          type: string
          description: Id of the key that was updated.
      required:
        - id
      additionalProperties: false
      description: Updated key id.
    ListI18nDraftsResponse:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            description: Stable opaque draft id.
          name:
            description: Draft name, e.g. the target locale being staged.
            type: string
          profileId:
            description: Profile the draft targets.
            type: string
          sourceProfileId:
            description: Profile the draft was seeded from, or `null`.
            anyOf:
              - type: string
              - type: 'null'
          status:
            description: Lifecycle state of the draft.
            type: string
            enum:
              - open
              - merged
              - abandoned
          createdBy:
            description: Actor email that created the draft.
            type: string
          createdAt:
            description: ISO-8601 timestamp of creation.
            type: string
          publishedAt:
            description: ISO-8601 merge/publish timestamp, or `null`.
            anyOf:
              - type: string
              - type: 'null'
        required:
          - id
        additionalProperties: {}
        description: One staged translation draft.
    CreateI18nDraftRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
          description: Draft name, e.g. the target locale being staged.
        profile_id:
          type: string
          format: uuid
          description: Profile the draft targets.
        source_profile_id:
          type: string
          format: uuid
          description: Optional profile to seed the draft's keys from.
      required:
        - name
        - profile_id
      additionalProperties: false
      description: Body for `POST /api/admin/i18n/drafts`. Stages a new translation draft against a target profile, optionally seeding from a source profile.
    I18nDraft:
      type: object
      properties:
        id:
          type: string
          description: Stable opaque draft id.
        name:
          type: string
          description: Draft name, e.g. the target locale being staged.
        profileId:
          type: string
          description: Profile the draft targets.
        sourceProfileId:
          anyOf:
            - type: string
            - type: 'null'
          description: Profile the draft was seeded from, or `null`.
        status:
          type: string
          enum:
            - open
            - merged
            - abandoned
          description: Lifecycle state of the draft.
        createdBy:
          type: string
          description: Actor email that created the draft.
        createdAt:
          type: string
          description: ISO-8601 timestamp of creation.
        publishedAt:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-8601 merge/publish timestamp, or `null`.
      required:
        - id
      additionalProperties: {}
      description: One staged translation draft.
    UpdateI18nDraftRequest:
      type: object
      properties:
        status:
          type: string
          enum:
            - open
            - merged
            - abandoned
          description: New lifecycle state for the draft.
      additionalProperties: false
      description: Body for `PATCH /api/admin/i18n/drafts/{draftId}`. Transitions the draft's lifecycle state.
    PublishI18nProfileRequest:
      type: object
      properties:
        chunk:
          description: Optional chunk label to stamp on the audit log. Publishing is profile-wide regardless — the whole profile is snapshotted into one KV blob.
          type: string
      additionalProperties: false
      description: Body for `POST /api/admin/i18n/profiles/{profileId}/publish`. The `chunk` is an audit label only.
    PublishI18nProfileResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
          description: Always `true` on success.
        profile_id:
          type: string
          description: Profile that was published.
        chunk:
          anyOf:
            - type: string
            - type: 'null'
          description: Audit chunk label, or `null` when none was given.
        published_at:
          type: string
          description: ISO-8601 timestamp of the publish.
        version:
          type: string
          description: New KV snapshot version that was shipped.
        key_count:
          type: number
          description: Number of keys in the published snapshot.
        changed:
          type: boolean
          description: Whether the snapshot's contents actually changed since the last publish.
        purged:
          type: string
          enum:
            - purged
            - skipped
            - failed
          description: 'CDN purge outcome: `purged` ok, `skipped` (no creds), or `failed` (edge still stale).'
        kv_verified:
          type: boolean
          description: Whether a KV read-back confirmed the new version persisted.
        warning:
          description: Human-readable caveat when the publish landed but is not fully live.
          type: string
      required:
        - ok
        - profile_id
        - chunk
        - published_at
        - version
        - key_count
        - changed
        - purged
        - kv_verified
      additionalProperties: false
      description: Result of a profile-wide publish.
    SetI18nLabelRequest:
      type: object
      properties:
        key:
          type: string
          minLength: 1
          maxLength: 256
          description: Dotted key path to set, e.g. `home.cta`.
        value:
          type: string
          description: New value for the key. Inserted when the key is new, overwritten when it exists.
        profile:
          description: Profile name to target, e.g. `en:prod`. Omit to target the project's default-marked profile.
          type: string
          minLength: 1
          maxLength: 64
        description:
          description: Optional human note to store with the key.
          type: string
      required:
        - key
        - value
      additionalProperties: false
      description: Body for `POST /api/admin/i18n/set`. Upserts one key's value and publishes the profile live.
    SetI18nLabelResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
          description: Always `true` on success.
        profile:
          type: string
          description: Name of the profile that was published.
        profile_id:
          type: string
          description: Id of the profile that was published.
        key:
          type: string
          description: The key that was set.
        value:
          type: string
          description: The value that was stored.
        published_at:
          type: string
          description: ISO-8601 timestamp of the publish.
        version:
          type: string
          description: New KV snapshot version that was shipped.
        key_count:
          type: number
          description: Number of keys in the published snapshot.
        changed:
          type: boolean
          description: Whether the snapshot's contents actually changed since the last publish.
        purged:
          type: string
          enum:
            - purged
            - skipped
            - failed
          description: 'CDN purge outcome: `purged` ok, `skipped` (no creds), or `failed` (edge still stale).'
        kv_verified:
          type: boolean
          description: Whether a KV read-back confirmed the new version persisted.
        warning:
          description: Human-readable caveat when the publish landed but is not fully live.
          type: string
      required:
        - ok
        - profile
        - profile_id
        - key
        - value
        - published_at
        - version
        - key_count
        - changed
        - purged
        - kv_verified
      additionalProperties: false
      description: Result of a one-shot set-and-publish.
    ErrorRecord:
      type: object
      description: |-
        A tracked production error — one row per distinct issue, keyed by `fingerprint`. Rows are never created by hand: an ingestion path (worker log drain / the `see()` SDK reporter) folds each occurrence into the matching row, bumping `count` and `lastSeenAt`. The admin surface only lists them, reads one, and flips `status`.

        Field names are camelCase (the D1 row projected through Drizzle). Many columns are nullable because the reporting source may not supply them.
      properties:
        id:
          type: string
          description: Stable opaque error id.
        projectId:
          type: string
          description: Project this issue belongs to.
        fingerprint:
          type: string
          description: Stable dedupe key (hash of `errorType` + normalized `message` + consequence). Unique per project — every occurrence with the same fingerprint folds into this one row.
        causedByFingerprint:
          description: Fingerprint of the issue this one descends from — set when `see()` reported the same error (re-throw) or its `{ cause }` (wrap) at an inner boundary first. Points at another error's `fingerprint` in the same project (soft reference, no FK). `null` for a root issue.
          anyOf:
            - type: string
            - type: 'null'
        message:
          type: string
          description: Error message text.
        errorType:
          description: Error class/name, e.g. `TypeError`. `null` when the source didn't supply one.
          anyOf:
            - type: string
            - type: 'null'
        stack:
          description: Stack trace of the latest occurrence, or `null` if none was captured.
          anyOf:
            - type: string
            - type: 'null'
        source:
          description: Where it surfaced — Worker name (`shipeasy`, `shipeasy-worker`) or `sdk-client` / `sdk-server`. `null` if unknown.
          anyOf:
            - type: string
            - type: 'null'
        url:
          description: Latest occurrence's raw URL (with ids intact), or `null`.
          anyOf:
            - type: string
            - type: 'null'
        seenUrls:
          description: Distinct, id-normalized route templates this issue has surfaced on, as a JSON-encoded string array (e.g. `["https://app/dashboard/#/gates"]`). UUIDs / numeric ids / opaque tokens are collapsed to `#` so the same route under different ids counts once. `null` if none recorded.
          anyOf:
            - type: string
            - type: 'null'
        subject:
          description: Consequence subject — `<errorType> causes the <subject> to <outcome>`. `null` if no consequence was reported.
          anyOf:
            - type: string
            - type: 'null'
        outcome:
          description: Consequence outcome — see `subject`. `null` if no consequence was reported.
          anyOf:
            - type: string
            - type: 'null'
        side:
          description: Which SDK side reported it — `client` or `server`. `null` if unknown.
          anyOf:
            - type: string
            - type: 'null'
        env:
          description: Published env the reporting SDK ran against (e.g. `dev`, `staging`, `prod`). `null` if unknown.
          anyOf:
            - type: string
            - type: 'null'
        kind:
          description: '`see()` error kind. `null` when the source didn''t classify the occurrence.'
          anyOf:
            - type: string
              enum:
                - caught
                - uncaught
                - unhandled_rejection
                - network
                - violation
            - type: 'null'
        lastExtrasJson:
          description: Latest occurrence's sanitized extras, JSON-encoded. `null` if none.
          anyOf:
            - type: string
            - type: 'null'
        sdkVersion:
          description: '`@shipeasy/sdk` version of the latest occurrence, or `null`.'
          anyOf:
            - type: string
            - type: 'null'
        count:
          type: integer
          minimum: 1
          description: Number of folded occurrences for this fingerprint.
        status:
          type: string
          enum:
            - open
            - resolved
            - ignored
          description: Triage state. `open` is the default; a `resolved` error reopens automatically (ingestion-side) if it recurs; `ignored` is sticky until flipped back here.
        firstSeenAt:
          type: string
          description: ISO-8601 timestamp of the first folded occurrence.
        lastSeenAt:
          type: string
          description: ISO-8601 timestamp of the most recent folded occurrence. Rows are ordered by this, descending.
        createdAt:
          type: string
          description: ISO-8601 timestamp the row was created.
        updatedAt:
          type: string
          description: ISO-8601 timestamp of the last mutation (e.g. a status flip).
      required:
        - id
        - projectId
        - fingerprint
        - message
        - count
        - status
        - firstSeenAt
        - lastSeenAt
        - createdAt
        - updatedAt
      additionalProperties: false
    ListErrorsResponse:
      type: array
      description: A bare JSON array of tracked errors, ordered by `lastSeenAt` descending. There is no pagination envelope — `limit` caps the page size.
      items:
        $ref: '#/components/schemas/ErrorRecord'
    UpdateErrorStatusRequest:
      type: object
      description: Body for `PATCH /api/admin/errors/{id}`. The only mutable field is `status` (open ⇄ resolved ⇄ ignored).
      properties:
        status:
          type: string
          enum:
            - open
            - resolved
            - ignored
          description: New triage state. `resolved` reopens automatically on recurrence; `ignored` is sticky.
      required:
        - status
      additionalProperties: false
    FileErrorTicketResponse:
      type: object
      description: The feedback ticket that tracks this error. Idempotent — if an open `error` ticket already tracks this fingerprint (hand- or auto-filed), the existing one is returned instead of creating a duplicate.
      properties:
        id:
          type: string
          description: Feedback ticket id.
        number:
          type: integer
          description: Human-facing per-project ticket number.
      required:
        - id
        - number
      additionalProperties: false
    ErrorSeriesRequest:
      type: object
      description: Time window for the occurrence series. Bounds are epoch **seconds** (Analytics Engine stores the occurrence timestamp in seconds). `to` must be strictly greater than `from`.
      properties:
        from:
          type: integer
          minimum: 0
          description: Window start, epoch seconds (inclusive).
        to:
          type: integer
          minimum: 0
          description: Window end, epoch seconds (exclusive). Must be greater than `from`.
        bucket:
          type: integer
          minimum: 60
          maximum: 86400
          default: 3600
          description: Bucket width in seconds (60s–86400s/1d). Defaults to `3600` (hourly). Each returned point is floor-aligned to this width.
      required:
        - from
        - to
      additionalProperties: false
    ErrorSeriesResponse:
      type: object
      description: Bucketed occurrence counts for one tracked error (by its fingerprint), plus the Analytics Engine SQL that produced them.
      properties:
        sql:
          type: string
          description: The Analytics Engine SQL executed to produce `rows` (echoed for transparency / debugging).
        rows:
          type: array
          description: Bucketed occurrence series, ordered by `t` ascending.
          items:
            type: object
            properties:
              t:
                type: integer
                description: Bucket start, epoch seconds, floor-aligned to `bucket`.
              v:
                type: number
                description: Occurrence count in the bucket (sample-interval weighted).
            required:
              - t
              - v
            additionalProperties: true
      required:
        - sql
        - rows
      additionalProperties: false
    ConnectorProvider:
      type: string
      enum:
        - google_sheets
        - github
        - slack
        - claude_trigger
        - cursor_trigger
        - copilot_trigger
        - jules_trigger
      description: Connector destination. OAuth/app providers (`google_sheets`, `github`, `slack`) dispatch the event payload to an external destination. Trigger providers (`claude_trigger`, `cursor_trigger`, `copilot_trigger`, `jules_trigger`) instead kick a coding-agent run that burns down the operational queue.
    ConnectorEvent:
      type: string
      enum:
        - bug.created
        - feature_request.created
      description: Lifecycle event a connector subscribes to. `bug.created` fires when a new bug report lands in the feedback inbox; `feature_request.created` fires for a new feature request. A connector dispatches (posts to Slack / appends a Sheets row / files a GitHub Issue) — or, for trigger connectors, auto-fires a coding-agent run — once per subscribed event.
    ConnectorRecord:
      type: object
      properties:
        id:
          type: string
          description: Stable opaque connector id (a UUID).
        projectId:
          type: string
          description: Id of the project the connector belongs to.
        provider:
          $ref: '#/components/schemas/ConnectorProvider'
        name:
          type: string
          maxLength: 80
          description: Human-readable connector label shown in the dashboard.
        enabled:
          type: boolean
          description: Whether the connector is active. OAuth providers are created `false` and flip to `true` only after the OAuth/config flow completes; trigger providers default to `true` on create. A disabled connector never dispatches and never auto-fires.
        events:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorEvent'
          description: Events this connector is subscribed to. Empty array = no auto-dispatch / no auto-fire (the connector can still be fired/tested manually).
        config:
          type: object
          additionalProperties: true
          description: Provider-specific, non-secret configuration (e.g. a Google Sheets `spreadsheetId`/`sheetTitle`, a Slack channel ref, or a trigger's repo coordinates + routine id). Secrets are never stored here — they live in an encrypted credentials cipher that is never returned by the API.
        accountLabel:
          anyOf:
            - type: string
            - type: 'null'
          description: Display label for the connected account / target (e.g. the OAuth account email, or a trigger's idempotency key such as its repo url or routine id). `null` until the connector is authenticated/configured.
        lastError:
          anyOf:
            - type: string
            - type: 'null'
          description: Error message from the most recent failed dispatch/fire attempt, or `null` if the last attempt succeeded (or none has run).
        lastAttemptAt:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-8601 timestamp of the most recent dispatch/fire attempt, or `null` if none has run.
        lastSuccessAt:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-8601 timestamp of the most recent successful dispatch/fire, or `null` if none has succeeded. Preserved across later failures.
        createdAt:
          type: string
          description: ISO-8601 timestamp of creation.
        updatedAt:
          type: string
          description: ISO-8601 timestamp of last mutation.
      required:
        - id
        - projectId
        - provider
        - name
        - enabled
        - events
        - config
        - accountLabel
        - lastError
        - lastAttemptAt
        - lastSuccessAt
        - createdAt
        - updatedAt
      additionalProperties: false
      description: A connector row. The encrypted credentials cipher backing the connector is intentionally never serialised.
    ListConnectorsResponse:
      type: array
      items:
        $ref: '#/components/schemas/ConnectorRecord'
      description: Bare array of every connector in the project (no pagination envelope).
    CreateOAuthConnectorRequest:
      type: object
      properties:
        provider:
          type: string
          enum:
            - google_sheets
            - github
            - slack
          description: OAuth/app connector destination.
        name:
          type: string
          minLength: 1
          maxLength: 80
          description: Human-readable connector label.
        events:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ConnectorEvent'
          description: Events to subscribe to. At least one is required.
      required:
        - provider
        - name
        - events
      additionalProperties: false
      description: 'Create an OAuth/app connector stub. The connector is created `enabled: false` with empty `config` and no credentials; the provider''s OAuth flow then attaches credentials and enables it.'
    ClaudeTriggerConfig:
      type: object
      properties:
        routineId:
          type: string
          minLength: 1
          description: The Claude Code routine id this connector fires (the id recorded at setup). Idempotency key for the connector.
        fireText:
          type: string
          minLength: 1
          description: Optional default prompt sent on a manual fire / when no event text applies.
      required:
        - routineId
      additionalProperties: false
      description: Non-secret config for a Claude trigger.
    CreateClaudeTriggerRequest:
      type: object
      properties:
        provider:
          type: string
          enum:
            - claude_trigger
          description: Discriminator. Claude Code scheduled-routine trigger.
        name:
          type: string
          minLength: 1
          maxLength: 80
          default: Claude trigger
          description: Human-readable connector label.
        events:
          type: array
          default: []
          items:
            $ref: '#/components/schemas/ConnectorEvent'
          description: Events that auto-fire the routine. Defaults to empty so the trigger does not auto-fire paid runs until events are subscribed.
        config:
          $ref: '#/components/schemas/ClaudeTriggerConfig'
        token:
          type: string
          minLength: 1
          description: The routine's fire bearer token (secret). **Optional** — a tokenless trigger is recorded but not fireable until a token is added later. Encrypted into the credentials cipher; never persisted in `config` or returned.
        enabled:
          type: boolean
          default: true
          description: Whether the trigger is active on create.
      required:
        - provider
        - config
      additionalProperties: false
      description: Create a Claude Code routine trigger in one shot. Idempotent by `config.routineId` — re-creating with the same routine id updates the existing row.
    CursorTriggerConfig:
      type: object
      properties:
        repoUrl:
          type: string
          format: uri
          description: Repo the cloud agent runs against, e.g. `https://github.com/owner/repo`. Idempotency key for the connector.
        startingRef:
          type: string
          minLength: 1
          description: Optional git ref the run starts from.
        projectId:
          type: string
          minLength: 1
          description: Shipeasy project id the run targets.
      required:
        - repoUrl
        - projectId
      additionalProperties: false
      description: Non-secret config for a Cursor trigger.
    CreateCursorTriggerRequest:
      type: object
      properties:
        provider:
          type: string
          enum:
            - cursor_trigger
          description: Discriminator. Cursor cloud-agent trigger.
        name:
          type: string
          minLength: 1
          maxLength: 80
          default: Cursor trigger
          description: Human-readable connector label.
        events:
          type: array
          default: []
          items:
            $ref: '#/components/schemas/ConnectorEvent'
          description: Events that auto-fire a cold cloud-agent run. Defaults to empty.
        config:
          $ref: '#/components/schemas/CursorTriggerConfig'
        apiKey:
          type: string
          minLength: 1
          description: Cursor API key that launches the run (secret). Encrypted into the credentials cipher; never returned.
        opsKey:
          type: string
          minLength: 1
          description: Restricted Shipeasy ops key, injected into the run as `SHIPEASY_CLI_TOKEN` via the launch envVars (secret). Encrypted; never returned.
        enabled:
          type: boolean
          default: true
          description: Whether the trigger is active on create.
      required:
        - provider
        - config
        - apiKey
        - opsKey
      additionalProperties: false
      description: Create a Cursor cloud-agent trigger. Both keys are required up front (never tokenless). Idempotent by `config.repoUrl`.
    CopilotTriggerConfig:
      type: object
      properties:
        owner:
          type: string
          minLength: 1
          description: GitHub repo owner. Together with `repo` forms the connector's idempotency key (`owner/repo`).
        repo:
          type: string
          minLength: 1
          description: GitHub repo name.
        baseRef:
          type: string
          minLength: 1
          description: Optional base ref the agent branches from.
        projectId:
          type: string
          minLength: 1
          description: Shipeasy project id the run targets.
      required:
        - owner
        - repo
        - projectId
      additionalProperties: false
      description: Non-secret config for a Copilot trigger.
    CreateCopilotTriggerRequest:
      type: object
      properties:
        provider:
          type: string
          enum:
            - copilot_trigger
          description: Discriminator. GitHub Copilot coding-agent trigger.
        name:
          type: string
          minLength: 1
          maxLength: 80
          default: Copilot trigger
          description: Human-readable connector label.
        events:
          type: array
          default: []
          items:
            $ref: '#/components/schemas/ConnectorEvent'
          description: Events that auto-fire a Copilot agent task. Defaults to empty.
        config:
          $ref: '#/components/schemas/CopilotTriggerConfig'
        token:
          type: string
          minLength: 1
          description: Copilot-licensed user PAT (secret). The ops key lives in the repo's GitHub "Agents" secret store and is never sent through Shipeasy. Encrypted; never returned.
        enabled:
          type: boolean
          default: true
          description: Whether the trigger is active on create.
      required:
        - provider
        - config
        - token
      additionalProperties: false
      description: Create a GitHub Copilot coding-agent trigger. Idempotent by `config.owner/config.repo`.
    JulesTriggerConfig:
      type: object
      properties:
        source:
          type: string
          minLength: 1
          description: Jules source for the connected repo, e.g. `sources/github/owner/repo`. Idempotency key for the connector.
        startingBranch:
          type: string
          minLength: 1
          description: Optional branch the session starts from.
        projectId:
          type: string
          minLength: 1
          description: Shipeasy project id the run targets.
      required:
        - source
        - projectId
      additionalProperties: false
      description: Non-secret config for a Jules trigger.
    CreateJulesTriggerRequest:
      type: object
      properties:
        provider:
          type: string
          enum:
            - jules_trigger
          description: Discriminator. Google Jules trigger.
        name:
          type: string
          minLength: 1
          maxLength: 80
          default: Jules trigger
          description: Human-readable connector label.
        events:
          type: array
          default: []
          items:
            $ref: '#/components/schemas/ConnectorEvent'
          description: Events that auto-fire a Jules session. Defaults to empty.
        config:
          $ref: '#/components/schemas/JulesTriggerConfig'
        apiKey:
          type: string
          minLength: 1
          description: Jules API key that launches the session (secret). Encrypted into the credentials cipher; never returned.
        opsKey:
          type: string
          minLength: 1
          description: Restricted Shipeasy ops key, embedded in the prompt (Jules exposes no env channel) (secret). Encrypted; never returned.
        enabled:
          type: boolean
          default: true
          description: Whether the trigger is active on create.
      required:
        - provider
        - config
        - apiKey
        - opsKey
      additionalProperties: false
      description: Create a Google Jules trigger. Both keys are required up front. Idempotent by `config.source`.
    CreateConnectorRequest:
      oneOf:
        - $ref: '#/components/schemas/CreateOAuthConnectorRequest'
        - $ref: '#/components/schemas/CreateClaudeTriggerRequest'
        - $ref: '#/components/schemas/CreateCursorTriggerRequest'
        - $ref: '#/components/schemas/CreateCopilotTriggerRequest'
        - $ref: '#/components/schemas/CreateJulesTriggerRequest'
      discriminator:
        propertyName: provider
        mapping:
          google_sheets: '#/components/schemas/CreateOAuthConnectorRequest'
          github: '#/components/schemas/CreateOAuthConnectorRequest'
          slack: '#/components/schemas/CreateOAuthConnectorRequest'
          claude_trigger: '#/components/schemas/CreateClaudeTriggerRequest'
          cursor_trigger: '#/components/schemas/CreateCursorTriggerRequest'
          copilot_trigger: '#/components/schemas/CreateCopilotTriggerRequest'
          jules_trigger: '#/components/schemas/CreateJulesTriggerRequest'
      description: Body for `POST /api/admin/connectors`, discriminated on `provider`. The OAuth providers (`google_sheets`/`github`/`slack`) create a disabled stub that is finished via the provider's OAuth flow. The trigger providers (`claude_trigger`/`cursor_trigger`/`copilot_trigger`/`jules_trigger`) arrive config + credentials together and are fireable immediately.
    CreateConnectorResponse:
      type: object
      properties:
        id:
          type: string
          description: Newly assigned connector id.
      required:
        - id
      additionalProperties: false
    DeleteConnectorResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
      required:
        - ok
      additionalProperties: false
    UpdateConnectorRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 80
          description: New connector label.
        enabled:
          type: boolean
          description: Toggle the connector on/off.
        events:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorEvent'
          description: Replaces the subscribed-events list wholesale. An empty array unsubscribes the connector from every event (e.g. turning off a trigger's auto-fire).
        config:
          type: object
          additionalProperties: true
          description: Replaces the non-secret config wholesale. Secrets are never set through this endpoint.
      additionalProperties: false
      description: Body for `PATCH /api/admin/connectors/{id}`. Partial — only supplied fields change. Array/object fields (`events`, `config`) replace, not merge.
    UpdateConnectorResponse:
      type: object
      properties:
        id:
          type: string
          description: Connector id that was updated.
      required:
        - id
      additionalProperties: false
      description: Update returns only the id — re-fetch via `GET /api/admin/connectors/{id}` for the full row.
    FireConnectorRequest:
      type: object
      properties:
        text:
          type: string
          description: Optional prompt override for the run. When omitted, each provider falls back to its own default (Claude → the configured `fireText`; the others → their built cold-start prompt).
      additionalProperties: false
      description: Body for `POST /api/admin/connectors/{id}/fire`. Entirely optional — an empty body kicks the run with the provider default.
    FireConnectorResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: Always `true` — a successful fire returns HTTP 200. A dispatch failure returns HTTP 502 with the `Error` envelope, not this body.
      required:
        - ok
      additionalProperties: false
      description: 'Result of a successful trigger fire: `{ ok: true }`. When the downstream dispatch fails the endpoint returns HTTP 502 (see the `Error` response), never `ok: false`.'
    TestConnectorResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: Always `true` — a successful test returns HTTP 200. A dispatch failure returns HTTP 502 with the `Error` envelope, not this body.
        issueUrl:
          anyOf:
            - type: string
            - type: 'null'
          description: URL of the artifact the test produced (e.g. the GitHub Issue created by a `github` connector), or `null` when the provider produces no linkable artifact.
      required:
        - ok
        - issueUrl
      additionalProperties: false
      description: 'Result of a successful connector test: `{ ok: true, issueUrl }`. When the downstream dispatch fails the endpoint returns HTTP 502 (see the `Error` response), never `ok: false`.'
    UpdateClaudeTriggerRequest:
      type: object
      properties:
        provider:
          type: string
          enum:
            - claude_trigger
          description: Discriminator. Claude Code scheduled-routine trigger.
        name:
          type: string
          minLength: 1
          maxLength: 80
          description: New connector label. Optional — omit to leave it unchanged.
        config:
          $ref: '#/components/schemas/ClaudeTriggerConfig'
        token:
          type: string
          minLength: 1
          description: New fire bearer token (secret). Optional — a blank/omitted token leaves the stored cipher untouched; a supplied one replaces it. Encrypted; never returned.
      required:
        - provider
        - config
      additionalProperties: false
      description: Per-provider PATCH body for editing an existing `claude_trigger` connector (the dashboard "Triggers" tab). The non-secret `config` is always supplied and replaces the stored config wholesale; `name` and `token` are optional.
    UpdateCursorTriggerRequest:
      type: object
      properties:
        provider:
          type: string
          enum:
            - cursor_trigger
          description: Discriminator. Cursor cloud-agent trigger.
        name:
          type: string
          minLength: 1
          maxLength: 80
          description: New connector label. Optional — omit to leave it unchanged.
        config:
          $ref: '#/components/schemas/CursorTriggerConfig'
        apiKey:
          type: string
          minLength: 1
          description: New Cursor launch key (secret). Optional — omit to leave the stored key untouched. Rotatable independently of `opsKey`. Encrypted; never returned.
        opsKey:
          type: string
          minLength: 1
          description: New restricted Shipeasy ops key (secret). Optional — omit to leave the stored key untouched. Rotatable independently of `apiKey`. Encrypted; never returned.
      required:
        - provider
        - config
      additionalProperties: false
      description: Per-provider PATCH body for editing an existing `cursor_trigger` connector. `config` replaces the stored config wholesale; `name` and either credential are optional (a supplied credential rotates just that key).
    UpdateCopilotTriggerRequest:
      type: object
      properties:
        provider:
          type: string
          enum:
            - copilot_trigger
          description: Discriminator. GitHub Copilot coding-agent trigger.
        name:
          type: string
          minLength: 1
          maxLength: 80
          description: New connector label. Optional — omit to leave it unchanged.
        config:
          $ref: '#/components/schemas/CopilotTriggerConfig'
        token:
          type: string
          minLength: 1
          description: New Copilot-licensed user PAT (secret). Optional — omit to leave the stored cipher untouched. Encrypted; never returned.
      required:
        - provider
        - config
      additionalProperties: false
      description: Per-provider PATCH body for editing an existing `copilot_trigger` connector. `config` replaces the stored config wholesale; `name` and `token` are optional.
    UpdateJulesTriggerRequest:
      type: object
      properties:
        provider:
          type: string
          enum:
            - jules_trigger
          description: Discriminator. Google Jules trigger.
        name:
          type: string
          minLength: 1
          maxLength: 80
          description: New connector label. Optional — omit to leave it unchanged.
        config:
          $ref: '#/components/schemas/JulesTriggerConfig'
        apiKey:
          type: string
          minLength: 1
          description: New Jules launch key (secret). Optional — omit to leave the stored key untouched. Rotatable independently of `opsKey`. Encrypted; never returned.
        opsKey:
          type: string
          minLength: 1
          description: New restricted Shipeasy ops key (secret). Optional — omit to leave the stored key untouched. Rotatable independently of `apiKey`. Encrypted; never returned.
      required:
        - provider
        - config
      additionalProperties: false
      description: Per-provider PATCH body for editing an existing `jules_trigger` connector. `config` replaces the stored config wholesale; `name` and either credential are optional.
    UpdateTriggerConnectorRequest:
      oneOf:
        - $ref: '#/components/schemas/UpdateClaudeTriggerRequest'
        - $ref: '#/components/schemas/UpdateCursorTriggerRequest'
        - $ref: '#/components/schemas/UpdateCopilotTriggerRequest'
        - $ref: '#/components/schemas/UpdateJulesTriggerRequest'
      discriminator:
        propertyName: provider
        mapping:
          claude_trigger: '#/components/schemas/UpdateClaudeTriggerRequest'
          cursor_trigger: '#/components/schemas/UpdateCursorTriggerRequest'
          copilot_trigger: '#/components/schemas/UpdateCopilotTriggerRequest'
          jules_trigger: '#/components/schemas/UpdateJulesTriggerRequest'
      description: 'Body for `PATCH /api/admin/connectors/{id}/trigger`, discriminated on `provider`. Edits an existing trigger connector: the non-secret `config` is always supplied and replaces the stored config wholesale; `name` and the credential secret(s) are optional (a supplied secret rotates just that key, a blank/omitted one leaves the stored cipher untouched).'
    CreateTriggerConnectorRequest:
      oneOf:
        - $ref: '#/components/schemas/CreateClaudeTriggerRequest'
        - $ref: '#/components/schemas/CreateCursorTriggerRequest'
        - $ref: '#/components/schemas/CreateCopilotTriggerRequest'
        - $ref: '#/components/schemas/CreateJulesTriggerRequest'
      discriminator:
        propertyName: provider
        mapping:
          claude_trigger: '#/components/schemas/CreateClaudeTriggerRequest'
          cursor_trigger: '#/components/schemas/CreateCursorTriggerRequest'
          copilot_trigger: '#/components/schemas/CreateCopilotTriggerRequest'
          jules_trigger: '#/components/schemas/CreateJulesTriggerRequest'
      description: Body for `POST /api/admin/connectors/trigger`, discriminated on `provider` — the trigger-provider subset of `CreateConnectorRequest` (no OAuth stubs). Config + credentials arrive together and the connector is usable immediately; creates are idempotent by each provider's natural key (`config.routineId` / `config.repoUrl` / `config.owner`+`config.repo` / `config.source`).
    KeyRecord:
      type: object
      description: A single API key as returned by the list endpoint. Response fields are snake_case. The raw token is never returned here — only its `last4` tail. `last4` and the typed `scopes` may be `null` for keys minted before those columns existed.
      properties:
        id:
          type: string
          description: Stable opaque key id (UUID). Use it to revoke the key.
        type:
          type: string
          enum:
            - server
            - client
            - admin
            - ops
          description: Key kind. `server` (back-end, full SDK auth), `client` (public, browser-embeddable), `admin` (CLI/devtools auth token), `ops` (restricted unattended-trigger credential).
        env:
          type: string
          enum:
            - dev
            - staging
            - prod
          description: Environment the key is bound to. The worker derives the read env from the key, so this is the isolation boundary. `admin`/`ops` keys are env-agnostic and pinned to `prod`.
        created_at:
          type: string
          description: ISO-8601 timestamp the key was minted.
        revoked_at:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-8601 timestamp the key was revoked, or `null` while the key is active.
        expires_at:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-8601 expiry, or `null` for a key that never expires. `admin` keys are fixed at 90 days; `ops` keys use a short sliding window.
        created_by_email:
          anyOf:
            - type: string
            - type: 'null'
          description: Email of the human or actor that minted the key, or `null` when not attributable (e.g. CLI device-flow).
        name:
          anyOf:
            - type: string
            - type: 'null'
          description: Human label for the key. `null` for unnamed dashboard mints; programmatic mints auto-name themselves.
        scopes:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          description: Permission strings recorded on the key for audit/display, or `null` when none were set.
        last4:
          anyOf:
            - type: string
            - type: 'null'
          description: Last 4 characters of the raw token, so the dashboard mask is matchable against the held key. `null` for keys minted before this column.
      required:
        - id
        - type
        - env
        - created_at
        - revoked_at
        - expires_at
        - created_by_email
        - name
        - scopes
        - last4
      additionalProperties: false
    ListKeysResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/KeyRecord'
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: Opaque cursor for the next page, or `null` on the last page. Pass it back as the `cursor` query parameter.
      required:
        - data
        - next_cursor
      additionalProperties: false
      description: One page of API keys plus a keyset `next_cursor` (ordered `created_at desc, id desc`).
    CreateKeyRequest:
      type: object
      description: |-
        Body for `POST /api/admin/keys`. Only `type` is required.

        `env` is **required** for `server` and `client` keys (the key is bound to one environment — that binding is the read-env isolation boundary). For `admin` and `ops` keys `env` is ignored and the key is pinned to `prod`.
      properties:
        type:
          type: string
          enum:
            - server
            - client
            - admin
            - ops
          description: Key kind to mint. `server` (back-end), `client` (public, browser), `admin` (CLI/devtools token), `ops` (restricted unattended-trigger credential). `admin`/`ops` keys don't count toward the plan key limit.
        name:
          type: string
          minLength: 1
          maxLength: 80
          description: Optional human label. Programmatic (API) mints that omit it get an auto-generated descriptive name; dashboard mints may leave it blank.
        scopes:
          type: array
          items:
            type: string
            enum:
              - experiments:read
              - gates:evaluate
              - events:write
              - configs:write
              - experiments:write
              - tickets:public_create
          description: 'Optional permission strings recorded on the key. `tickets:public_create` is enforced: a client key needs it (plus the project''s `allowPublicTickets` setting) to file a `pending_approval` bug via the public `POST /cli/report` endpoint. The rest are audit/display only.'
        expiresInDays:
          anyOf:
            - type: integer
              minimum: 1
              maximum: 3650
            - type: 'null'
          description: Days until the key expires (1–3650), or `null`/omitted for a key that never expires. Ignored for `admin` keys (fixed 90-day expiry) and `ops` keys (short sliding window).
        env:
          type: string
          enum:
            - dev
            - staging
            - prod
          description: Environment to bind the key to. Always required. For `server`/`client` keys it is the isolation boundary the worker reads from; `admin`/`ops` keys are env-agnostic and pinned to `prod` by the handler regardless of the value sent.
      required:
        - type
        - env
      additionalProperties: false
    CreateKeyResponse:
      type: object
      description: The minted key. The plaintext `key` is returned **once**, here — it is stored hashed and can never be retrieved again.
      properties:
        id:
          type: string
          description: Stable opaque key id (UUID). Use it to revoke the key.
        type:
          type: string
          enum:
            - server
            - client
            - admin
            - ops
          description: The kind of key that was minted.
        env:
          type: string
          enum:
            - dev
            - staging
            - prod
          description: Environment the key is bound to (`prod` for `admin`/`ops`).
        key:
          type: string
          description: The plaintext API token (e.g. `sdk_server_…`). Returned once — store it now; it cannot be recovered.
        expires_at:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-8601 expiry, or `null` if the key never expires.
      required:
        - id
        - type
        - env
        - key
        - expires_at
      additionalProperties: false
    RevokeKeyResponse:
      type: object
      description: Confirms the key is revoked. Idempotent — revoking an already-revoked key returns the same shape.
      properties:
        id:
          type: string
          description: Id of the key that was revoked.
        revoked:
          type: boolean
          const: true
      required:
        - id
        - revoked
      additionalProperties: false
    SearchHit:
      type: object
      description: A single universal-search hit. Field names are camelCase; `title` is `null` when the resource has no human title/display name (members fall back to a role label).
      properties:
        type:
          type: string
          enum:
            - member
            - gate
            - experiment
            - config
            - killswitch
            - metric
          description: Resource family — drives the result group + icon in the palette. (`member` hits are surfaced first.)
        id:
          type: string
          description: Stable identifier used to deep-link into the row's detail pane. For `member` hits this is the teammate's email; for everything else it is the resource id.
        name:
          type: string
          description: The matched handle — the resource's immutable `name`, or the member's display name (falling back to email).
        title:
          anyOf:
            - type: string
            - type: 'null'
          description: Human title/display name when present, else `null`. For `member` hits this carries the email (or the `Owner`/`Member` role when no profile name is set).
        href:
          type: string
          description: Project-relative href that opens the row (e.g. `/gates?open=<id>`).
      required:
        - type
        - id
        - name
        - title
        - href
      additionalProperties: false
    SearchResponse:
      type: object
      description: Flat, ranked-by-type list of search hits the command palette groups for display. Capped per resource family so one noisy type can't crowd out the rest.
      properties:
        hits:
          type: array
          items:
            $ref: '#/components/schemas/SearchHit'
      required:
        - hits
      additionalProperties: false
  responses:
    BadRequest:
      description: The request was malformed (bad JSON or missing project scope).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            BAD_REQUEST:
              summary: Malformed request
              value:
                error: Malformed request (bad JSON, missing project scope).
                code: BAD_REQUEST
    Unauthorized:
      description: Missing or invalid admin SDK key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            UNAUTHORIZED:
              summary: No / invalid key
              value:
                error: Missing or invalid admin SDK key.
                code: UNAUTHORIZED
    Forbidden:
      description: The key is valid but not allowed to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            FORBIDDEN:
              summary: Not an admin of this project
              value:
                error: Key is valid but not allowed to act on this project.
                code: FORBIDDEN
            PLAN_REQUIRED:
              summary: Feature gated behind a higher plan
              value:
                error: The requested feature requires a higher plan tier (e.g. sequential testing, custom alpha, holdout, group count).
                code: PLAN_REQUIRED
    NotFound:
      description: The resource does not exist or is not visible to the caller.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            NOT_FOUND:
              summary: Unknown id or name
              value:
                error: The resource does not exist or is not visible to the caller.
                code: NOT_FOUND
    Conflict:
      description: The mutation conflicts with current state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            ALREADY_EXISTS:
              summary: Duplicate name
              value:
                error: A resource with this name already exists in the project.
                code: ALREADY_EXISTS
            REFERENCED_IN_USE:
              summary: Still referenced by another resource
              value:
                error: The resource cannot be archived/deleted while another resource still references it.
                code: REFERENCED_IN_USE
            INVALID_TRANSITION:
              summary: Illegal lifecycle transition
              value:
                error: The requested lifecycle transition is not allowed from the current state.
                code: INVALID_TRANSITION
            IMMUTABLE_FIELD:
              summary: Edited an immutable field while running
              value:
                error: A field that is immutable in the current state was modified (e.g. editing allocation while running).
                code: IMMUTABLE_FIELD
    UnprocessableEntity:
      description: The request body failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            VALIDATION:
              summary: Schema validation failed
              value:
                error: The request body failed structural (schema) validation.
                code: VALIDATION
            REFERENCED_NOT_FOUND:
              summary: Referenced entity missing
              value:
                error: A referenced entity (universe, metric, gate, event) does not exist.
                code: REFERENCED_NOT_FOUND
            GROUPS_WEIGHT_SUM:
              summary: Group weights must sum to 10000
              value:
                error: Experiment group weights must sum to 10000 (basis points).
                code: GROUPS_WEIGHT_SUM
            EVENT_PENDING:
              summary: Event still pending review
              value:
                error: The referenced event is still pending review and cannot back a metric yet.
                code: EVENT_PENDING
    BadGateway:
      description: |-
        The request was well-formed and the resource exists, but a downstream provider
        the endpoint delegates to (e.g. a connector's Slack/GitHub/cloud-agent dispatch)
        failed. The failure is upstream of this API, not a client error. No stable
        `ErrorCode` is assigned to upstream failures, so `code` is omitted.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            UPSTREAM_FAILURE:
              summary: Downstream provider dispatch failed
              value:
                error: 'GitHub API responded 403: resource not accessible by integration.'