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: Fired Alerts
    parent: Ops
    description: |-
      Fired alerts: the conditions the platform has actually raised — metric-rule
      crossings, armed kill switches, experiment SRM/peek guards, and guardrail
      breaches. Raised only by the platform (UI killswitch handlers plus the
      worker analysis consumer and alerts cron), never filed by hand; deduped per
      `(source, dedupeKey)` with auto-resolve when the condition clears. This
      surface lists them and triages one (status flip + person/agent owner). The
      *rules* that define metric-threshold alerts are the sibling alert-rules
      resource.
  - name: Agents
    parent: Ops
    description: |-
      Connected AI agents — one per authenticated trigger connector (Claude /
      Cursor / Copilot / Jules). The read-only roster behind agent assignment
      and the `ops ack` agent types: an AI ack (`ops ack <handle> --agent
      <type>`) requires the type to appear here, so this list is where an
      `AGENT_NOT_CONNECTED` error sends you.
  - 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: Investigations
    parent: Ops
    description: |-
      Investigation records on a queue item — the structured, read-only write-ups
      an AI agent produces while working it (findings / a blocking question / QA
      notes), plus the `working` run rows an ack or an AI hand-off opens. This is
      the AI-write seam the cockpit's detail panel renders: `list` reads what a
      previous run found, `create` appends a new record, and `update` fills in the
      `working` run record you were handed (findings, PR, confidence) as you work.
  - 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, profile 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 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
                    creatorEmail: ana@example.com
                    updaterEmail: bo@example.com
                    version: 4
                    createdAt: '2026-05-01T10:12:00.000Z'
                    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}:
    get:
      operationId: getGate
      summary: Get one gate
      description: |-
        Returns the full gate row — including the gatekeeper `stack`, resolved creator/last-editor emails, and the edit `version` — for one gate, addressed by id or `name`.

        **Use case:** Inspect a single gate's current rollout, rules, and stack before editing it, without paging through the whole list.
      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: Get one gate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GateApiRow'
              example:
                id: gat_01j7w7m9q4hxbf6npe6s9zr3vc
                name: checkout_v2
                enabled: 1
                type: targeting
                rolloutPct: 5000
                rules:
                  - attr: country
                    op: in
                    value:
                      - US
                      - CA
                      - GB
                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
                creatorEmail: ana@example.com
                updaterEmail: bo@example.com
                version: 4
                createdAt: '2026-05-01T10:12:00.000Z'
                updatedAt: '2026-05-09T16:01:22.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: 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/gates/{id}/activity:
    get:
      operationId: listGateActivity
      summary: List gate activity
      description: |-
        Returns recent audit rows for one gate (create, update, enable, disable, delete) ordered newest first. Use the `limit` query parameter to cap the result (1–100, default 20).

        **Use case:** Render the activity feed in the gate detail panel or answer "who ramped this gate, and when?" during an incident review.
      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'
        - 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 gate activity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGateActivityResponse'
              example:
                - id: act_01j7waf01a2b3c4d5e6f7g8h9i
                  action: gate.update
                  actorEmail: ana@example.com
                  actorType: user
                  payload:
                    rollout_pct: 5000
                  createdAt: '2026-05-09T16:01:22.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/gates/{id}/whitelist:
    get:
      operationId: getGateWhitelist
      summary: Read a gate's whitelist
      description: |-
        Returns the gate's whitelist — the always-first allowlist that admits the listed identities before any targeting rule or percentage rollout is evaluated.

        A gate with no whitelist returns `entries: []` (and the default `attr`), never a 404 — so a caller can read-then-write without special-casing the empty gate.

        **Use case:** Check whether an account is already let through before adding it.
      tags:
        - Flags
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque gate id (`gate_…`) or the gate's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Read a gate's whitelist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GateWhitelist'
              example:
                id: gate_01j7w8a1b2c3d4e5f6g7h8i9j0
                name: new_checkout
                attr: email
                entries:
                  - alice@acme.dev
                  - bob@acme.dev
        '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: whitelist
        positional:
          - id
    put:
      operationId: setGateWhitelist
      summary: Replace a gate's whitelist
      description: |-
        Replaces the gate's whole whitelist with `entries`, creating the block if the gate didn't have one. Idempotent — the same call twice leaves the same list.

        This is the only whitelist call that can switch `attr` (`email` ⇄ `user_id`) or clear the block: `entries: []` removes the whitelist from the gate entirely.

        **Use cases**

        - **Pin an exact list** — `{ "entries": ["alice@acme.dev", "bob@acme.dev"] }`.
        - **Switch to user ids** — `{ "attr": "user_id", "entries": ["usr_123"] }`.
        - **Drop the whitelist** — `{ "entries": [] }`.
      tags:
        - Flags
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque gate id (`gate_…`) or the gate's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetGateWhitelistRequest'
            examples:
              pinList:
                summary: Pin an exact list of emails
                value:
                  entries:
                    - alice@acme.dev
                    - bob@acme.dev
              switchToUserIds:
                summary: Re-key the whitelist onto user ids
                description: Switching `attr` replaces the entries wholesale — the old emails are not translated.
                value:
                  attr: user_id
                  entries:
                    - usr_01j7w8a1b2c3d4e5f6g7h8i9j0
              clear:
                summary: Remove the whitelist
                description: An empty list drops the pinned block from the gate's stack.
                value:
                  entries: []
      responses:
        '200':
          description: Replace a gate's whitelist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GateWhitelist'
              example:
                id: gate_01j7w8a1b2c3d4e5f6g7h8i9j0
                name: new_checkout
                attr: email
                entries:
                  - alice@acme.dev
                  - bob@acme.dev
        '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: whitelist-set
        positional:
          - id
    post:
      operationId: addToGateWhitelist
      summary: Add entries to a gate's whitelist
      description: |-
        Adds identities to the gate's whitelist, creating the block if the gate doesn't have one yet. Entries already on the list are skipped, so the call is idempotent and safe to retry.

        Adding to a gate that already has a whitelist keyed on the other attribute is rejected (409) rather than silently re-keying the entries already there — use `PUT` to switch `attr` deliberately.

        **Use case:** Let one more customer into a private beta without reading the current list first.
      tags:
        - Flags
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque gate id (`gate_…`) or the gate's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddToGateWhitelistRequest'
            examples:
              addOne:
                summary: Admit one more email
                value:
                  entries:
                    - carol@acme.dev
              createOnUserIds:
                summary: Start a whitelist keyed on user ids
                description: '`attr` is honoured only because this gate has no whitelist yet.'
                value:
                  attr: user_id
                  entries:
                    - usr_01j7w8a1b2c3d4e5f6g7h8i9j0
      responses:
        '200':
          description: Add entries to a gate's whitelist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GateWhitelist'
              example:
                id: gate_01j7w8a1b2c3d4e5f6g7h8i9j0
                name: new_checkout
                attr: email
                entries:
                  - alice@acme.dev
                  - bob@acme.dev
                  - carol@acme.dev
        '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: whitelist-add
        positional:
          - id
    delete:
      operationId: removeFromGateWhitelist
      summary: Remove entries from a gate's whitelist
      description: |-
        Removes identities from the gate's whitelist. Entries that aren't on the list are skipped, so the call is idempotent.

        Removing the last entry leaves an empty whitelist block in place; to drop the block itself use `PUT` with `entries: []`.

        **Use case:** Revoke one beta tester's access without touching anyone else's.
      tags:
        - Flags
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque gate id (`gate_…`) or the gate's `name`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveFromGateWhitelistRequest'
            examples:
              removeOne:
                summary: Revoke one email
                value:
                  entries:
                    - carol@acme.dev
      responses:
        '200':
          description: Remove entries from a gate's whitelist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GateWhitelist'
              example:
                id: gate_01j7w8a1b2c3d4e5f6g7h8i9j0
                name: new_checkout
                attr: email
                entries:
                  - alice@acme.dev
                  - bob@acme.dev
        '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: whitelist-remove
        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/ExperimentApiRow'
              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
                    groupName: control
                    ds: '2026-05-09'
                    'n': 12421
                    mean: 0.1834
                    variance: 0.1498
                    delta: null
                    deltaPct: null
                    ci95Low: null
                    ci95High: null
                    ci99Low: null
                    ci99High: null
                    ciLow: null
                    ciHigh: null
                    pValue: null
                    expectedN: 15000
                    realizedMde: null
                    srmPValue: 0.82
                    srmDetected: 0
                    msprtSignificant: null
                    msprtLambda: null
                    isFinal: 0
                    peekWarning: 0
                  - metric: checkout_completed
                    groupName: treatment
                    ds: '2026-05-09'
                    'n': 12519
                    mean: 0.1922
                    variance: 0.1553
                    delta: 0.0088
                    deltaPct: 4.8
                    ci95Low: 0.0015
                    ci95High: 0.0161
                    ci99Low: -0.0008
                    ci99High: 0.0184
                    ciLow: 0.0015
                    ciHigh: 0.0161
                    pValue: 0.018
                    expectedN: 15000
                    realizedMde: 0.0079
                    srmPValue: 0.82
                    srmDetected: 0
                    msprtSignificant: null
                    msprtLambda: null
                    isFinal: 0
                    peekWarning: 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
                    groupName: treatment
                    ds: '2026-05-08'
                    'n': 11200
                    mean: 0.1903
                    variance: 0.1541
                    delta: 0.0071
                    deltaPct: 3.9
                    ci95Low: -0.0004
                    ci95High: 0.0146
                    ci99Low: -0.0028
                    ci99High: 0.017
                    ciLow: -0.0004
                    ciHigh: 0.0146
                    pValue: 0.034
                    expectedN: 15000
                    realizedMde: 0.0083
                    srmPValue: 0.79
                    srmDetected: 0
                    msprtSignificant: null
                    msprtLambda: null
                    isFinal: 0
                    peekWarning: 0
                  - metric: checkout_completed
                    groupName: treatment
                    ds: '2026-05-09'
                    'n': 12519
                    mean: 0.1922
                    variance: 0.1553
                    delta: 0.0088
                    deltaPct: 4.8
                    ci95Low: 0.0015
                    ci95High: 0.0161
                    ci99Low: -0.0008
                    ci99High: 0.0184
                    ciLow: 0.0015
                    ciHigh: 0.0161
                    pValue: 0.018
                    expectedN: 15000
                    realizedMde: 0.0079
                    srmPValue: 0.82
                    srmDetected: 0
                    msprtSignificant: null
                    msprtLambda: null
                    isFinal: 0
                    peekWarning: 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/experiments/{id}/readouts:
    post:
      operationId: createExperimentReadout
      summary: Mint a readout snapshot
      description: |-
        Freezes the current results view into an immutable, dated readout snapshot — verdict, headline, per-metric numbers, the caveat list with its acknowledgment state, enrollment, and a hash of the assignment-relevant config. Ship/stop flows mint one automatically; "Share readout" mints one on demand. Snapshots are never updated after insert.

        Pass `requireAllAcknowledged: true` to enforce ship gating server-side — returns `422` while any open caveat is not listed in `acknowledgedCaveatIds`.

        **Use case:** Capture "what the data said when we decided" before shipping or stopping, so the decision stays auditable even after results move.
      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/CreateExperimentReadoutRequest'
            examples:
              manual:
                summary: Manual — "Share readout"
                description: Snapshot the current results view on demand.
                value:
                  kind: manual
              shipGated:
                summary: Ship — with caveat gating
                description: Mint a ship readout, acknowledging the open caveats; fails with `422` if any open caveat is missing from the list.
                value:
                  kind: ship
                  acknowledgedCaveatIds:
                    - srm
                    - min_runtime
                  requireAllAcknowledged: true
      responses:
        '200':
          description: Mint a readout snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateExperimentReadoutResponse'
              example:
                id: 5f0c1f2d-8e90-4c6e-9b1a-3a7c1f2d8e90
          links:
            GetExperimentReadout:
              operationId: getExperimentReadout
              parameters:
                readoutId: $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
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: readout-create
        positional:
          - id
  /api/admin/experiments/{id}/readouts/{readoutId}:
    get:
      operationId: getExperimentReadout
      summary: Get a readout snapshot
      description: |-
        Returns one immutable readout snapshot — the frozen results view (verdict, headline, per-metric numbers, caveats, enrollment) captured when it was minted, plus the `configHash` that tells you whether it is still comparable to the live view.

        **Use case:** Render a shared, dated readout exactly as it looked at decision time.
      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: readoutId
          in: path
          required: true
          description: Readout snapshot id, as returned by `createExperimentReadout`.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Get a readout snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperimentReadoutApiRow'
              example:
                id: 5f0c1f2d-8e90-4c6e-9b1a-3a7c1f2d8e90
                experimentId: exp_01j7wb12c3d4e5f6g7h8j9k0l1
                experimentName: checkout_button_color
                kind: ship
                createdBy: pm@example.com
                createdAt: '2026-05-09T18:22:11.000Z'
                verdict: ship
                title: Treatment wins on checkout conversion
                why: Goal metric significant with guardrails flat after 8 days.
                configHash: 9c1f4f1f2c0c4a5fa1c2b6d3e7c8e3a19c1f4f1f2c0c4a5fa1c2b6d3e7c8e3a1
                metricsJson:
                  - name: checkout_completed
                    role: goal
                    delta: 0.0088
                    deltaPct: 4.8
                    ci:
                      - 0.0015
                      - 0.0161
                    p: 0.018
                    sig: true
                caveatsJson:
                  - id: min_runtime
                    severity: warn
                    text: Below the 14-day minimum runtime.
                    acknowledged: true
                usersJson:
                  groups:
                    - name: control
                      'n': 12421
                    - name: treatment
                      'n': 12519
                  days: 8
        '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: readout-get
        positional:
          - id
          - readoutId
  /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.
                    folder: pricing
                    creatorEmail: ana@example.com
                    createdAt: '2026-05-01T10:12:00.000Z'
                    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 under `value`, or pass the env keys `dev`/`staging`/`prod` directly (each overrides `value` for that env and is published at version 1).
      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 (env keys)
                description: Pass the env keys directly to seed different initial values per env. Each overrides `value` for that env and is published at version 1.
                value:
                  name: pricing.tiers
                  schema:
                    type: object
                    properties:
                      tiers:
                        type: array
                    required:
                      - tiers
                  dev:
                    tiers:
                      - name: free
                      - name: pro
                      - name: enterprise
                  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.
                folder: pricing
                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). A per-env key (`dev`/`staging`/`prod`) publishes a new version to **only that env**, immediately, overriding `value` for it. When `schema` is supplied it replaces the current schema; every existing value is re-validated.

        **Use cases**

        - **Republish flat value** — `{ "value": {…} }` sets the same value on every env.
        - **Publish one env** — `{ "prod": {…} }` publishes a new version to prod only, instantly.
        - **Schema migration** — `{ "schema": {…} }` replaces the schema; existing values are re-validated.
      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
              prodOnly:
                summary: Per-env — publish prod only
                description: Publishes a new version to prod only, immediately. dev/staging untouched.
                value:
                  prod:
                    tiers:
                      - name: free
                      - name: pro
                      - name: enterprise
              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
        hidden: true
        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
        hidden: true
        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
        hidden: true
        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
        hidden: true
        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/configs/{id}/versions:
    get:
      operationId: listConfigVersions
      summary: List config version history
      description: |-
        Returns every published version of the config's value on one env, newest first. The `env` query parameter picks the environment (`dev`, `staging`, or `prod`) and defaults to `prod`; an unknown env returns `400`. The config's JSON Schema is config-level and not versioned — this is value history only.

        **Use case:** Render the History timeline in the config detail pane (value diff + restore), or audit which value was live on prod at a given version.
      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: env
          in: query
          required: false
          description: Environment to list history for (`dev`, `staging`, or `prod`). Defaults to `prod` when omitted.
          schema:
            $ref: '#/components/schemas/Env'
      responses:
        '200':
          description: List config version history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListConfigVersionsResponse'
              example:
                - version: 5
                  value:
                    tiers:
                      - name: free
                      - name: pro
                  publishedAt: '2026-05-09T18:22:11.000Z'
                  publishedBy: ana@example.com
                - version: 4
                  value:
                    tiers:
                      - name: free
                  publishedAt: '2026-05-08T11:05:22.000Z'
                  publishedBy: bo@example.com
        '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: versions
        hidden: true
        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.
                    folder: payments
                    creatorEmail: ana@example.com
                    createdAt: '2026-05-01T10:12:00.000Z'
                    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.
                folder: payments
                creatorEmail: ana@example.com
                createdAt: '2026-05-01T10:12:00.000Z'
                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/killswitches/{id}/toggle:
    post:
      operationId: toggleKillswitch
      summary: Toggle a killswitch or one of its switches
      description: |-
        Flips a killswitch on one environment and publishes a new version there. This is the one-call incident verb: it reads the current value, flips it, and publishes, so you don't have to fetch the killswitch first.

        Every body field is optional, which is what makes the call widen cleanly:

        - **Flip the killswitch** — `{}`. Flips the flat `value` on `prod`.
        - **Flip one sub-switch** — `{ "switchKey": "eu_region" }`. Flips that entry on `prod`, creating it (from `false`) if it isn't in the map yet.
        - **Set it idempotently** — `{ "switchKey": "eu_region", "value": true }`. Publishes exactly that value, so a retried call can't undo the first one. A `null` `value` means "flip", not "set to null".
        - **Choose the environment** — add `"env": "staging"`. Omitted, `env` is `prod`.

        The response reports both `previous` and `value`, so a caller that asked for a flip can see what it actually changed.

        Prefer this over `PUT /{id}/value` and `PUT /{id}/switch` unless you specifically need those endpoints' unconditional set semantics.
      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: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToggleKillswitchRequest'
            examples:
              flipOnProd:
                summary: Flip the killswitch on prod
                description: No body fields — reads the flat `value` on prod and publishes its opposite.
                value: {}
              flipOneSwitch:
                summary: Flip one sub-switch on prod
                description: Flips `switches.eu_region` on prod, leaving the flat `value` and every other key alone.
                value:
                  switchKey: eu_region
              setOneSwitch:
                summary: Trip one sub-switch idempotently
                description: Publishes `switches.eu_region = true` on prod whatever it was before — safe to retry.
                value:
                  switchKey: eu_region
                  value: true
              setOneSwitchOnStaging:
                summary: Trip one sub-switch on a chosen env
                description: The same idempotent set, published on staging instead of prod.
                value:
                  switchKey: eu_region
                  value: true
                  env: staging
      responses:
        '200':
          description: Toggle a killswitch or one of its switches
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToggleKillswitchResponse'
              example:
                id: ksw_01j7w9d8h2k4m6n8p0q2r4s6t8
                env: prod
                switchKey: eu_region
                previous: false
                value: true
                version: 7
                published:
                  value: false
                  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: toggle
        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:
                - id: attr_01j7w8a1b2c3
                  name: plan
                  type: enum
                  enumValues:
                    - free
                    - paid
                  required: 1
                  description: Billing plan of the calling user.
                  sdkPath: user.plan
                  createdAt: '2026-06-20T09:14:08.000Z'
                  source: manual
                  lastSeenAt: '2026-07-16T22:04:11.000Z'
                  deprecated: 0
                - id: attr_01j7w8a1b2c4
                  name: country
                  type: string
                  enumValues: null
                  required: 0
                  description: null
                  sdkPath: null
                  createdAt: '2026-06-20T09:14:08.000Z'
                  source: auto
                  lastSeenAt: '2026-07-16T22:04:11.000Z'
                  deprecated: 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
      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(checkout_completed)
                  queryIr:
                    v: 2
                    expr:
                      node: agg
                      event: checkout_completed
                      agg:
                        kind: count
                      filters: []
                  direction: higher_better
                  version: 1
        '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(<event>)` for event 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:
              countEvents:
                summary: Count an event (DSL)
                description: Completed checkouts, expressed with the query DSL.
                value:
                  name: checkouts
                  event_name: checkout_completed
                  query: count(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:
                    v: 2
                    expr:
                      node: agg
                      event: checkout_completed
                      agg:
                        kind: count
                      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:
                  v: 2
                  expr:
                    node: agg
                    event: purchase
                    agg:
                      kind: sum
                    valueLabel: amount
                    filters: []
                direction: higher_better
                winsorizePct: 99
                version: 1
        '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/metrics/{id}/experiments:
    get:
      operationId: listMetricExperiments
      summary: List experiments using a metric
      description: |-
        Returns every experiment that attaches this metric — as `goal`, `guardrail`, or `secondary` — ordered with running experiments first, then by role weight (goal > guardrail > secondary).

        **Use case:** See who depends on a metric before editing or archiving it — e.g. the metric detail panel's "used by" list.
      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: List experiments using a metric
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMetricExperimentsResponse'
              example:
                experiments:
                  - id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
                    name: checkout_button_color
                    status: running
                    role: goal
                  - id: exp_01j7wb98x7y6z5w4v3u2t1s0r9
                    name: pricing_page_copy
                    status: stopped
                    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
      x-cli:
        name: experiments
        positional:
          - id
  /api/admin/metrics/{id}/unarchive:
    post:
      operationId: unarchiveMetric
      summary: Unarchive a metric
      description: |-
        Reverses a soft-delete (archive), making the metric live again. Idempotent — unarchiving a metric that is already live succeeds with no effect.

        **Use case:** Undo an accidental archive (the metrics list "Undo" toast calls this).
      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: Unarchive a metric
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnarchiveMetricResponse'
              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: unarchive
        positional:
          - id
  /api/admin/metrics/{id}/series:
    post:
      operationId: getMetricSeries
      summary: Get a metric's time series
      description: |-
        Compiles the metric's typed IR into Analytics Engine SQL and returns the bucketed series over the requested window (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.

        Returns `422` when the stored definition can't compile (e.g. a label or event has gone away — re-save the metric), and `502`/`503` when the analytics upstream fails or isn't configured.

        **Use case:** Render the metric trend chart / sparkline, or pull raw bucketed values to feed an external dashboard.
      tags:
        - Metrics
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque metric id (`met_…`).
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetMetricSeriesRequest'
            examples:
              lastDayHourly:
                summary: Last 24h, hourly buckets
                description: Hourly metric values over a one-day window (bounds in epoch seconds).
                value:
                  from: 1751000400
                  to: 1751086800
                  bucket: 3600
      responses:
        '200':
          description: Get a metric's time series
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMetricSeriesResponse'
              example:
                sql: |-
                  SELECT intDiv(toUInt32(double2), 3600) * 3600 AS t,
                    sum(_sample_interval) AS v
                  FROM shipeasy_metric_events
                  WHERE index1 = 'e976b15e-2f0d-4c6e-9b1a-3a7c1f2d8e90'
                    AND blob1 = 'checkout_completed'
                    AND double2 >= 1751000400 AND double2 < 1751086800
                  GROUP BY t
                  ORDER BY t
                rows:
                  - t: 1751000400
                    v: 412
                  - t: 1751004000
                    v: 531
                  - t: 1751007600
                    v: 468
        '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: series
        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, measurement plans) 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, or `all` (the default). Every type a returned item can carry is filterable, including the auto-filed ones.
          schema:
            default: all
            anyOf:
              - 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.
              - type: string
                const: all
        - name: status
          in: query
          required: false
          description: Filter by lifecycle status, or `all` (the default). The human-gated holding state (`pending_approval`) is excluded from `all`/default and returned only when requested as the exact status.
          schema:
            default: all
            anyOf:
              - $ref: '#/components/schemas/OpsItemStatus'
              - type: string
                const: all
        - name: limit
          in: query
          required: false
          description: Max items to return (1–500). Defaults to 200.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 200
        - name: owner
          in: query
          required: false
          description: Narrow to items owned by one person OR one agent. Matches a person by `users.id`, email, or display name, and an agent by connector id, display name, or kebab-case handle — e.g. `owner=Claude` or `owner=alice@acme.dev`. Case-insensitive exact match, applied over the returned page.
          schema:
            type: string
      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
                  source: team
                  owner:
                    user:
                      id: usr_01j7w8a1b2c3d4e5f6g7h8i9j0
                      email: alice@acme.dev
                      name: Alice
                    agent: null
                  run: null
                  lastRun: null
                  createdAt: '2026-06-20T09:14:08.000Z'
                  updatedAt: '2026-06-21T10:02:44.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
  /ops/bug:
    post:
      operationId: createPublicBug
      summary: File a bug
      description: |-
        Files one bug onto a project's queue, awaiting human approval. This is the **public** intake: it authenticates with a *client* SDK key rather than an admin key, so it can be called from a CLI, an installer script, a devtools overlay, or any shipped code — the same places a client key already lives.

        Three gates decide whether a ticket is filed, and nothing else the caller sends can widen them:

        1. the key is a `client` key carrying the `tickets:public_create` scope,
        2. the key's project has public ticket creation enabled, and
        3. the item is filed as `pending_approval` — parked out of the work queue until a human promotes it in the dashboard.

        The project is the key's own project; there is no `X-Project-Id` to pass and no way to file into someone else's queue. Repeat submissions of the same title dedupe against the open ticket already tracking it, which returns `200` with `deduped: true` instead of filing again.

        This endpoint is served by the Shipeasy **edge worker** (`api.shipeasy.ai`), not the admin API — see `servers` below.

        **Use case:** `shipeasy setup` fails on a customer's machine and self-reports the failure with the user's consent — `{ "title": "Setup failed at Feature installs", "stepsToReproduce": "…", "actualResult": "…" }`.
      tags:
        - Ops
      servers:
        - url: https://api.shipeasy.ai
          description: Shipeasy edge worker (production)
        - url: http://localhost:8787
          description: Local `wrangler dev`
      security:
        - clientSdkKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePublicBugRequest'
            examples:
              minimal:
                summary: Just a title
                description: Every other field is optional — the queue triages from `open` at default priority.
                value:
                  title: Checkout button misaligned on mobile
              full:
                summary: A full report
                value:
                  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
                  reporterEmail: alice@acme.dev
                  pageUrl: https://acme.dev/cart
      responses:
        '200':
          description: An open ticket already tracks this report; nothing was filed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePublicTicketResponse'
              example:
                number: 7
                deduped: true
        '201':
          description: File a bug
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePublicTicketResponse'
              example:
                id: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
                number: 7
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - VALIDATION
      x-cli:
        hidden: true
  /ops/feature-request:
    post:
      operationId: createPublicFeatureRequest
      summary: File a feature request
      description: |-
        Files one feature request onto a project's queue, awaiting human approval. The feature-request counterpart to `POST /ops/bug`, with the same three gates: a `client` key carrying `tickets:public_create`, a project that has opted in, and a `pending_approval` state forced server-side.

        The project is the key's own project; there is no `X-Project-Id` to pass. Repeat submissions of the same title dedupe against the open ticket already tracking it, which returns `200` with `deduped: true` instead of filing again.

        This endpoint is served by the Shipeasy **edge worker** (`api.shipeasy.ai`), not the admin API — see `servers` below.

        **Use case:** An in-product "request a feature" form posts what the user asked for — `{ "title": "Dark mode", "useCase": "Reduce eye strain at night" }`.
      tags:
        - Ops
      servers:
        - url: https://api.shipeasy.ai
          description: Shipeasy edge worker (production)
        - url: http://localhost:8787
          description: Local `wrangler dev`
      security:
        - clientSdkKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePublicFeatureRequestRequest'
            examples:
              minimal:
                summary: Just a title
                value:
                  title: Dark mode for the dashboard
              full:
                summary: A full request
                value:
                  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
                  reporterEmail: alice@acme.dev
      responses:
        '200':
          description: An open ticket already tracks this report; nothing was filed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePublicTicketResponse'
              example:
                number: 7
                deduped: true
        '201':
          description: File a feature request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePublicTicketResponse'
              example:
                id: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
                number: 8
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - VALIDATION
      x-cli:
        hidden: true
  /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
    delete:
      operationId: deleteOpsItem
      summary: Delete a queue item
      description: |-
        Permanently delete a queue item — any type — along with its comment thread, attachments, tags, and investigation records. A human (dashboard) action: the route is never allow-listed for restricted ops keys. Irreversible; to take an item out of the queue without destroying it, set its status (`wont_fix`/`resolved`) instead.

        **Use case:** Remove a junk or duplicate report for good.
      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: Delete a queue item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteOpsItemResponse'
              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
  /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}/ack:
    post:
      operationId: ackOpsItem
      summary: Ack an item (start a run)
      description: |-
        Acknowledge a queue item — a person or an AI agent declaring "I'm on this
        now". Opens a run: stamps who picked the item up and when, assigns them as
        owner, and moves the item into the matching working status
        (`investigating_by_ai` for an AI ack, `in_progress` for a human one). The
        dashboard renders the open run as a live working indicator (which agent +
        time since the run started).

        **AI ack.** Pass `agent` with your own agent type (`claude`, `cursor`,
        `copilot`, `jules`; `gemini` aliases `jules`) and, when you have one, the
        run's `sessionId` so the dashboard can deep-link to the session. If the
        project has no connected trigger connector of that type the call fails
        with `AGENT_NOT_CONNECTED` — list the available agents with `ops agents
        list` and use one of those (or connect the agent under Settings →
        Triggers).

        **Completion.** The run closes automatically on the loop's final actions —
        linking the fixing PR (`link-pr`), an ops-notify escalation, or a
        completion status change (`ready_for_qa`/`resolved`) — and the dashboard
        then shows the run result (final action, PR, duration, session link).
        A repeat ack supersedes the previous open run.

        **Use case:** Call this first when picking an item up, so the team sees
        who/what is working on it in real time.
      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: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AckOpsItemRequest'
            example:
              agent: claude
              sessionId: session_01CiaFDeDyr37JZ62Gzd8oir
      responses:
        '200':
          description: Ack an item (start a run)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AckOpsItemResponse'
              example:
                id: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
                number: 7
                status: investigating_by_ai
                runId: 6f1f9a1e-8b32-4c8e-9a51-2f3b1c9d0e4a
                agent: claude
                connectorName: Claude
                sessionId: session_01CiaFDeDyr37JZ62Gzd8oir
                startedAt: '2026-07-17T10:15:00.000Z'
        '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
        - AGENT_NOT_CONNECTED
        - VALIDATION
      x-cli:
        name: ack
        positional:
          - handle
  /api/admin/ops/{handle}/investigation:
    get:
      operationId: listOpsInvestigations
      summary: List an item's investigation records
      description: |-
        The structured, read-only investigation records on a queue item — the
        findings / blocking questions / QA notes an AI agent posted while working
        it, plus its `working` run rows. Returns `published` records only, newest
        first (max 50).

        **Use case:** Read what a previous agent run already found before starting
        your own investigation of the item.
      tags:
        - Investigations
      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 investigation records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOpsInvestigationsResponse'
        '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
      x-cli:
        name: list
        positional:
          - handle
    post:
      operationId: createOpsInvestigation
      summary: Record an investigation
      description: |-
        Append one structured investigation record to a queue item — the AI-write
        seam the cockpit's detail panel renders read-only. Post your findings
        (`kind: investigated`), a blocking question for the team (`kind:
        question`), or how to verify the fix (`kind: ready_for_qa` with
        `qaNotes`). Append-only and create-only, so it is safe for restricted ops
        keys.

        **Use case:** After working an item, leave a findings write-up (summary,
        markdown findings, sources inspected, confidence) so the team — and the
        next agent run — sees what you learned.
      tags:
        - Investigations
      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/CreateOpsInvestigationRequest'
            examples:
              findings:
                summary: Post a findings write-up
                value:
                  kind: investigated
                  summary: Root cause is a stale KV read on the checkout flag.
                  findings: The `checkout.cta` gate is rebuilt without a CDN purge, so…
                  agent: claude
                  confidence: high
                  sources:
                    - path: packages/core/src/kv/rebuild.ts
                      label: KV rebuild helper
              question:
                summary: Ask the team a blocking question
                value:
                  kind: question
                  question: Should the fix preserve the legacy `?v=1` query param behaviour?
                  agent: claude
      responses:
        '200':
          description: Record an investigation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpsInvestigation'
        '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
        positional:
          - handle
  /api/admin/ops/{handle}/investigation/{investigationId}:
    patch:
      operationId: updateOpsInvestigation
      summary: Update an investigation record
      description: |-
        Update one existing investigation record in place — the write-back seam for
        the `working` run record you were handed when a run was launched. Fill in
        the `summary`/`findings`, attach the fixing PR, record your `confidence`
        and the `sources` you inspected, or flip its `kind` off `working` once the
        investigation is done. A partial patch: send only the fields you want to
        change. Safe for restricted ops keys (it never reads or deletes).

        **Use case:** A run started with an empty `working` record; as you work,
        PATCH it with your findings so the cockpit's detail panel fills in live —
        no need to append a second record.
      tags:
        - Investigations
      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'
        - name: investigationId
          in: path
          required: true
          description: The investigation record id (from `POST`/`GET .../investigation` or the `runId` an ack/launch returned).
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOpsInvestigationRequest'
            examples:
              findings:
                summary: Fill in the run record's findings
                value:
                  kind: investigated
                  summary: Root cause is a stale KV read on the checkout flag.
                  findings: The `checkout.cta` gate is rebuilt without a CDN purge, so…
                  confidence: high
                  prNumber: 4821
                  prUrl: https://github.com/acme/web/pull/4821
      responses:
        '200':
          description: The updated investigation record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpsInvestigation'
        '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: update
        positional:
          - handle
          - investigationId
  /api/admin/agent-profiles:
    get:
      operationId: listOpsAgents
      summary: List connected AI agents
      description: |-
        The project's connected AI agents — one per authenticated trigger
        connector (Claude / Cursor / Copilot / Jules). These are the agent types
        `ops ack` accepts and the agents a queue item can be assigned to.

        **Use case:** Discover which `agent` values an AI ack can use, e.g. after
        an `AGENT_NOT_CONNECTED` error.
      tags:
        - Agents
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: List connected AI agents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOpsAgentsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-error-codes:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
      x-cli:
        name: list
  /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/alerts:
    get:
      operationId: listAlerts
      summary: List fired alerts
      description: |-
        Returns the project's FIRED alerts as a **bare JSON array** (no pagination envelope), ordered by `createdAt desc`. Defaults to the currently-firing ones (`status=active`); pass a `status` to widen to resolved/dismissed history or `all`.

        A fired alert is an **instance** of an alert rule, and an instance IS its ops queue item — the same row `/api/admin/ops` returns with `type: "alert"`, viewed through the alert lens. One rule produces many instances over its life and at most one is open at a time: when the condition clears the instance closes, and the next firing is a NEW instance with its own id and history. That is why `severity` reads off the rule (the queue item carries it as `priority`) and why resolving the queue item and clearing the alert are one act, not two rows to keep in step.

        Instances are opened only by the platform — the UI's killswitch handlers plus the worker's analysis consumer and alerts cron — never filed by hand, so this surface is list + triage (via PATCH), with no create. The rules that *define* metric-threshold alerts live at `/api/admin/alert-rules`.

        **Use case:** Snapshot what is currently firing for an on-call view or the home Alerts block, or pull `status=all` to audit how a noisy rule has behaved over time.
      tags:
        - Fired Alerts
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: status
          in: query
          required: false
          description: Filter by lifecycle state. Defaults to `active` (currently firing); `all` returns every status.
          schema:
            type: string
            enum:
              - active
              - resolved
              - dismissed
              - all
            default: active
      responses:
        '200':
          description: List fired alerts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAlertsResponse'
              example:
                - id: al_01j7w9c4d5e6f7g8h9i0j1k2l3
                  source: metric_rule
                  ruleId: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
                  severity: danger
                  dedupeKey: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
                  title: Checkout error rate above threshold
                  detail: checkout_errors was 137 over the trailing 24h — above the rule's threshold of 50.
                  href: /dashboard/metrics/met_01j6abc2d3e4f5g6h7i8j9k0l1
                  observedValue: 137
                  status: active
                  createdAt: '2026-06-28T14:55:31.000Z'
                  resolvedAt: null
                  dismissedAt: null
                  assigneeId: null
                  assigneeConnectorId: null
                  assigneeAgent: null
                - id: al_01j7w9b2a1z0y9x8w7v6u5t4s3
                  source: killswitch_armed
                  ruleId: null
                  severity: warn
                  dedupeKey: ks_01j5checkout_kill
                  title: Kill switch "checkout_kill" is armed
                  detail: The kill switch has been armed for 3 days — confirm it is still intentional.
                  href: /dashboard/killswitches/ks_01j5checkout_kill
                  observedValue: null
                  status: active
                  createdAt: '2026-06-27T09:12:05.000Z'
                  resolvedAt: null
                  dismissedAt: null
                  assigneeId: 6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c
                  assigneeConnectorId: null
                  assigneeAgent: 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
  /api/admin/alerts/{id}:
    patch:
      operationId: updateAlert
      summary: Update a fired alert
      description: |-
        Triage writes on one fired alert — the only mutations this surface allows. All body fields are optional (at least one required); only the fields present are changed.

        - **`status`** — flip between `active` / `resolved` / `dismissed`. `resolved` and `dismissed` stamp `resolvedAt` / `dismissedAt`; `active` re-opens and clears both. These write the underlying queue item's own status (`resolved` / `wont_fix` / `open`), so clearing an alert here and resolving it in the ops queue are the same act. A cleared instance is never revived: if the condition fires again it opens a NEW instance with its own id.
        - **`assigneeId`** — the PERSON owner (a `users.id`), or `null` to unassign.
        - **`agent`** — the AGENT owner: a connected trigger connector's id, or the built-in `"jarvis"` (**Enterprise plan only** — `403` otherwise), or `null` to clear. Person and agent halves are independent.

        Returns the updated row; `404` if the alert does not exist in the project.

        **Use cases**

        - **Wave off a known condition** — `{ "status": "dismissed" }` on an alert that needs no action.
        - **Hand it to someone** — `{ "assigneeId": "…" }` from the ops cockpit's Owner column.
      tags:
        - Fired Alerts
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: Stable opaque instance id — the same id as the `alert` ops item this instance is.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAlertRequest'
            examples:
              resolve:
                summary: Mark resolved
                description: Close out a fired alert once the underlying condition is handled.
                value:
                  status: resolved
              dismiss:
                summary: Dismiss a benign alert
                description: Wave off an alert that needs no action.
                value:
                  status: dismissed
              assignPerson:
                summary: Assign a person owner
                description: Hand the alert to a teammate from the ops cockpit's Owner column.
                value:
                  assigneeId: 6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c
              assignAgent:
                summary: Assign an agent owner
                description: Hand the alert to a connected coding agent (a connector id, or `"jarvis"` on Enterprise).
                value:
                  agent: con_01j7wagentclaude0001
      responses:
        '200':
          description: Update a fired alert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertApiRow'
              example:
                id: al_01j7w9c4d5e6f7g8h9i0j1k2l3
                source: metric_rule
                ruleId: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
                severity: danger
                dedupeKey: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
                title: Checkout error rate above threshold
                detail: checkout_errors was 137 over the trailing 24h — above the rule's threshold of 50.
                href: /dashboard/metrics/met_01j6abc2d3e4f5g6h7i8j9k0l1
                observedValue: 137
                status: resolved
                createdAt: '2026-06-28T14:55:31.000Z'
                resolvedAt: '2026-06-28T16:40:12.000Z'
                dismissedAt: null
                assigneeId: null
                assigneeConnectorId: null
                assigneeAgent: 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
        - NOT_FOUND
        - VALIDATION
      x-cli:
        name: update
        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}:
    get:
      operationId: getProject
      summary: Show a project by id
      description: |-
        Returns one project by id — the same full shape as `GET /api/admin/projects/current`. The id in the path must match the project the caller's credential resolves to (a credential can only read its own project); any other id is a 403.

        **Use case:** Re-fetch the project row after a `PATCH` when you already hold its id.
      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'
      responses:
        '200':
          description: Show a project by id
          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
        - NOT_FOUND
    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.
      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
                  isDefault: 1
                  createdAt: '2026-04-12T10:14:08.000Z'
                  deletedAt: 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: 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
      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). Defaults to 200.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 200
        - 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 i18n keys (insert-only, or `force` to overwrite)
      description: |-
        Add NEW keys to a profile. Insert-only by default — existing keys are left untouched and reported back as `skipped`.

        Pass `force: true` to overwrite the existing ones in bulk with the submitted values: they come back as `updated` instead of `skipped`. Without `force` the only overwrite paths are `updateI18nKey` (one key) and the devtools-only `upsertI18nKeys`.

        **Use case:** Seed newly-extracted keys without clobbering translations already in the profile — or re-push a whole source-language file with `force` after the copy changed.
      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 i18n keys (insert-only, or `force` to overwrite)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushI18nKeysResponse'
              example:
                added:
                  - checkout.cta
                skipped: []
                updated: []
                pushed_count: 1
                skipped_count: 0
                updated_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
    put:
      operationId: upsertI18nKeys
      summary: Bulk upsert i18n keys (overwrite)
      description: |-
        Bulk upsert keys into a profile — existing keys ARE overwritten, new ones inserted. The profile's KV snapshot is rebuilt and the CDN purged before the call returns, so the edits go live on their own.

        This is the overwrite counterpart of the insert-only `pushI18nKeys`. It backs the devtools overlay's in-product "Apply changes" label editing and is deliberately not surfaced by the CLI or MCP — those surfaces only expose the insert-only push so a whole `en.json` can't wholesale-overwrite prod.

        **Use case:** Apply a batch of in-product label edits (devtools overlay) in one call.
      tags:
        - Keys
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertI18nKeysRequest'
            example:
              profile_id: 3f1a6c2e-1b2c-4d5e-8f90-0a1b2c3d4e5f
              keys:
                - key: checkout.cta
                  value: Buy it now
      responses:
        '200':
          description: Bulk upsert i18n keys (overwrite)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertI18nKeysResponse'
              example:
                upserted: 1
        '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
  /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
    delete:
      operationId: deleteI18nKey
      summary: Delete one i18n key
      description: |-
        Permanently delete a single key from its profile. The profile's KV snapshot is rebuilt and the CDN purged as part of this call, so the removal goes live on its own.

        **Use case:** Remove a stale or mistakenly-pushed key without touching the rest of the profile.
      tags:
        - Keys
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: id
          in: path
          required: true
          description: The key's id.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Delete one i18n key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OkResponse'
              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
  /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
    delete:
      operationId: deleteI18nDraft
      summary: Delete a translation draft
      description: |-
        Permanently delete a staged translation draft. Its staged keys are removed with it; the target profile's live keys are untouched.

        **Use case:** Discard a draft that will never ship instead of leaving it abandoned.
      tags:
        - Drafts
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: draftId
          in: path
          required: true
          description: The draft id to delete.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Delete a translation draft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OkResponse'
              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
  /api/admin/i18n/profiles/{profileId}:
    delete:
      operationId: deleteI18nProfile
      summary: Delete an i18n profile
      description: |-
        Soft-delete a locale profile. The project's default profile cannot be deleted (409). The profile's keys are retained in the database but the profile no longer resolves for listing or publishing.

        **Use case:** Retire a locale that is no longer shipped.
      tags:
        - Profiles
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: profileId
          in: path
          required: true
          description: The profile id to delete.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: Delete an i18n profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OkResponse'
              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
  /api/admin/i18n/drafts/{draftId}/keys:
    get:
      operationId: listI18nDraftKeys
      summary: List a draft's staged keys
      description: |-
        Returns every staged key in a translation draft — the values queued to ship when the draft is merged.

        **Use case:** Review a machine-translation draft's staged strings before marking it merged.
      tags:
        - Drafts
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: draftId
          in: path
          required: true
          description: The draft id to list staged keys for.
          schema:
            $ref: '#/components/schemas/ResourceId'
      responses:
        '200':
          description: List a draft's staged keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListI18nDraftKeysResponse'
              example:
                - id: dk_01j7
                  draftId: draft_01j7
                  key: checkout.cta
                  value: Achetez maintenant
                  description: null
                  variables: null
                  updatedBy: owner@acme.com
                  updatedAt: '2026-07-01T10: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
    post:
      operationId: upsertI18nDraftKey
      summary: Upsert one staged draft key
      description: |-
        Upsert a single staged key into an **open** draft — inserted when new, overwritten when it already exists. A draft that is `merged` or `abandoned` rejects the write (400). `{{var}}` placeholder names are auto-derived from the value.

        **Use case:** Stage or correct one translation in a draft under review without touching the live profile.
      tags:
        - Drafts
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: draftId
          in: path
          required: true
          description: The draft id to stage the key into.
          schema:
            $ref: '#/components/schemas/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertI18nDraftKeyRequest'
            example:
              key: checkout.cta
              value: Achetez maintenant
      responses:
        '201':
          description: Upsert one staged draft key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OkResponse'
              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
  /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 body takes no options.

        **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: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishI18nProfileRequest'
            example: {}
      responses:
        '200':
          description: Publish a profile
          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'
                  assigneeId: null
                  assigneeConnectorId: null
                  assigneeAgent: 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
  /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, plus `occurrences` — the sampled per-instance detail rows behind the issue (newest first; exhaustive while the issue is small, thinned at volume, capped at 100). 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 walk `occurrences` to see how the failing message/stack varies across instances.
      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'
                assigneeId: 6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c
                assigneeConnectorId: null
                assigneeAgent: null
                occurrences:
                  - id: occ_01j7w7qq0v3k9d2m5rc8t1xh4n
                    projectId: e976b15e-2f0d-4c6e-9b1a-3a7c1f2d8e90
                    errorId: err_01j7w7m9q4hxbf6npe6s9zr3vc
                    message: Cannot read properties of undefined (reading 'id')
                    stack: |-
                      TypeError: Cannot read properties of undefined (reading 'id')
                          at GateEditor (/app/gates/[id]/page.tsx:42:18)
                    url: https://app.example.com/dashboard/gat_01j7/edit
                    env: prod
                    side: client
                    sdkVersion: 6.0.0
                    extrasJson: '{"gateId":"gat_01j7"}'
                    sampleRate: 100
                    seenAt: '2026-06-28T14:55:31.000Z'
                  - id: occ_01j7w7pk8s6e3f9b0zad7y5w2q
                    projectId: e976b15e-2f0d-4c6e-9b1a-3a7c1f2d8e90
                    errorId: err_01j7w7m9q4hxbf6npe6s9zr3vc
                    message: Cannot read properties of undefined (reading 'id')
                    stack: |-
                      TypeError: Cannot read properties of undefined (reading 'id')
                          at GateEditor (/app/gates/[id]/page.tsx:42:18)
                    url: https://app.example.com/dashboard/gat_02c4/edit
                    env: prod
                    side: client
                    sdkVersion: 6.0.0
                    extrasJson: '{"gateId":"gat_02c4"}'
                    sampleRate: 10
                    seenAt: '2026-06-24T09:12:05.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'
                assigneeId: null
                assigneeConnectorId: null
                assigneeAgent: 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
        - 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}/resolve:
    post:
      operationId: resolveError
      summary: Resolve a tracked error
      description: |-
        Marks one tracked error `resolved` — the single-purpose "close out" action. Takes no body; it is `PATCH /api/admin/errors/{id}` pinned to `{ "status": "resolved" }`, exposed so tooling can close an error without being handed the full open/resolved/ignored status machine. A resolved error reopens automatically (ingestion-side) if it recurs, so resolving is always safe: a premature resolve un-does itself on the next occurrence. Returns the updated row; `404` if the error does not exist.

        **Use case:** Close out a tracked error from an agent or script once its fix has shipped — e.g. after a deploy, resolve every open issue the change addressed and let recurrence reopen anything that wasn't actually fixed.
      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: Resolve 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: 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'
                assigneeId: null
                assigneeConnectorId: null
                assigneeAgent: 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
        - NOT_FOUND
      x-cli:
        name: resolve
        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
                    description: Held by the checkout service; rotate with the quarterly credential sweep
                    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}:
    patch:
      operationId: updateKey
      summary: Update an API key's label
      description: |-
        Renames a key or re-notes what it is for. **Only `name` and `description` are editable** — everything that gives the key its authority (`type`, `env`, `scopes`, `expires_at`) is fixed at mint, because the worker derives the read env and permissions from the key itself. To change any of those, rotate: mint a replacement and revoke this one.

        Omitted fields are left untouched; send `null` to clear one. Returns the updated key row. Revoked keys can still be relabelled (the audit trail outlives the credential). Returns `404` if no such key exists in the project.

        **Use case:** A key minted by `shipeasy setup` carries an auto-composed provenance label — rename it to the service that actually holds it and note the rotation owner.
      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'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateKeyRequest'
            examples:
              rename:
                summary: Rename and note the key
                value:
                  name: checkout-service · production
                  description: Held by the checkout service; rotation owner is the payments team
              clearDescription:
                summary: Clear the note
                value:
                  description: null
      responses:
        '200':
          description: Update an API key's label
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyRecord'
              example:
                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: checkout-service · production
                description: Held by the checkout service; rotation owner is the payments team
                scopes:
                  - gates:evaluate
                  - events:write
                last4: a1b2
        '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/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"`.'
    clientSdkKey:
      type: apiKey
      in: header
      name: X-SDK-Key
      description: |-
        Pass a **client** SDK key as `X-SDK-Key: sdk_client_…`. Used only by the public ticket intake (`POST /ops/bug`, `POST /ops/feature-request`), which is served by the edge worker rather than the admin API.

        Client keys are designed to be embedded in shipped code — a CLI, an installer, a browser bundle — so presenting one here is safe by construction: it can do nothing but file a rate-limited ticket into its own project, in a state a human must approve. It carries no read access and cannot reach any other operation in this contract.

        The key must additionally carry the `tickets:public_create` scope, and its project must have public ticket creation enabled.
  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:
    GateApiRow:
      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
                      whitelist:
                        description: Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first "whitelist" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.
                        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.
        creatorEmail:
          description: Resolved email of the user who created the gate (`created_by` → `users.email`), or `null` when the creator is unknown.
          anyOf:
            - type: string
            - type: 'null'
        updaterEmail:
          description: Resolved email of the user who last edited the gate (`updated_by` → `users.email`), or `null` when the last editor is unknown.
          anyOf:
            - type: string
            - type: 'null'
        version:
          type: integer
          minimum: 1
          maximum: 9007199254740991
          description: Monotonic edit counter — starts at 1 on create (D1 `NOT NULL DEFAULT 1`) and increments on every `PATCH /api/admin/gates/{id}`.
        createdAt:
          description: ISO-8601 creation timestamp, or `null` on legacy rows created before the column existed.
          anyOf:
            - type: string
            - type: 'null'
      required:
        - id
        - name
        - enabled
        - rolloutPct
        - updatedAt
        - creatorEmail
        - updaterEmail
        - version
        - createdAt
      additionalProperties: false
      description: The single wire shape for a gate row, shared by `ListGatesResponse` (`data[]` items) and `GET /api/admin/gates/{id}`.
    ListGatesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GateApiRow'
        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
        - AGENT_NOT_CONNECTED
      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.
        AGENT_NOT_CONNECTED: The named AI agent type has no connected trigger connector in this project — list the available agents (`ops agents list` / `GET /api/admin/agent-profiles`) and use one of those, or connect the agent under Settings → Triggers.
    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
                      whitelist:
                        description: Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first "whitelist" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.
                        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
                      whitelist:
                        description: Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first "whitelist" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.
                        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
    ListGateActivityResponse:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
          action:
            type: string
            description: Audit action (e.g. `gate.create`, `gate.update`, `gate.enable`, `gate.disable`, `gate.delete`).
          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 gate, newest first.
    GateWhitelistAttr:
      type: string
      enum:
        - email
        - user_id
      description: Which identity attribute the whitelist matches on. `email` compares the caller's `email`; `user_id` compares the caller's `userID`. A whitelist matches on exactly one of the two at a time.
    GateWhitelist:
      type: object
      properties:
        id:
          type: string
          description: Resolved gate id.
        name:
          type: string
          description: The gate's stable `name`.
        attr:
          $ref: '#/components/schemas/GateWhitelistAttr'
        entries:
          type: array
          items:
            type: string
            minLength: 1
          description: The whitelisted identities, in the order they are stored. Deduplicated case-sensitively; an empty array means the gate has no whitelist.
      required:
        - id
        - name
        - attr
        - entries
      additionalProperties: false
      description: A gate's whitelist — the always-first allowlist that admits the listed identities before any targeting rule or rollout runs. Backed by the pinned `whitelist` entry at the head of the gate's `stack`, so it is the same list the dashboard's Whitelist block edits.
    SetGateWhitelistRequest:
      type: object
      properties:
        attr:
          anyOf:
            - $ref: '#/components/schemas/GateWhitelistAttr'
          description: Identity attribute to match on. Defaults to the whitelist's current attribute, or `email` when the gate has no whitelist yet.
        entries:
          type: array
          items:
            type: string
            minLength: 1
          description: The complete whitelist after the call. Pass `[]` to remove the whitelist from the gate entirely.
      required:
        - entries
      additionalProperties: false
      description: Body for `PUT /api/admin/gates/{id}/whitelist`. Replaces the whole list — idempotent, and the only call that can switch `attr` or clear the whitelist.
    AddToGateWhitelistRequest:
      type: object
      properties:
        attr:
          anyOf:
            - $ref: '#/components/schemas/GateWhitelistAttr'
          description: Identity attribute to match on. Only honoured when the gate has no whitelist yet (this call creates it); passing an attribute that disagrees with an existing whitelist is a 409 rather than a silent re-key of the entries already there.
        entries:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
          description: Identities to admit. Already-listed entries are skipped, so the call is idempotent.
      required:
        - entries
      additionalProperties: false
      description: Body for `POST /api/admin/gates/{id}/whitelist`. Adds entries to the whitelist, creating it if the gate doesn't have one.
    RemoveFromGateWhitelistRequest:
      type: object
      properties:
        entries:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
          description: Identities to stop admitting. Entries that aren't listed are skipped, so the call is idempotent.
      required:
        - entries
      additionalProperties: false
      description: 'Body for `DELETE /api/admin/gates/{id}/whitelist`. Removes entries from the whitelist. Removing the last entry leaves an empty whitelist in place — use `PUT` with `entries: []` to drop the block itself.'
    ExperimentApiRow:
      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).
        hashVersion:
          type: integer
          minimum: 1
          description: Bucketing hash algorithm version for the experiment's pool slice (§B4). Defaults to 1.
        poolOffsetBp:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 10000
            - type: 'null'
          description: Basis-point offset of the experiment's contiguous slice in the universe pool, or `null` before a slice is allocated.
        poolSizeBp:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 10000
            - type: 'null'
          description: Basis-point width of the experiment's pool slice (equal to its allocation), or `null` before a slice is allocated.
        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
        version:
          anyOf:
            - type: integer
            - type: 'null'
          description: Save counter (number of published edits), or `null` on pre-versioning rows.
        creatorEmail:
          anyOf:
            - type: string
            - type: 'null'
          description: 'Resolved creator email (`created_by` → users). Enriched field: present on list rows, omitted from the by-id detail.'
        updaterEmail:
          anyOf:
            - type: string
            - type: 'null'
          description: 'Resolved last-editor email (`updated_by` → users). Enriched field: present on list rows, omitted from the by-id detail.'
        verdict:
          type: string
          enum:
            - ship
            - hold
            - wait
            - invalid
            - draft
          description: 'Answer-first decision from the goal metric + guardrails + SRM vs. the significance threshold and min runtime: `ship`, `hold`, `wait`, `invalid`, `draft`. Enriched field: list rows only.'
        verdictTitle:
          type: string
          description: 'Expanded verdict headline the results hero renders. Enriched field: list rows only.'
        verdictWhy:
          type: string
          description: 'Verdict rationale the results hero renders. Enriched field: list rows only.'
        goalMetric:
          anyOf:
            - type: object
              properties:
                id:
                  type: string
                name:
                  type: string
              required:
                - id
                - name
              additionalProperties: false
            - type: 'null'
          description: 'The experiment''s goal metric `{ id, name }`, or `null` when none is set. Enriched field: list rows only.'
        guardrails:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              eventName:
                anyOf:
                  - type: string
                  - type: 'null'
            required:
              - id
              - name
            additionalProperties: false
          description: 'Guardrail metrics `{ id, name, eventName? }`. Enriched field: list rows only.'
        guardrailCount:
          type: integer
          minimum: 0
          description: 'Number of guardrail metrics. Enriched field: list rows only.'
        primaryLiftPct:
          anyOf:
            - type: number
            - type: 'null'
          description: 'Goal-metric lift of the leading variant vs. control, in percent, or `null` when not yet computed. Enriched field: list rows only.'
        significancePct:
          anyOf:
            - type: number
            - type: 'null'
          description: 'Statistical significance (1 − p) as a percent, or `null` when not yet computed. Enriched field: list rows only.'
        sampleSize:
          anyOf:
            - type: integer
            - type: 'null'
          description: 'Total distinct units analysed, or `null` when not yet computed. Enriched field: list rows only.'
        exposure:
          type: array
          items:
            type: object
            properties:
              ds:
                type: string
              value:
                type: number
            required:
              - ds
              - value
            additionalProperties: false
          description: 'Cumulative unique-users-enrolled series for the exposure sparkline. Enriched field: list rows only.'
        exposureTotal:
          anyOf:
            - type: integer
            - type: 'null'
          description: 'Total distinct units ever exposed (sparkline headline), or `null`. Enriched field: list rows only.'
      required:
        - id
        - name
        - description
        - hypothesis
        - tag
        - ownerEmail
        - audience
        - bucketBy
        - folder
        - status
        - universe
        - targetingGate
        - holdoutGate
        - allocationPct
        - reservedHeadroom
        - hashVersion
        - poolOffsetBp
        - poolSizeBp
        - salt
        - params
        - groups
        - significanceThreshold
        - minRuntimeDays
        - minSampleSize
        - sequentialTesting
        - startedAt
        - stoppedAt
        - updatedAt
        - version
      additionalProperties: false
    ListExperimentsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ExperimentApiRow'
        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_events
            - sum
            - avg
          description: 'Reducer for the `event` form. Defaults to `count_events`. `count_users` was removed: Analytics Engine samples rows and weights the survivors, and a distinct count cannot be reweighted, so it under-reports by the sample interval. `retention_7d` / `retention_30d` were removed on 2026-08-10: the day count reached no query and no reducer, so both produced the same number as a distinct user count and reported it as a returning-user rate.'
        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
    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
    ExperimentResultRow:
      type: object
      description: One persisted analysis row (`experiment_results`) for a single metric/group/day slice. Camel-case wire names; nullable statistics are `null` on control rows, empty arms, or when the analysis pass hasn't produced them.
      properties:
        metric:
          type: string
          description: Metric name this row was computed for.
        groupName:
          type: string
          description: Variant (group) label the row belongs to, e.g. `control` or `treatment`.
        ds:
          type: string
          description: Date slice (`YYYY-MM-DD`).
        'n':
          description: Sample size (exposed units) in this group for the slice, or `null` when unknown.
          anyOf:
            - type: integer
            - type: 'null'
        mean:
          description: Per-unit metric mean in this group, or `null` on empty arms.
          anyOf:
            - type: number
            - type: 'null'
        variance:
          description: Per-unit metric variance in this group, or `null` on empty arms.
          anyOf:
            - type: number
            - type: 'null'
        delta:
          description: Absolute difference vs. control (metric units). `null` on the control row.
          anyOf:
            - type: number
            - type: 'null'
        deltaPct:
          description: Relative difference vs. control, in percent. `null` on the control row.
          anyOf:
            - type: number
            - type: 'null'
        ci95Low:
          description: Lower bound of the 95% confidence interval on `delta`, or `null`. Kept for back-compat — prefer `ciLow`/`ciHigh`.
          anyOf:
            - type: number
            - type: 'null'
        ci95High:
          description: Upper bound of the 95% confidence interval on `delta`, or `null`. Kept for back-compat — prefer `ciLow`/`ciHigh`.
          anyOf:
            - type: number
            - type: 'null'
        ci99Low:
          description: Lower bound of the 99% confidence interval on `delta`, or `null`. Kept for back-compat — prefer `ciLow`/`ciHigh`.
          anyOf:
            - type: number
            - type: 'null'
        ci99High:
          description: Upper bound of the 99% confidence interval on `delta`, or `null`. Kept for back-compat — prefer `ciLow`/`ciHigh`.
          anyOf:
            - type: number
            - type: 'null'
        ciLow:
          description: Lower bound of the confidence interval at the project's configured `ci_confidence` (not always 95%), or `null`. When both `ciLow`/`ciHigh` are `null`, fall back to `ci95Low`/`ci95High` (pre-migration rows).
          anyOf:
            - type: number
            - type: 'null'
        ciHigh:
          description: Upper bound of the confidence interval at the project's configured `ci_confidence` (not always 95%), or `null`. When both `ciLow`/`ciHigh` are `null`, fall back to `ci95Low`/`ci95High` (pre-migration rows).
          anyOf:
            - type: number
            - type: 'null'
        pValue:
          description: Two-sided p-value vs. control, or `null` on the control row / empty arms.
          anyOf:
            - type: number
            - type: 'null'
        expectedN:
          description: Sample size per arm the power calculation expects for a conclusive read, or `null` when not computed.
          anyOf:
            - type: integer
            - type: 'null'
        realizedMde:
          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.
          anyOf:
            - type: number
            - type: 'null'
        srmPValue:
          description: p-value of the sample-ratio-mismatch chi-squared test, or `null` when not computed.
          anyOf:
            - type: number
            - type: 'null'
        srmDetected:
          type: integer
          description: '`1` if sample-ratio mismatch detected, else `0`.'
        msprtSignificant:
          description: 'Sequential (mSPRT) significance flag: `1` significant, `0` not, `null` when sequential testing is off or not computed.'
          anyOf:
            - type: integer
            - type: 'null'
        msprtLambda:
          description: mSPRT mixture likelihood-ratio statistic, or `null` when sequential testing is off or not computed.
          anyOf:
            - type: number
            - type: 'null'
        isFinal:
          type: integer
          description: '`1` when this row belongs to the final analysis pass after the experiment stopped, else `0`.'
        peekWarning:
          type: integer
          description: '`1` when the row was read before `min_runtime_days`/`min_sample_size` were met (peeking inflates false positives), else `0`.'
      required:
        - metric
        - groupName
        - ds
        - 'n'
        - mean
        - variance
        - delta
        - deltaPct
        - ci95Low
        - ci95High
        - ci99Low
        - ci99High
        - ciLow
        - ciHigh
        - pValue
        - expectedN
        - realizedMde
        - srmPValue
        - srmDetected
        - msprtSignificant
        - msprtLambda
        - isFinal
        - peekWarning
      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:
            $ref: '#/components/schemas/ExperimentResultRow'
          description: One analysis row per metric/group/day — the persisted `experiment_results` rows for this experiment.
        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:
            $ref: '#/components/schemas/ExperimentResultRow'
          description: Every daily analysis slice (same row shape as `/results`), oldest to newest.
      required:
        - experiment
        - series
      additionalProperties: false
    ReanalyzeExperimentResponse:
      type: object
      properties:
        id:
          type: string
        queued:
          type: boolean
          description: '`true` when the analysis job was enqueued; `false` when the worker enqueue failed or the analysis queue is not configured (retry later).'
      required:
        - id
        - queued
      additionalProperties: false
    CreateExperimentReadoutRequest:
      type: object
      description: Body for `POST /api/admin/experiments/{id}/readouts`. Mints an immutable, dated readout snapshot of the current results view — "this is what we saw when we decided".
      properties:
        kind:
          type: string
          enum:
            - manual
            - ship
            - stop
          description: Why the snapshot is being minted — `manual` ("Share readout"), or automatically on `ship` / `stop`.
        acknowledgedCaveatIds:
          type: array
          items:
            type: string
            description: Caveat id, as surfaced in the results view's caveat list.
          description: Ids of the open caveats the caller ticked (decision-gating acknowledgment). Unlisted caveats are stored as unacknowledged.
        requireAllAcknowledged:
          type: boolean
          description: When `true`, refuse (`422`) to mint while any open caveat is not listed in `acknowledgedCaveatIds` — server-side ship gating.
      required:
        - kind
      additionalProperties: false
    CreateExperimentReadoutResponse:
      type: object
      properties:
        id:
          type: string
          description: Id of the newly minted readout snapshot.
      required:
        - id
      additionalProperties: false
    ExperimentReadoutMetric:
      type: object
      description: Frozen per-metric numbers as rendered at mint time. Display-shaped, not row-shaped — the snapshot keeps rendering exactly what was decided on even if derivations change later.
      properties:
        name:
          type: string
          description: Metric name.
        role:
          type: string
          enum:
            - goal
            - guardrail
            - secondary
          description: Metric role at mint time. `goal` drives the decision, `guardrail` blocks ship if degraded, `secondary` is informational.
        delta:
          description: Absolute difference vs. control (metric units), or `null`.
          anyOf:
            - type: number
            - type: 'null'
        deltaPct:
          description: Relative difference vs. control in percent, or `null`.
          anyOf:
            - type: number
            - type: 'null'
        ci:
          description: Two-item `[low, high]` confidence interval on the delta at the project's configured confidence, or `null`.
          anyOf:
            - type: array
              items:
                type: number
              minItems: 2
              maxItems: 2
            - type: 'null'
        p:
          description: p-value vs. control, or `null`.
          anyOf:
            - type: number
            - type: 'null'
        sig:
          type: boolean
          description: Whether the metric was statistically significant at mint time.
        pass:
          type: boolean
          description: Guardrail pass/fail at mint time. Omitted for metrics where pass/fail doesn't apply.
      required:
        - name
        - role
        - delta
        - deltaPct
        - ci
        - p
        - sig
      additionalProperties: false
    ExperimentReadoutCaveat:
      type: object
      description: One caveat from the results view, frozen with its acknowledgment state at mint time.
      properties:
        id:
          type: string
          description: Stable caveat id.
        severity:
          type: string
          enum:
            - info
            - warn
            - danger
          description: Caveat severity as rendered in the results view.
        text:
          type: string
          description: Human-readable caveat text.
        acknowledged:
          type: boolean
          description: Whether the caller ticked this caveat when minting (decision-gating acknowledgment).
      required:
        - id
        - severity
        - text
        - acknowledged
      additionalProperties: false
    ExperimentReadoutApiRow:
      type: object
      description: An immutable, dated readout snapshot — the frozen results view captured when a decision was made. Never updated after insert.
      properties:
        id:
          type: string
          description: Stable readout id.
        experimentId:
          type: string
          description: Id of the experiment the snapshot belongs to.
        experimentName:
          type: string
          description: Experiment name at mint time (denormalised — survives renames).
        kind:
          type: string
          enum:
            - manual
            - ship
            - stop
          description: Why the snapshot was minted — `manual` ("Share readout"), or automatically on `ship` / `stop`.
        createdBy:
          type: string
          description: Email of the actor who minted the snapshot.
        createdAt:
          type: string
          description: ISO-8601 mint timestamp.
        verdict:
          type: string
          description: Server-computed verdict at mint time (e.g. `ship`, `hold`, `wait`, `invalid`).
        title:
          type: string
          description: Headline of the results view at mint time.
        why:
          type: string
          description: One-line explanation backing the verdict at mint time.
        configHash:
          type: string
          description: sha-256 hex over the assignment-relevant config (salt, groups, allocation, universe, gate) — the snapshot is only comparable to the live view while this hash still matches.
        metricsJson:
          description: Frozen per-metric numbers as rendered at mint time, or `null` for legacy rows without a metrics slice.
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/ExperimentReadoutMetric'
            - type: 'null'
        caveatsJson:
          description: The caveat list with its acknowledgment state at mint time, or `null` for legacy rows without one.
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/ExperimentReadoutCaveat'
            - type: 'null'
        usersJson:
          description: Enrollment at mint time — per-group sample sizes plus the number of days the experiment had been running — or `null` when not captured.
          anyOf:
            - type: object
              properties:
                groups:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: Group label.
                      'n':
                        type: number
                        description: Enrolled units in the group at mint time.
                    required:
                      - name
                      - 'n'
                    additionalProperties: false
                    description: One group's enrollment at mint time.
                  description: Per-group enrollment counts.
                days:
                  type: number
                  description: Days the experiment had been running at mint time.
              required:
                - groups
                - days
              additionalProperties: false
            - type: 'null'
      required:
        - id
        - experimentId
        - experimentName
        - kind
        - createdBy
        - createdAt
        - verdict
        - title
        - why
        - configHash
        - metricsJson
        - caveatsJson
        - usersJson
      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'
              folder:
                description: Folder segment used for dashboard organisation, or `null` when the config lives at the root.
                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.
              creatorEmail:
                description: Resolved email of the creator (`created_by` → `users.email`), or `null` when unknown. List-only enrichment — present on `GET /api/admin/configs` rows, absent from the by-id detail — so it is optional, never required.
                anyOf:
                  - type: string
                  - type: 'null'
              createdAt:
                description: ISO-8601 creation timestamp, or `null` on legacy rows. List-only enrichment — present on `GET /api/admin/configs` rows, absent from the by-id detail — so it is optional, never required.
                anyOf:
                  - type: string
                  - type: 'null'
              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
              - folder
              - 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:
          type: object
          additionalProperties: {}
          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.'
        dev:
          type: object
          additionalProperties: {}
          description: Seed the **dev** env's initial value (version 1), overriding `value` for dev. Published immediately. Must match `schema`.
        staging:
          type: object
          additionalProperties: {}
          description: Seed the **staging** env's initial value (version 1), overriding `value` for staging. Published immediately. Must match `schema`.
        prod:
          type: object
          additionalProperties: {}
          description: Seed the **prod** env's initial value (version 1), overriding `value` for prod. Published immediately. Must match `schema`.
      required:
        - name
        - schema
      additionalProperties: false
      description: Body for `POST /api/admin/configs`. `name` + `schema` required. Per-env `dev`/`staging`/`prod` values are published to that env at version 1 (overriding `value`).
    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'
        folder:
          description: Folder segment used for dashboard organisation, or `null` when the config lives at the root.
          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.
        creatorEmail:
          description: Resolved email of the creator (`created_by` → `users.email`), or `null` when unknown. List-only enrichment — present on `GET /api/admin/configs` rows, absent from this by-id detail — so it is optional, never required.
          anyOf:
            - type: string
            - type: 'null'
        createdAt:
          description: ISO-8601 creation timestamp, or `null` on legacy rows. List-only enrichment — present on `GET /api/admin/configs` rows, absent from this by-id detail — so it is optional, never required.
          anyOf:
            - type: string
            - type: 'null'
        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
        - folder
        - 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:
          type: object
          additionalProperties: {}
          description: Flat value applied to **every** env. Publishes a new version per env. To publish one env only, pass that env's key (`dev`/`staging`/`prod`) instead.
        dev:
          type: object
          additionalProperties: {}
          description: Publish a new version to the **dev** env only, immediately (no draft). Overrides `value` for dev. Must match the effective schema.
        staging:
          type: object
          additionalProperties: {}
          description: Publish a new version to the **staging** env only, immediately (no draft). Overrides `value` for staging. Must match the effective schema.
        prod:
          type: object
          additionalProperties: {}
          description: Publish a new version to the **prod** env only, immediately (no draft). Overrides `value` for prod. Must match the effective schema.
        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; per-env `dev`/`staging`/`prod` publish a new version to just that 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:
          type: object
          additionalProperties: {}
          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
    ListConfigVersionsResponse:
      type: array
      items:
        type: object
        properties:
          version:
            type: integer
            minimum: 1
            maximum: 9007199254740991
            description: Published version number on the requested env (monotonically increasing per env).
          value:
            description: The full JSON value that was published at this version.
          publishedAt:
            type: string
            description: ISO-8601 publish timestamp.
          publishedBy:
            type: string
            description: Email/id of the actor who published this version.
        required:
          - version
          - value
          - publishedAt
          - publishedBy
        additionalProperties: false
        description: One published version of the config's value on the requested env.
      description: Full published-value history for one (config, env), newest first. The config's schema is config-level and not versioned — this is value history only.
    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`.
              folder:
                description: Folder segment used for dashboard organisation, or `null` when the killswitch lives at the root.
                anyOf:
                  - type: string
                  - type: 'null'
              creatorEmail:
                description: Resolved email of the creator (`created_by` → `users.email`), or `null` when unknown.
                anyOf:
                  - type: string
                  - type: 'null'
              createdAt:
                description: ISO-8601 creation timestamp, or `null` on legacy rows created before the column existed.
                anyOf:
                  - type: string
                  - type: '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
              - folder
              - creatorEmail
              - createdAt
              - 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`.
        folder:
          description: Folder segment used for dashboard organisation, or `null` when the killswitch lives at the root.
          anyOf:
            - type: string
            - type: 'null'
        creatorEmail:
          description: Resolved email of the creator (`created_by` → `users.email`), or `null` when unknown.
          anyOf:
            - type: string
            - type: 'null'
        createdAt:
          description: ISO-8601 creation timestamp, or `null` on legacy rows created before the column existed.
          anyOf:
            - type: string
            - type: '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
        - folder
        - creatorEmail
        - createdAt
        - 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
    ToggleKillswitchRequest:
      type: object
      properties:
        switchKey:
          anyOf:
            - type: string
              maxLength: 64
              pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$
            - type: 'null'
          description: Which target to flip. Omit (or `null`) to flip the killswitch's own flat `value`; name a switch key to flip that nested sub-switch instead, creating the entry if it doesn't exist yet.
        value:
          anyOf:
            - type: boolean
            - type: 'null'
          description: The value to publish. Omit (or `null`) to flip whatever is stored now — read-modify-write in one call. Pass an explicit `true`/`false` to make the call idempotent, so a retry can't undo the first attempt.
        env:
          anyOf:
            - $ref: '#/components/schemas/Env'
          description: Environment to publish on. Defaults to `prod` — the environment an incident response means when it says "kill it".
      additionalProperties: false
      description: |-
        Body for `POST /api/admin/killswitches/{id}/toggle`. Every field is optional, so the four useful calls read as one method with a widening argument list:

        - `{}` — flip the flat value on prod.
        - `{ "switchKey": "eu_region" }` — flip that sub-switch on prod.
        - `{ "switchKey": "eu_region", "value": true }` — set that sub-switch on prod, idempotently.
        - `{ "switchKey": "eu_region", "value": true, "env": "staging" }` — the same, on a chosen env.
    ToggleKillswitchResponse:
      type: object
      properties:
        id:
          type: string
          description: Resolved killswitch id.
        env:
          $ref: '#/components/schemas/Env'
        switchKey:
          anyOf:
            - type: string
              maxLength: 64
              pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$
            - type: 'null'
          description: The sub-switch that was flipped, or `null` when the flat `value` was.
        previous:
          type: boolean
          description: The value that was in effect before this call. Equal to `value` when an idempotent `value` matched what was already stored.
        value:
          type: boolean
          description: The value now in effect on `env`.
        version:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Newly published version on `env`.
        published:
          $ref: '#/components/schemas/KillswitchValue'
      required:
        - id
        - env
        - switchKey
        - previous
        - value
        - 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
    AttributeType:
      type: string
      enum:
        - string
        - number
        - boolean
        - enum
        - date
      description: Declared value type of a targeting attribute.
    ListAttributesResponse:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            description: Stable opaque attribute id.
          name:
            type: string
            description: Attribute key as seen in evaluation context (e.g. `plan`, `country`).
          type:
            $ref: '#/components/schemas/AttributeType'
          enumValues:
            description: Allowed values for `enum` attributes, else `null`.
            anyOf:
              - type: array
                items:
                  type: string
              - type: 'null'
          required:
            type: integer
            enum:
              - 0
              - 1
            description: Whether the attribute must be present on the evaluation context (D1 stores the flag as `0`/`1`).
          description:
            description: Human note shown in the dashboard, or `null`.
            anyOf:
              - type: string
              - type: 'null'
          sdkPath:
            description: Dotted path the SDK reads the value from, or `null`.
            anyOf:
              - type: string
              - type: 'null'
          createdAt:
            type: string
            description: ISO-8601 creation timestamp.
          source:
            type: string
            enum:
              - auto
              - manual
            description: How the attribute came to exist — `auto` (inferred by the `/sdk/evaluate` sampler) or `manual` (declared via the UI/API).
          lastSeenAt:
            description: ISO-8601 timestamp of the most recent SDK sample that carried this attribute, or `null` when never sampled.
            anyOf:
              - type: string
              - type: 'null'
          deprecated:
            type: integer
            enum:
              - 0
              - 1
            description: '`1` when an auto-discovered attribute has stopped appearing in samples. Deprecated attributes stay listed; pickers may hide or de-rank them.'
        required:
          - id
          - name
          - type
        additionalProperties: {}
        description: One declared or auto-inferred targeting attribute row.
      description: Every targeting attribute in the project (declared and auto-inferred).
    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}`.
    MetricDisplayConfig:
      description: How the metric's series is DRAWN, as opposed to what it measures. Both parts used to be DSL functions (`expected(q, seasonal)`, `forecast(q, …)`), which meant turning a band on minted a different metric; they are properties now, so every chart of the metric picks them up and nothing that JUDGES the metric — an alert rule, the experiment analyzer — reads them at all.
      type: object
      properties:
        band:
          description: Shade the seasonal baseline around the series. The fit is the median of this hour of the week over the four weeks before the window, and it is the SAME fit an `anomaly` alert rule fires on — so the shaded region is exactly where such a rule would stay quiet, whether or not one exists.
          type: object
          properties:
            method:
              type: string
              enum:
                - seasonal
            sigma:
              type: number
              exclusiveMinimum: 0
              description: Half-width of the band in sigma-equivalents. Omit for 3, the sigma an alert rule also defaults to.
          required:
            - method
          additionalProperties: false
        forecast:
          description: Project the series past the end of the window. Projected buckets are marked, so a chart can draw an estimate differently from a measurement.
          type: object
          properties:
            method:
              type: string
              enum:
                - linear
                - seasonal
              description: '`linear` continues a least-squares slope over the window it is already reading. `seasonal` de-seasonalises against the four weeks before the window, fits the trend on the remainder and adds the hour-of-week term back — ask for it when the metric has a shape.'
            horizon:
              type: integer
              minimum: 1
              maximum: 500
              description: Buckets to project. Omit for a quarter of the window, which is the same claim at every bucket width.
          required:
            - method
          additionalProperties: false
      additionalProperties: false
    QueryIr:
      description: |-
        A metric definition as a typed expression tree — the structured alternative to the `query` DSL string, and what the API stores. Exactly one of `query` / `query_ir` is supplied per metric body; `query` is the same definition written as text, and is the spelling to prefer.
        Until 2026-08-10 this documented a single aggregation (`{agg, metric, filters}`, with `ratio` as a special case). That shape no longer exists — stored metrics were migrated and the code that read it was deleted — so a body sending it is rejected. Send the `query` string instead, or the tree below.
      type: object
      properties:
        v:
          type: integer
          const: 2
          description: Storage version of the definition. `2` is the only one.
        expr:
          type: object
          additionalProperties: true
          description: |-
            The expression tree: aggregate leaves (`{node: "agg", event, agg, filters, valueLabel?}`), arithmetic over them (`{node: "binary", op, left, right}`), scalars, and function calls (`{node: "call", fn, arg, params?}`). A ratio is ordinary division of two leaves.
            Deliberately opaque here rather than mirrored node by node: the grammar belongs to the query language, a second copy of it in this spec would drift from the one the server enforces, and the server validates every tree by planning it before the metric saves. `GET /api/admin/metrics` returns the grammar itself; the `query` string is the same tree in the form humans and the CLI write.
        groupBy:
          type: object
          properties:
            op:
              type: string
              enum:
                - by
                - without
              description: '`by` names the output dimensions; `without` names the ones to drop.'
            labels:
              type: array
              maxItems: 8
              items:
                type: string
                pattern: ^[a-z_][a-z0-9_]{0,63}$
                description: Event property / label identifier.
              description: Labels the grouping names.
          required:
            - op
            - labels
          additionalProperties: false
          description: How the series is split. On the envelope rather than in `expr` because every leaf of one expression shares it.
        display:
          $ref: '#/components/schemas/MetricDisplayConfig'
      required:
        - v
        - expr
      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:
            description: Typed query IR, or `null` for a metric whose IR was never populated (re-save it to backfill).
            anyOf:
              - $ref: '#/components/schemas/QueryIr'
              - type: 'null'
          displayName:
            description: Human-friendly display name shown in the dashboard, or `null` to fall back to `name`.
            anyOf:
              - type: string
              - type: 'null'
          presetId:
            description: Id of the metric preset this metric was created from, or `null` for a custom metric.
            anyOf:
              - type: string
              - type: 'null'
          unit:
            description: Display unit (e.g. `ms`, `%`, `$`), or `null` when unitless.
            anyOf:
              - type: string
              - type: 'null'
          version:
            type: integer
            description: Monotonic save counter — incremented on every update.
          deletedAt:
            description: ISO-8601 soft-delete (archive) timestamp, or `null` while the metric is live.
            anyOf:
              - type: string
              - type: 'null'
          creatorEmail:
            description: Email of the user who created the metric, or `null` when unknown. List responses only.
            anyOf:
              - type: string
              - type: 'null'
          updaterEmail:
            description: Email of the user who last edited the metric, or `null` when unknown. List responses only.
            anyOf:
              - type: string
              - type: 'null'
          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, or `null` on legacy rows created before the column existed.
            anyOf:
              - type: string
              - type: 'null'
          updatedAt:
            description: ISO-8601 last-update timestamp.
            type: string
        required:
          - id
          - name
          - folder
          - eventName
          - query
          - queryIr
          - version
          - displayName
          - presetId
          - unit
          - deletedAt
        additionalProperties: {}
        description: A metric definition.
      description: Every metric in the project (the list endpoint is not paginated).
    MetricDisplayName:
      description: 'What a human calls the metric — "Checkout revenue" beside the `checkout.revenue` that identifies it. Unlike `name` it is free text, it is editable, and nothing addresses the metric by it: the dashboard leads with it and falls back to `name` when it is absent, so a metric nobody named simply reads as its key. Send `null` to clear it.'
      maxLength: 200
      anyOf:
        - type: string
        - type: 'null'
    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).
    MetricDisplayUnit:
      description: Display unit (e.g. `ms`, `%`, `$`), or `null` when unitless.
      anyOf:
        - type: string
        - type: 'null'
    CreateMetricWithQuery:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/MetricName'
        display_name:
          $ref: '#/components/schemas/MetricDisplayName'
        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'
        unit:
          $ref: '#/components/schemas/MetricDisplayUnit'
        display:
          $ref: '#/components/schemas/MetricDisplayConfig'
      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'
        display_name:
          $ref: '#/components/schemas/MetricDisplayName'
        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'
        unit:
          $ref: '#/components/schemas/MetricDisplayUnit'
        display:
          $ref: '#/components/schemas/MetricDisplayConfig'
      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:
          description: Typed query IR, or `null` for a metric whose IR was never populated (re-save it to backfill).
          anyOf:
            - $ref: '#/components/schemas/QueryIr'
            - type: 'null'
        displayName:
          description: Human-friendly display name shown in the dashboard, or `null` to fall back to `name`.
          anyOf:
            - type: string
            - type: 'null'
        presetId:
          description: Id of the metric preset this metric was created from, or `null` for a custom metric.
          anyOf:
            - type: string
            - type: 'null'
        unit:
          description: Display unit (e.g. `ms`, `%`, `$`), or `null` when unitless.
          anyOf:
            - type: string
            - type: 'null'
        version:
          type: integer
          description: Monotonic save counter — incremented on every update.
        deletedAt:
          description: ISO-8601 soft-delete (archive) timestamp, or `null` while the metric is live.
          anyOf:
            - type: string
            - type: 'null'
        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, or `null` on legacy rows created before the column existed.
          anyOf:
            - type: string
            - type: 'null'
        updatedAt:
          description: ISO-8601 last-update timestamp.
          type: string
      required:
        - id
        - name
        - folder
        - eventName
        - query
        - queryIr
        - version
        - displayName
        - presetId
        - unit
        - deletedAt
      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:
        display_name:
          $ref: '#/components/schemas/MetricDisplayName'
        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'
        unit:
          $ref: '#/components/schemas/MetricDisplayUnit'
        display:
          $ref: '#/components/schemas/MetricDisplayConfig'
      required:
        - query
      additionalProperties: false
      description: Update-metric variant that replaces the query with a `query` DSL string.
    UpdateMetricWithQueryIr:
      type: object
      properties:
        display_name:
          $ref: '#/components/schemas/MetricDisplayName'
        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'
        unit:
          $ref: '#/components/schemas/MetricDisplayUnit'
        display:
          $ref: '#/components/schemas/MetricDisplayConfig'
      required:
        - query_ir
      additionalProperties: false
      description: Update-metric variant that replaces the query with a typed `query_ir`.
    UpdateMetricFields:
      type: object
      properties:
        display_name:
          $ref: '#/components/schemas/MetricDisplayName'
        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'
        unit:
          $ref: '#/components/schemas/MetricDisplayUnit'
        display:
          $ref: '#/components/schemas/MetricDisplayConfig'
      additionalProperties: false
      description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction, display unit, band and projection).
    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.
    ListMetricExperimentsResponse:
      type: object
      description: Experiments that attach this metric, ordered with running experiments first, then by role weight (goal > guardrail > secondary), then by name.
      properties:
        experiments:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Stable opaque experiment id.
              name:
                type: string
                description: Experiment name.
              status:
                type: string
                enum:
                  - draft
                  - running
                  - stopped
                  - archived
                description: Experiment lifecycle status.
              role:
                type: string
                enum:
                  - goal
                  - guardrail
                  - secondary
                description: Role this metric plays in the experiment. `goal` drives the decision, `guardrail` blocks ship if degraded, `secondary` is informational.
            required:
              - id
              - name
              - status
              - role
            additionalProperties: false
            description: One experiment attaching this metric.
          description: Every experiment (any status) attaching this metric.
      required:
        - experiments
      additionalProperties: false
    UnarchiveMetricResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
      required:
        - ok
      additionalProperties: false
      description: Unarchive (undo soft-delete) acknowledgement.
    GetMetricSeriesRequest:
      type: object
      description: Time window for the metric series. Bounds are epoch **seconds** (Analytics Engine stores the event 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
    GetMetricSeriesResponse:
      type: object
      description: Bucketed values for one metric, compiled from its typed IR and executed against the Analytics Engine SQL API, plus the SQL that produced them. Capped at 5000 rows (high-cardinality `groupBy` series are truncated).
      properties:
        sql:
          type: string
          description: The Analytics Engine SQL executed to produce `rows` (echoed for transparency / debugging).
        rows:
          type: array
          description: Bucketed series, ordered by `t` ascending. For a metric with a `groupBy` clause each bucket has one row per label combination, with the label values as extra string/number properties on the row.
          items:
            type: object
            properties:
              t:
                type: integer
                description: Bucket start, epoch seconds, floor-aligned to `bucket`.
              v:
                type: number
                description: Aggregated metric value in the bucket (sample-interval weighted).
              lo:
                type: number
                description: |
                  Lower edge of the seasonal band — what this hour of the week normally holds, `sigma` below the median of the four weeks before the window. Present only for a metric whose `display.band` is on, and always alongside `hi`.
              hi:
                type: number
                description: |
                  Upper edge of the seasonal band. Present only for a metric whose `display.band` is on, and always alongside `lo`. A point outside `[lo, hi]` is exactly a bucket an `anomaly` alert rule at the same sigma would breach on — the band a chart draws and the condition a rule fires on come from one fit.
            required:
              - t
              - v
            additionalProperties: true
      required:
        - sql
        - rows
      additionalProperties: false
    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
                  pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
                  description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
                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
                pending:
                  description: '`true` when this property was DISCOVERED in live traffic rather than declared. Nothing is recorded for it yet — a property is written to Analytics Engine only once it owns a column, and a column is allocated when an admin declares the property (include it in a `PATCH .../events/{id}` body). Approval is a gate rather than a formality: columns are finite and permanently reserved, so auto-allocating them from customer payload keys would exhaust an event''s schema irreversibly.'
                  type: boolean
              required:
                - name
                - type
              additionalProperties: false
              description: One typed property on a catalogued event — declared by an admin, or discovered in traffic and awaiting declaration.
            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,49}$
          description: Event name. Starts with a letter, digit, or `_`; letters, digits, `_`, `-`, `.`; max 50 characters. The cap is the Analytics Engine index budget — 96 bytes total, less a 36-byte project UUID and a separator — and the API has always enforced 50 while this spec advertised 128. The charset is ASCII, so characters and bytes are the same count. 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
                pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
                description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
              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
                pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
                description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
              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
              pending:
                description: '`true` when this property was DISCOVERED in live traffic rather than declared. Nothing is recorded for it yet — a property is written to Analytics Engine only once it owns a column, and a column is allocated when an admin declares the property (include it in a `PATCH .../events/{id}` body). Approval is a gate rather than a formality: columns are finite and permanently reserved, so auto-allocating them from customer payload keys would exhaust an event''s schema irreversibly.'
                type: boolean
            required:
              - name
              - type
            additionalProperties: false
            description: One typed property on a catalogued event — declared by an admin, or discovered in traffic and awaiting declaration.
          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
                pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
                description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
              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
                pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
                description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
              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
        - investigating_by_ai
        - in_progress
        - blocked
        - ready_for_qa
        - resolved
        - wont_fix
      description: 'Lifecycle status of a queue item. The working flow is `open` → `in_progress` → `ready_for_qa` → `resolved` (or `wont_fix`, terminal from any earlier stage). `blocked` marks an item that can''t progress until an external dependency clears — a working state a human sets and clears. `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. `investigating_by_ai` is a system-owned display state — set when the AI agent (Jarvis) picks an item up to investigate, never chosen by a human — so it is shown but not offered as a manual choice. `pending_approval` is the one human-gated holding state: it parks an item OUT of the work queue until a human promotes it to `open` in the dashboard, so `GET /api/admin/ops` excludes it under `status=all`/default and returns it only when requested as an exact `status`. It covers untriaged inbound that must never be auto-implemented — connector requests filed from a customer''s connectors panel, and questions funnelled in from the "Stuck in onboarding?" assistant — where approving means flipping the status to `open`. Two earlier values were removed in favour of this single gate: `triage` (the onboarding-help bucket, now `pending_approval`) and `triaged` (a redundant "looked at but not started" step, now plain `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.
    OpsInvestigationState:
      type: string
      enum:
        - pr_ready
        - pr_merged
        - pr_closed
        - investigated
        - detected
        - question
        - ready_for_qa
        - pending_approval
        - working
        - backlog
      description: 'Where automation has taken an item in the investigation lifecycle — the signal the ops cockpit renders as "what AI did" plus the one action expected of the user. It is **written as a side-effect of the actions that already happen**, never authored on its own: linking a PR sets `pr_ready`, moving to `in_progress` sets `working`, `ready_for_qa` sets `ready_for_qa`, a system/assistant reply sets `question`, resolving clears it, and creation seeds `backlog` or `investigated`/`detected` for auto-filed error/alert tickets. `backlog` is the single "nothing has happened yet" state — how urgent that is reads off `priority`, not off a separate state, and its one action is to hand the item to an agent. `pr_merged` and `pr_closed` are written by the GitHub `pull_request` webhook when the linked PR reaches a terminal outcome — merged (the fix shipped, resolve the item) or closed without merging (the fix was rejected, decide what happens next). Absent on rows filed before the field existed — consumers should treat a missing value as "derive from the other fields".'
    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
            - killswitch_armed
            - experiment_srm
            - experiment_peek
            - guardrail
          description: What kind of condition opened this alert instance.
        dedupeKey:
          type: string
          description: Stable per-condition key; with `source` forms the ticket's `sourceRef`.
        detail:
          anyOf:
            - type: string
            - type: 'null'
          description: The instance's one-line reading — the observed condition in words.
        ruleId:
          anyOf:
            - type: string
            - type: 'null'
          description: Id of the alert rule that opened this instance, or `null` for a built-in condition.
        severity:
          type: string
          enum:
            - danger
            - warn
            - info
          description: How loud the alert is. Severity belongs to the RULE and is carried by this ticket as `priority`; it is DERIVED from that on the hydrated single-item read, and absent from the raw stored context list rows return.
        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: Firing state of this instance, projected from the ticket's own status (`active` while it is open, i.e. while the condition holds). Absent from the raw stored context list rows return.
        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
      additionalProperties: {}
      description: Detail for an `alert` ticket — the fired-alert INSTANCE this ticket is. List rows carry the stored capture subset (`source`, `dedupeKey`, `ruleId`, `detail`, `href`, `observedValue`); the single-item read hydrates the rest, resolving `severity`/`status` off the ticket itself and 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'
        errorChart:
          type: object
          properties:
            series:
              type: array
              items:
                type: object
                properties:
                  t:
                    type: number
                    description: Bucket start — unix epoch **milliseconds**. Bucket width scales with the window (hourly up to ~5 days, coarser beyond).
                  v:
                    type: number
                    description: Occurrence count in the bucket (sample-rate weighted).
                required:
                  - t
                  - v
                additionalProperties: {}
                description: One occurrence bucket.
              description: Occurrence buckets, oldest first. Buckets with no occurrences are omitted.
            domainFrom:
              type: number
              description: Chart domain start — unix epoch milliseconds (the window's start).
            domainTo:
              type: number
              description: Chart domain end — unix epoch milliseconds (the read time).
          required:
            - series
            - domainFrom
            - domainTo
          additionalProperties: {}
          description: 'Occurrence timeline for an `error` ticket — buckets over the project''s error auto-close window (Settings → Errors: `errorAutocloseDays`, 7 days when auto-close is off, capped at 30) from the sampled occurrences, hydrated at read time by the single-item read only. Plotting exactly the quiet window that auto-resolves the error is what makes an empty right-hand edge meaningful. ABSENT (not `null`) on non-error tickets, on list rows (raw context), and when no occurrence landed in the window.'
      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.
    GithubPrLink:
      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.
        owner:
          type: string
          description: Repository owner (org or user) the pull request lives in. Absent on links recorded before the field existed — `url` still carries it.
        repo:
          type: string
          description: Repository name the pull request lives in. Absent on links recorded before the field existed — `url` still carries it.
        state:
          type: string
          enum:
            - open
            - merged
            - closed
          description: Outcome of the pull request on GitHub, kept current by the `pull_request` webhook. `merged` and `closed` (closed WITHOUT merging, i.e. rejected) are terminal. Absent means the outcome has never been observed — treat it as `open`.
        mergedAt:
          type: string
          description: ISO-8601 timestamp the pull request merged, when `state` is `merged`.
        closedAt:
          type: string
          description: ISO-8601 timestamp the pull request closed unmerged, when `state` is `closed`.
      required:
        - number
        - url
      additionalProperties: {}
      description: The pull request linked to a queue item via `link-pr` (stored on `connectorData.github.pr`).
    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:
          $ref: '#/components/schemas/GithubPrLink'
      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.
    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.
    OpsItemOwner:
      type: object
      properties:
        user:
          anyOf:
            - type: object
              properties:
                id:
                  type: string
                  description: The `users.id` of the assigned person (what `assigneeId` stores).
                email:
                  type: string
                  description: The person's email.
                name:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: The person's display name, or `null` when none is set.
              required:
                - id
                - email
                - name
              additionalProperties: false
              description: The resolved person owner.
            - type: 'null'
          description: The PERSON half of the owner (resolved from `assigneeId`), or `null` when no person is assigned.
        agent:
          anyOf:
            - type: object
              properties:
                connectorId:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: The `connectors` row id for a connector-backed agent; `null` for the built-in one.
                builtin:
                  anyOf:
                    - type: string
                      const: jarvis
                    - type: 'null'
                  description: The built-in-agent key (`jarvis`) when this is the hosted Shipeasy agent; `null` for a connector-backed one.
                provider:
                  type: string
                  enum:
                    - claude_trigger
                    - cursor_trigger
                    - copilot_trigger
                    - jules_trigger
                    - jarvis
                  description: The trigger-connector provider backing this agent, or `jarvis` for the built-in hosted agent.
                name:
                  type: string
                  description: Display name — the connector's `name`, the provider default (e.g. "Claude"), or "Jarvis".
              required:
                - connectorId
                - builtin
                - provider
                - name
              additionalProperties: false
              description: The resolved agent owner. Exactly one of `connectorId` / `builtin` is set.
            - type: 'null'
          description: The AGENT half of the owner (resolved from `assigneeConnectorId` / `assigneeAgent`), or `null` when no agent is assigned.
      required:
        - user
        - agent
      additionalProperties: false
      description: 'The fully-resolved owner of a queue item — a person and/or an AI agent. The two halves are independent: an item may have a person, an agent, both, or neither (both `null`).'
    OpsRunAction:
      type: string
      enum:
        - link_pr
        - notify
        - status
        - superseded
      description: The final action that closed a run record — `link_pr`/`notify` are the agent's terminal ops actions, `status` a completion status flip (ready_for_qa/resolved), `superseded` a newer ack replacing an open run.
    OpsRunActionOrNull:
      anyOf:
        - $ref: '#/components/schemas/OpsRunAction'
        - type: 'null'
      description: Which final action closed the run, or `null` while it is open (or a non-run record).
    OpsRun:
      type: object
      properties:
        id:
          type: string
          description: Run record id.
        agent:
          anyOf:
            - type: string
            - type: 'null'
          description: The AI agent type working the run (`jarvis` | `claude` | `cursor` | `copilot` | `jules`); `null` for a human ack.
        connectorId:
          anyOf:
            - type: string
            - type: 'null'
          description: The trigger-connector row id backing the acking agent; `null` for a human ack or the built-in Jarvis agent.
        ackedBy:
          anyOf:
            - type: string
            - type: 'null'
          description: Email of the human who acked; `null` for an AI ack.
        sessionId:
          anyOf:
            - type: string
            - type: 'null'
          description: The agent-run session id recorded on the ack (dashboard deep-links to the run page), or `null`.
        sessionUrl:
          anyOf:
            - type: string
            - type: 'null'
          description: 'The run''s session-page deep link, or `null`. DERIVED (never stored): rebuilt from `sessionId` + the run''s trigger connector — Claude''s routine id (`?trigger=`), Copilot''s repo (`/tasks/`), Cursor/Jules from the id alone.'
        startedAt:
          type: string
          description: ISO-8601 timestamp the run started (the ack time).
        completedAt:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-8601 timestamp the run closed, or `null` while still open.
        completedAction:
          $ref: '#/components/schemas/OpsRunActionOrNull'
        prNumber:
          anyOf:
            - type: number
            - type: 'null'
          description: The PR the run linked as its final action, or `null`.
        prUrl:
          anyOf:
            - type: string
            - type: 'null'
          description: HTML URL of that PR, or `null`.
      required:
        - id
        - agent
        - connectorId
        - ackedBy
        - sessionId
        - sessionUrl
        - startedAt
        - completedAt
        - completedAction
        - prNumber
        - prUrl
      additionalProperties: false
      description: One run on a queue item — who (person or AI agent) picked it up when, and, once closed, how it ended (final action + PR + session link). Opened by `POST /api/admin/ops/{handle}/ack`.
    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'
          investigationState:
            anyOf:
              - $ref: '#/components/schemas/OpsInvestigationState'
              - type: 'null'
            description: Where automation has taken this item in the investigation lifecycle (see `OpsInvestigationState`). Optional — absent/`null` on rows filed before the field existed; derive from `status`/`type` in that case.
          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).'
          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: 'The RAW stored capture context on the row — NOT hydrated: list rows carry only what was captured at file time (e.g. `context.browser` for bug/feature, the trigger subset for auto-filed tickets). The live `error`/`alert` readings and `errorChart` are added only by the single-item read (`GET /api/admin/ops/{handle}`). `null` when nothing was captured.'
          connectorData:
            anyOf:
              - $ref: '#/components/schemas/ConnectorData'
              - type: 'null'
            description: Per-connector linkage recorded for this item, keyed by connector provider. `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).
          assigneeId:
            anyOf:
              - type: string
              - type: 'null'
            description: The PERSON owner — a `users.id` (resolved into `owner.user`), or `null` when unassigned.
          assigneeConnectorId:
            anyOf:
              - type: string
              - type: 'null'
            description: The AGENT owner when it is a connected trigger connector — a `connectors` row id (resolved into `owner.agent`), or `null`. Mutually exclusive with `assigneeAgent`.
          assigneeAgent:
            anyOf:
              - type: string
              - type: 'null'
            description: The AGENT owner when it is a built-in hosted Shipeasy agent — currently only `jarvis` — or `null`. Mutually exclusive with `assigneeConnectorId`.
          owner:
            $ref: '#/components/schemas/OpsItemOwner'
          run:
            anyOf:
              - $ref: '#/components/schemas/OpsRun'
              - type: 'null'
            description: The currently OPEN run on this item (someone acked it and is actively working — the cockpit's live working indicator), or `null` when nothing is in flight.
          lastRun:
            anyOf:
              - $ref: '#/components/schemas/OpsRun'
              - type: 'null'
            description: The most recently COMPLETED run (the run result — final action, PR, duration), excluding superseded runs; `null` when no run has completed yet.
          createdAt:
            type: string
            description: ISO-8601 creation timestamp.
          updatedAt:
            type: string
            description: ISO-8601 last-update timestamp.
        required:
          - id
          - number
          - type
          - title
          - status
          - priority
          - source
          - owner
          - run
          - lastRun
          - createdAt
          - updatedAt
        additionalProperties: {}
        description: One queue item — any type — plus its resolved `owner` and run state.
      description: A page of queue items, newest first.
    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`.
        status:
          anyOf:
            - $ref: '#/components/schemas/OpsItemStatus'
          description: Initial lifecycle status; defaults to `open` when omitted.
        assigneeId:
          anyOf:
            - type: string
            - type: 'null'
          description: The `users.id` of the person to assign as owner at creation, or `null`.
        subscribers:
          type: array
          items:
            type: string
            format: email
          default: []
          description: Emails of teammates to subscribe to this item's Slack pings at creation.
        tags:
          type: array
          items:
            type: string
          default: []
          description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
        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`.
        status:
          anyOf:
            - $ref: '#/components/schemas/OpsItemStatus'
          description: Initial lifecycle status; defaults to `open` when omitted.
        assigneeId:
          anyOf:
            - type: string
            - type: 'null'
          description: The `users.id` of the person to assign as owner at creation, or `null`.
        subscribers:
          type: array
          items:
            type: string
            format: email
          default: []
          description: Emails of teammates to subscribe to this item's Slack pings at creation.
        tags:
          type: array
          items:
            type: string
          default: []
          description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
        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`.
    CreatePublicBugRequest:
      type: object
      properties:
        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`.
        status:
          anyOf:
            - $ref: '#/components/schemas/OpsItemStatus'
          description: Initial lifecycle status; defaults to `open` when omitted.
        assigneeId:
          anyOf:
            - type: string
            - type: 'null'
          description: The `users.id` of the person to assign as owner at creation, or `null`.
        subscribers:
          type: array
          items:
            type: string
            format: email
          default: []
          description: Emails of teammates to subscribe to this item's Slack pings at creation.
        tags:
          type: array
          items:
            type: string
          default: []
          description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
        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:
        - title
      additionalProperties: false
      description: Body for `POST /ops/bug`. The same bug fields as `CreateBugRequest`, minus the `type` discriminator — the path already says what is being filed.
    CreatePublicTicketResponse:
      type: object
      properties:
        id:
          type: string
          description: The new item's id. Absent on a deduped response — nothing was created, so there is no new id to report.
        number:
          type: integer
          description: Per-project item number. On a deduped response this is the number of the OPEN ticket already tracking the report, which is what a caller should show the user either way.
        deduped:
          type: boolean
          description: '`true` when an open ticket already tracked this report and nothing was filed (HTTP 200). Absent on a fresh file (HTTP 201).'
      required:
        - number
      additionalProperties: false
      description: 'Response for the public ticket intake. A fresh file returns `201` with `id` + `number`; a repeat of a report already tracked by an open ticket returns `200` with that ticket''s `number` and `deduped: true`.'
    CreatePublicFeatureRequestRequest:
      type: object
      properties:
        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`.
        status:
          anyOf:
            - $ref: '#/components/schemas/OpsItemStatus'
          description: Initial lifecycle status; defaults to `open` when omitted.
        assigneeId:
          anyOf:
            - type: string
            - type: 'null'
          description: The `users.id` of the person to assign as owner at creation, or `null`.
        subscribers:
          type: array
          items:
            type: string
            format: email
          default: []
          description: Emails of teammates to subscribe to this item's Slack pings at creation.
        tags:
          type: array
          items:
            type: string
          default: []
          description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
        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:
        - title
      additionalProperties: false
      description: Body for `POST /ops/feature-request`. The same feature-request fields as `CreateFeatureRequestRequest`, minus the `type` discriminator — the path already says what is being filed.
    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.
    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.
        investigationState:
          anyOf:
            - $ref: '#/components/schemas/OpsInvestigationState'
            - type: 'null'
          description: Where automation has taken this item in the investigation lifecycle (see `OpsInvestigationState`). Written as a side-effect of the actions that already happen (link a PR, change status, an assistant reply); `null` on rows filed before the field existed — derive from `status`/`type` in that case.
        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).
        assigneeId:
          anyOf:
            - type: string
            - type: 'null'
          description: The PERSON owner — a `users.id` (resolved into `owner.user`), or `null` when unassigned.
        assigneeConnectorId:
          anyOf:
            - type: string
            - type: 'null'
          description: The AGENT owner when it is a connected trigger connector — a `connectors` row id (resolved into `owner.agent`), or `null`. Mutually exclusive with `assigneeAgent`.
        assigneeAgent:
          anyOf:
            - type: string
            - type: 'null'
          description: The AGENT owner when it is a built-in hosted Shipeasy agent — currently only `jarvis` — or `null`. Mutually exclusive with `assigneeConnectorId`.
        owner:
          $ref: '#/components/schemas/OpsItemOwner'
        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
        - owner
        - 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.
    DeleteOpsItemResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
          description: Always `true` — the item (and its comments, attachments, tags, and investigation records) was deleted.
      required:
        - ok
      additionalProperties: false
      description: Response for `DELETE /api/admin/ops/{handle}`.
    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.
        pr:
          anyOf:
            - $ref: '#/components/schemas/GithubPrLink'
            - type: 'null'
          description: 'The PR link now recorded on the item (`connectorData.github.pr`), or `null` after an unlink (`prNumber: null`).'
      required:
        - id
        - pr
      additionalProperties: false
      description: Response for `POST /api/admin/ops/{handle}/link-pr` — the item id and the resulting PR link.
    AckOpsItemRequest:
      type: object
      properties:
        agent:
          type: string
          enum:
            - claude
            - cursor
            - copilot
            - jules
            - gemini
            - jarvis
          description: The AI agent type acking on the item's behalf — pass your own type when you are a coding agent (Claude Code passes `claude`, Cursor `cursor`, Copilot `copilot`, Jules/Gemini `jules`). Omit entirely for a human ack by the authenticated caller.
        sessionId:
          type: string
          maxLength: 300
          description: The agent-run session id (e.g. Claude's `session_01…`), so the dashboard can deep-link to the exact run page. Omit when the harness has no session id.
      additionalProperties: false
      description: Body for `POST /api/admin/ops/{handle}/ack`. With `agent` set this is an AI ack — the named agent type must have a connected trigger connector in the project, or the call fails with `AGENT_NOT_CONNECTED` and instructions to query the available agents (`ops agents list`). `gemini` is accepted as an alias for `jules`. Without `agent` it is a HUMAN ack by the authenticated caller.
    AckOpsItemResponse:
      type: object
      properties:
        id:
          type: string
          description: Item id that was acked.
        number:
          anyOf:
            - type: number
            - type: 'null'
          description: Per-project item number.
        status:
          type: string
          description: The working status the ack moved the item into (`investigating_by_ai` for an AI ack, `in_progress` for a human one).
        runId:
          type: string
          description: Id of the run record the ack opened.
        agent:
          anyOf:
            - type: string
            - type: 'null'
          description: The AI agent type working the item; `null` for a human ack.
        connectorName:
          anyOf:
            - type: string
            - type: 'null'
          description: Display name of the connected agent (the connector's name); `null` for a human ack.
        sessionId:
          anyOf:
            - type: string
            - type: 'null'
          description: The session id recorded on the run, if one was supplied.
        startedAt:
          type: string
          description: ISO-8601 timestamp the run started (the ack time).
      required:
        - id
        - number
        - status
        - runId
        - agent
        - connectorName
        - sessionId
        - startedAt
      additionalProperties: false
      description: Response for `POST /api/admin/ops/{handle}/ack` — the opened run.
    OpsInvestigation:
      type: object
      properties:
        id:
          type: string
          description: Investigation record id.
        feedbackId:
          type: string
          description: The queue item this record hangs off.
        kind:
          type: string
          enum:
            - investigated
            - detected
            - question
            - ready_for_qa
            - working
            - note
          description: Which lifecycle stage the record documents — mirrors the investigation-state buckets the cockpit renders. `working` records double as run rows (see `OpsRun`).
        summary:
          anyOf:
            - type: string
            - type: 'null'
          description: One-line summary of the record, or `null`.
        findings:
          anyOf:
            - type: string
            - type: 'null'
          description: The agent's full findings write-up (markdown), or `null`.
        question:
          anyOf:
            - type: string
            - type: 'null'
          description: A blocking question for the team (markdown), or `null`.
        qaNotes:
          anyOf:
            - type: string
            - type: 'null'
          description: How to verify the fix — QA notes (markdown), or `null`.
        agent:
          anyOf:
            - type: string
              enum:
                - jarvis
                - claude
                - cursor
                - copilot
                - jules
            - type: 'null'
          description: Which agent produced the record (`jarvis` is the in-house assistant; the rest are trigger-connector coding agents), or `null`.
        model:
          anyOf:
            - type: string
            - type: 'null'
          description: The model the agent ran on (self-reported), or `null`.
        connectorId:
          anyOf:
            - type: string
            - type: 'null'
          description: The trigger-connector row id the agent ran through, or `null`.
        prNumber:
          anyOf:
            - type: number
            - type: 'null'
          description: A PR the record references (e.g. the run's fixing PR), or `null`.
        prUrl:
          anyOf:
            - type: string
            - type: 'null'
          description: HTML URL of that PR, or `null`.
        sources:
          anyOf:
            - type: array
              items:
                type: object
                properties:
                  path:
                    type: string
                    description: Repo-relative file path the agent inspected.
                  url:
                    type: string
                    description: External link the agent consulted.
                  label:
                    type: string
                    description: Human-readable label for the source.
                additionalProperties: false
                description: One file/link the agent inspected while producing the record.
            - type: 'null'
          description: The files/links the agent inspected, or `null`.
        confidence:
          anyOf:
            - type: string
              enum:
                - low
                - medium
                - high
            - type: 'null'
          description: The agent's self-reported confidence, or `null`.
        tokensUsed:
          anyOf:
            - type: number
            - type: 'null'
          description: Tokens the run consumed (self-reported), or `null`.
        durationMs:
          anyOf:
            - type: number
            - type: 'null'
          description: Run duration in milliseconds, or `null`.
        visibility:
          type: string
          enum:
            - draft
            - published
          description: '`draft` records are the agent''s scratch state; only `published` ones render in the panel (and are returned by default).'
        startedAt:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-8601 timestamp the work started, or `null`.
        completedAt:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-8601 timestamp the work finished, or `null`.
        sessionId:
          anyOf:
            - type: string
            - type: 'null'
          description: The agent-run session id, or `null`.
        sessionUrl:
          anyOf:
            - type: string
            - type: 'null'
          description: 'The run''s session-page deep link, or `null`. DERIVED (never stored): rebuilt from `sessionId` + the run''s trigger connector — Claude''s routine id (`?trigger=`), Copilot''s repo (`/tasks/`), Cursor/Jules from the id alone. Only `working` run records carry one.'
        ackedBy:
          anyOf:
            - type: string
            - type: 'null'
          description: Email of the human who acked (run records for a human ack), or `null`.
        completedAction:
          $ref: '#/components/schemas/OpsRunActionOrNull'
        createdAt:
          type: string
          description: ISO-8601 creation timestamp.
        updatedAt:
          type: string
          description: ISO-8601 last-update timestamp.
      required:
        - id
        - feedbackId
        - kind
        - summary
        - findings
        - question
        - qaNotes
        - agent
        - model
        - connectorId
        - prNumber
        - prUrl
        - sources
        - confidence
        - tokensUsed
        - durationMs
        - visibility
        - startedAt
        - completedAt
        - sessionId
        - sessionUrl
        - ackedBy
        - completedAction
        - createdAt
        - updatedAt
      additionalProperties: false
      description: One structured investigation record on a queue item — the read-only write-up an AI agent produces while working it (findings / blocking question / QA notes), rendered by the cockpit's detail panel.
    ListOpsInvestigationsResponse:
      type: array
      items:
        $ref: '#/components/schemas/OpsInvestigation'
      description: Response for `GET /api/admin/ops/{handle}/investigation` — the item's `published` investigation records, newest first (max 50).
    CreateOpsInvestigationRequest:
      type: object
      properties:
        kind:
          type: string
          enum:
            - investigated
            - detected
            - question
            - ready_for_qa
            - working
            - note
          description: Which lifecycle stage the record documents.
        summary:
          type: string
          maxLength: 2000
          description: One-line summary of the record.
        findings:
          type: string
          maxLength: 50000
          description: The full findings write-up (markdown).
        question:
          type: string
          maxLength: 10000
          description: A blocking question for the team (markdown).
        qaNotes:
          type: string
          maxLength: 50000
          description: How to verify the fix — QA notes (markdown).
        agent:
          type: string
          enum:
            - jarvis
            - claude
            - cursor
            - copilot
            - jules
          description: The agent type producing the record — pass your own type when you are a coding agent.
        model:
          type: string
          maxLength: 200
          description: The model the agent ran on.
        connectorId:
          type: string
          maxLength: 200
          description: The trigger-connector row id the agent ran through.
        prNumber:
          type: integer
          description: A PR the record references.
        prUrl:
          type: string
          format: uri
          maxLength: 2000
          description: HTML URL of that PR.
        sources:
          type: array
          maxItems: 200
          items:
            type: object
            properties:
              path:
                type: string
                description: Repo-relative file path inspected.
              url:
                type: string
                description: External link consulted.
              label:
                type: string
                description: Human-readable label for the source.
            additionalProperties: false
            description: One file/link inspected while producing the record.
          description: The files/links inspected.
        confidence:
          type: string
          enum:
            - low
            - medium
            - high
          description: Self-reported confidence in the record.
        tokensUsed:
          type: integer
          description: Tokens the run consumed.
        durationMs:
          type: integer
          description: Run duration in milliseconds.
        visibility:
          type: string
          enum:
            - draft
            - published
          description: Record visibility. Defaults to `published`; `draft` keeps it out of the panel.
        startedAt:
          type: string
          description: ISO-8601 timestamp the work started.
        completedAt:
          type: string
          description: ISO-8601 timestamp the work finished.
        sessionId:
          type: string
          maxLength: 300
          description: The agent-run session id, so the dashboard can deep-link to the run.
      required:
        - kind
      additionalProperties: false
      description: Body for `POST /api/admin/ops/{handle}/investigation`. `kind` is required; include at least one content field (`summary`/`findings`/`question`/`qaNotes`) — the panel renders whatever it gets.
    UpdateOpsInvestigationRequest:
      type: object
      properties:
        kind:
          type: string
          enum:
            - investigated
            - detected
            - question
            - ready_for_qa
            - working
            - note
          description: Reclassify the record's lifecycle stage (e.g. flip a `working` run into `investigated` once findings land).
        summary:
          type: string
          maxLength: 2000
          description: One-line summary of the record.
        findings:
          type: string
          maxLength: 50000
          description: The full findings write-up (markdown).
        question:
          type: string
          maxLength: 10000
          description: A blocking question for the team (markdown).
        qaNotes:
          type: string
          maxLength: 50000
          description: How to verify the fix — QA notes (markdown).
        model:
          type: string
          maxLength: 200
          description: The model the agent ran on.
        prNumber:
          type: integer
          description: A PR the record references.
        prUrl:
          type: string
          format: uri
          maxLength: 2000
          description: HTML URL of that PR.
        sources:
          type: array
          maxItems: 200
          items:
            type: object
            properties:
              path:
                type: string
                description: Repo-relative file path inspected.
              url:
                type: string
                description: External link consulted.
              label:
                type: string
                description: Human-readable label for the source.
            additionalProperties: false
            description: One file/link inspected while producing the record.
          description: The files/links inspected.
        confidence:
          type: string
          enum:
            - low
            - medium
            - high
          description: Self-reported confidence in the record.
        tokensUsed:
          type: integer
          description: Tokens the run consumed.
        durationMs:
          type: integer
          description: Run duration in milliseconds.
        visibility:
          type: string
          enum:
            - draft
            - published
          description: Record visibility. `draft` keeps it out of the panel; `published` surfaces it.
        completedAt:
          type: string
          description: ISO-8601 timestamp the work finished. Set it (or flip `kind` off `working`) to mark a run record done.
        sessionId:
          type: string
          maxLength: 300
          description: The agent-run session id, so the dashboard can deep-link to the run.
      additionalProperties: false
      minProperties: 1
      description: Body for `PATCH /api/admin/ops/{handle}/investigation/{investigationId}` — a partial update of one existing investigation record (typically the `working` run record you were handed). Send only the fields you want to change; at least one is required.
    OpsAgentProfile:
      type: object
      properties:
        connectorId:
          type: string
          description: The connector row id — what an agent assignment stores.
        provider:
          type: string
          enum:
            - claude_trigger
            - cursor_trigger
            - copilot_trigger
            - jules_trigger
          description: The trigger-connector provider backing this agent.
        name:
          type: string
          description: Display name — the connector's `name`, or the provider default (e.g. "Claude").
        handle:
          type: string
          description: Mention/search handle — the kebab-cased name (e.g. `claude`).
      required:
        - connectorId
        - provider
        - name
        - handle
      additionalProperties: false
      description: One connected, assignable AI agent (an authenticated trigger connector).
    ListOpsAgentsResponse:
      type: array
      items:
        $ref: '#/components/schemas/OpsAgentProfile'
      description: The project's connected AI agents — the agent types `POST /api/admin/ops/{handle}/ack` accepts. Empty when no trigger connector is connected yet.
    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`.
    AlertCompositeSpec:
      type: object
      description: 'What a `composite` rule is a boolean over. `rules` are sibling alert-rule ids in the same project and `op` is how their states combine. A child''s state is what the current pass concluded about it, falling back to whether it has an open instance — so a composite still means something on a tick where a child could not be evaluated, which is exactly the tick a "two of these are broken at once" rule is for. One level deep: a child may not itself be composite.'
      properties:
        op:
          type: string
          enum:
            - and
            - or
          description: How the children's states combine.
        rules:
          type: array
          minItems: 2
          items:
            type: string
            minLength: 1
          description: Ids of the alert rules to combine. Stored sorted and de-duplicated.
      required:
        - op
        - rules
      additionalProperties: false
    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.
          kind:
            type: string
            enum:
              - normal
              - anomaly
              - outliers
              - no_data
              - composite
            description: What the rule watches for. `normal` compares the metric's own value — against `threshold` via `comparator`, or against the [`rangeMin`, `rangeMax`] corridor it must stay inside. `anomaly` compares it against ITS OWN seasonal baseline in sigmas, which is the same fit a chart draws as the band. `outliers` compares each `by()` group against its peers in the same bucket, so it needs a grouped metric. `no_data` fires when the metric records nothing at all for `noDataMinutes` — a count of zero is not silence, and the two are distinguished by the reader's presence columns. `composite` is a boolean over OTHER rules' current state and watches no metric of its own.
          comparator:
            type: string
            enum:
              - gt
              - gte
              - lt
              - lte
            description: How the metric value is compared to the threshold (gt/gte/lt/lte). Read only by a `normal` rule with no range set.
          threshold:
            type: number
            description: Threshold the metric value is compared against. Read only by a `normal` rule with no range set.
          rangeMin:
            anyOf:
              - type: number
              - type: 'null'
            description: Lower edge of the corridor a `normal` rule must stay inside; `null` if the rule is judged by comparator and threshold.
          rangeMax:
            anyOf:
              - type: number
              - type: 'null'
            description: Upper edge of the corridor a `normal` rule must stay inside; `null` if the rule is judged by comparator and threshold.
          sigma:
            anyOf:
              - type: number
              - type: 'null'
            description: How far from normal is too far, for `anomaly` and `outliers`, in sigma-equivalents. `null` takes the default of 3, which is also the width of the band a chart draws.
          direction:
            anyOf:
              - type: string
                enum:
                  - above
                  - below
                  - either
              - type: 'null'
            description: Which side of the baseline an `anomaly` or `outliers` rule watches. `null` means either.
          sustained:
            type: boolean
            description: Whether the rule is judged by ACCUMULATED departure rather than bucket by bucket. `anomaly` and `outliers` only.
          warnThreshold:
            anyOf:
              - type: number
              - type: 'null'
            description: The milder bound, in the same unit the kind judges in. `null` means the rule has one level.
          recoveryThreshold:
            anyOf:
              - type: number
              - type: 'null'
            description: What the metric must get back to before a live alert closes. `null` means no hysteresis — the firing bound clears it.
          groupAlerts:
            type: boolean
            description: Whether the rule fires one alert per `by()` group rather than one for the whole metric.
          maxGroups:
            anyOf:
              - type: integer
              - type: 'null'
            description: How many groups this rule may alert on at once. `null` takes the shipped cap of 10.
          noDataMinutes:
            anyOf:
              - type: integer
              - type: 'null'
            description: How long the silence must last for a `no_data` rule. `null` on every other kind.
          delayMinutes:
            anyOf:
              - type: integer
              - type: 'null'
            description: How far behind live the evaluated window is held, on top of the reader's settle grace. `null` means no extra delay.
          autoResolveMinutes:
            anyOf:
              - type: integer
              - type: 'null'
            description: Close a live instance that has gone this long without a fresh verdict. `null` never auto-resolves.
          composite:
            anyOf:
              - $ref: '#/components/schemas/AlertCompositeSpec'
              - type: 'null'
            description: For a `composite` rule, the child rules and how their states combine. `null` on every other kind.
          windowHours:
            type: integer
            minimum: -9007199254740991
            maximum: 9007199254740991
            description: Lookback window (hours) the metric is aggregated over.
          bucketMinutes:
            anyOf:
              - type: integer
              - type: 'null'
            description: Width of the buckets the window is split into, in minutes. `null` divides the window into 12 equal buckets.
          requiredBuckets:
            anyOf:
              - type: integer
              - type: 'null'
            description: How many buckets must breach before the rule fires. `null` means every bucket that had data.
          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
          - kind
          - comparator
          - threshold
          - rangeMin
          - rangeMax
          - sigma
          - direction
          - sustained
          - warnThreshold
          - recoveryThreshold
          - groupAlerts
          - maxGroups
          - noDataMinutes
          - delayMinutes
          - autoResolveMinutes
          - composite
          - windowHours
          - bucketMinutes
          - requiredBuckets
          - 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.
        kind:
          default: normal
          description: 'What the rule watches for. `normal` compares the metric''s own value — against `threshold` via `comparator`, or against the [`rangeMin`, `rangeMax`] corridor it must stay inside. `anomaly` compares it against its own seasonal baseline in sigmas: the same fit a chart draws as the band, so a point outside the drawn band is exactly a breaching bucket, and one metric can back rules at several sigmas. `outliers` compares each `by()` group against its peers in the same bucket and is refused on a metric with no grouping.'
          type: string
          enum:
            - normal
            - anomaly
            - outliers
            - no_data
            - composite
        comparator:
          default: gt
          description: How the metric value is compared to the threshold. Read only by a `normal` rule with no range set.
          type: string
          enum:
            - gt
            - gte
            - lt
            - lte
        threshold:
          type: number
          description: Threshold the metric value is compared against. Required for a `normal` rule unless a range is given; ignored by every other kind.
        rangeMin:
          anyOf:
            - type: number
            - type: 'null'
          description: Lower edge of the corridor the metric must stay inside. Setting either bound switches a `normal` rule off `comparator`/`threshold` and onto the range, which breaches on LEAVING it in either direction. One bound alone is a one-sided range.
        rangeMax:
          anyOf:
            - type: number
            - type: 'null'
          description: Upper edge of the corridor the metric must stay inside.
        sigma:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: 'null'
          description: How far from normal is too far, for `anomaly` and `outliers`, in sigma-equivalents. Omit (or `null`) for 3, which is also the half-width of the band a chart draws — so an unconfigured rule fires exactly where the picture says it would.
        direction:
          anyOf:
            - type: string
              enum:
                - above
                - below
                - either
            - type: 'null'
          description: Which side of the baseline an `anomaly` or `outliers` rule watches. Omit (or `null`) for either, which is what "is this unusual" means; name a side for a metric that is only bad in one direction.
        sustained:
          default: false
          type: boolean
          description: 'Judge the window by ACCUMULATED departure instead of bucket by bucket. The ordinary check asks every bucket to be past `sigma`, which a slow regression never manages: a metric running 1.5σ worse than normal since Tuesday puts no single bucket past 3σ and pages nobody. A sustained rule adds up each bucket''s excess over half a sigma and fires once the total passes twice `sigma` — four buckets at 2σ do it, a lone 3σ spike does not. `anomaly` and `outliers` only, and refused alongside `requiredBuckets`: the accumulated bar IS the evidence bar, and a second one counted in buckets would silently override it.'
        windowHours:
          default: 24
          description: Lookback window (hours) the metric is aggregated over. 1–720.
          type: integer
          minimum: 1
          maximum: 720
        bucketMinutes:
          anyOf:
            - type: integer
              minimum: 1
              maximum: 43200
            - type: 'null'
          description: Width of the buckets the window is split into, in minutes. Omit (or `null`) to divide the window into 12 equal buckets. The rule is judged per bucket, so this is the resolution at which "sustained" is measured — a short bucket asks the condition to hold through finer detail.
        requiredBuckets:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          description: How many buckets must breach before the rule fires. Omit (or `null`) to require every bucket that had data. Buckets with nothing in them are excluded before this is counted, so on a sparse metric `null` can mean a single bucket — set this to 2 or more where one lone sample must never page.
        warnThreshold:
          anyOf:
            - type: number
            - type: 'null'
          description: 'The milder bound — a second level, in the same unit the kind judges in, that raises a quieter alert before the firing level is reached. Must be strictly milder than the level the rule fires at, or it could never fire on its own. Refused on a range rule and on a `sustained` one: neither condition is a single number, so there is nothing to substitute.'
        recoveryThreshold:
          anyOf:
            - type: number
            - type: 'null'
          description: What the metric must get back to before a live alert closes. Without it a metric sitting on its threshold pages and clears once per tick. Must be on the safe side of the firing level, or equal to it. Omit (or `null`) for no hysteresis.
        groupAlerts:
          default: false
          type: boolean
          description: Fire one alert per `by()` group instead of one for the whole metric. The firing key becomes (rule, group), so each group raises, dedupes and recovers on its own. Refused on a metric with no `by()`, and on `no_data` — a group that went silent has no rows left to be missing from.
        maxGroups:
          anyOf:
            - type: integer
              minimum: 1
              maximum: 50
            - type: 'null'
          description: How many groups this rule may alert on at once. Omit (or `null`) for 10. Past the cap the worst groups fire and the count of the rest is stated on each ticket — a group set is customer data, and an uncapped rule on `by(user_id)` would file a ticket per user.
        noDataMinutes:
          anyOf:
            - type: integer
              minimum: 5
              maximum: 43200
            - type: 'null'
          description: 'For a `no_data` rule: how long the silence must last. Omit (or `null`) for 15 minutes. Five is the floor — below it, ordinary ingest lag empties the trailing bucket and reads as an outage.'
        delayMinutes:
          anyOf:
            - type: integer
              minimum: 1
              maximum: 1440
            - type: 'null'
          description: Hold the evaluated window back this far behind live, on top of the reader's own settle grace. For a metric assembled from a source that lands in batches, whose trailing buckets are legitimately incomplete for longer than the grace covers.
        autoResolveMinutes:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          description: Close a live instance that has gone this long without a fresh verdict. A rule that cannot reach a verdict deliberately leaves its alert alone, which is right for a tick and wrong for a week. Never closes an instance that is currently breaching. Omit (or `null`) to never auto-resolve.
        composite:
          $ref: '#/components/schemas/AlertCompositeSpec'
        severity:
          default: warn
          description: Severity of the raised alert. A `warnThreshold` breach opens one step quieter than this.
          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
      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
        kind:
          type: string
          enum:
            - normal
            - anomaly
            - outliers
            - no_data
            - composite
        comparator:
          type: string
          enum:
            - gt
            - gte
            - lt
            - lte
        threshold:
          type: number
        rangeMin:
          anyOf:
            - type: number
            - type: 'null'
          description: Lower edge of the corridor; `null` drops it, returning the rule to comparator and threshold when both bounds are gone.
        rangeMax:
          anyOf:
            - type: number
            - type: 'null'
          description: Upper edge of the corridor; `null` drops it.
        sigma:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: 'null'
          description: Sigmas an `anomaly` or `outliers` rule fires at; `null` restores the default of 3.
        direction:
          anyOf:
            - type: string
              enum:
                - above
                - below
                - either
            - type: 'null'
          description: Which side an `anomaly` or `outliers` rule watches; `null` restores either.
        sustained:
          type: boolean
          description: Judge the window by accumulated departure rather than bucket by bucket. `anomaly` and `outliers` only; refused alongside `requiredBuckets`.
        warnThreshold:
          anyOf:
            - type: number
            - type: 'null'
          description: The milder bound; `null` drops the warning level, leaving the rule with one.
        recoveryThreshold:
          anyOf:
            - type: number
            - type: 'null'
          description: What the metric must get back to before a live alert closes; `null` drops the hysteresis.
        groupAlerts:
          type: boolean
          description: Fire one alert per `by()` group. Refused on a metric with no grouping.
        maxGroups:
          anyOf:
            - type: integer
              minimum: 1
              maximum: 50
            - type: 'null'
          description: How many groups may alert at once; `null` restores the default of 10.
        noDataMinutes:
          anyOf:
            - type: integer
              minimum: 5
              maximum: 43200
            - type: 'null'
          description: How long a `no_data` rule's silence must last; `null` restores 15 minutes.
        delayMinutes:
          anyOf:
            - type: integer
              minimum: 1
              maximum: 1440
            - type: 'null'
          description: How far behind live the window is held; `null` drops the delay.
        autoResolveMinutes:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          description: Close a stale live instance after this long; `null` never auto-resolves.
        composite:
          $ref: '#/components/schemas/AlertCompositeSpec'
        windowHours:
          type: integer
          minimum: 1
          maximum: 720
        bucketMinutes:
          anyOf:
            - type: integer
              minimum: 1
              maximum: 43200
            - type: 'null'
          description: Bucket width in minutes; `null` restores the default 12 buckets per window.
        requiredBuckets:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          description: Buckets that must breach to fire; `null` restores "every bucket that had data".
        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
    AlertApiRow:
      type: object
      description: |-
        One FIRED alert — an INSTANCE of a condition the platform observed, not the rule that defines it (alert *rules* are the `/api/admin/alert-rules` resource). Instances are never filed by hand: the UI (killswitch flips) and the worker (analysis consumer + alerts cron) open them, keyed by `(source, dedupeKey)`, and at most one instance per condition is open at a time — re-raising refreshes the open one, and the condition clearing closes it.

        An instance IS an ops queue item (`/api/admin/ops` with `type: "alert"`) seen through the alert lens: same `id`, `severity` is that item's `priority`, and `status` is its work status projected onto three states. Resolving the queue item and clearing the alert are therefore the same act.

        Every field is always present on the wire; nullable fields are `null`, never absent.
      properties:
        id:
          type: string
          description: Stable opaque instance id — also the id of the ops queue item this instance is.
        source:
          type: string
          enum:
            - metric_rule
            - killswitch_armed
            - experiment_srm
            - experiment_peek
            - guardrail
          description: Which platform subsystem raised the alert — a metric-threshold rule crossing (`metric_rule`), an armed kill switch (`killswitch_armed`), a sample-ratio mismatch or peeking guard on an experiment (`experiment_srm` / `experiment_peek`), or a guardrail-metric breach (`guardrail`).
        ruleId:
          description: 'Id of the alert rule that raised it (`ar_…`), for `source: metric_rule`. `null` for alerts raised outside the rules engine.'
          anyOf:
            - type: string
            - type: 'null'
        severity:
          type: string
          enum:
            - danger
            - warn
            - info
          description: How loud the alert is — `danger` pages, `warn` is the default, `info` is FYI-only. Severity belongs to the RULE and seeds the instance's queue `priority` (`danger`→`critical`, `warn`→`high`, `info`→`medium`); it is read back from there, so re-prioritising the queue item changes what this reports.
        dedupeKey:
          type: string
          description: Idempotency + reconcile key within `(project, source)` — re-raising the same condition refreshes the open instance instead of stacking duplicates, and the condition clearing closes it. A later firing of the same condition opens a NEW instance with its own `id`.
        title:
          type: string
          description: Short human-readable headline (what fired).
        detail:
          type: string
          description: Longer human-readable explanation — the observed condition, thresholds, and context.
        href:
          description: Dashboard-relative link to the surface that explains the alert (e.g. the experiment or kill switch page), or `null` if there is no single destination.
          anyOf:
            - type: string
            - type: 'null'
        observedValue:
          description: The numeric value that tripped the condition (e.g. the metric aggregate a rule compared against its threshold), or `null` when the source has no scalar observation.
          anyOf:
            - type: number
            - type: 'null'
        status:
          type: string
          enum:
            - active
            - resolved
            - dismissed
          description: Lifecycle state, projected from the queue item's work status. `active` means the item is still open, i.e. the condition holds (shown as "Firing" in the UI); `resolved` means it cleared (auto, when the raiser reconciles, or by hand); `dismissed` means a human waved it off (the item is closed `wont_fix`).
        createdAt:
          type: string
          description: ISO-8601 timestamp this instance opened — when the condition started firing.
        resolvedAt:
          description: ISO-8601 timestamp the alert flipped to `resolved`, or `null` while it hasn't.
          anyOf:
            - type: string
            - type: 'null'
        dismissedAt:
          description: ISO-8601 timestamp the alert was dismissed, or `null` while it hasn't been.
          anyOf:
            - type: string
            - type: 'null'
        assigneeId:
          description: PERSON owner of the triage — a `users.id` (soft reference, same value space as a feedback item's `assigneeId`), or `null` if unassigned. Set from the ops cockpit's Owner column; independent of the agent half.
          anyOf:
            - type: string
            - type: 'null'
        assigneeConnectorId:
          description: AGENT owner — the id of a connected trigger connector (`connectors.id`), or `null`. Mutually exclusive with `assigneeAgent`.
          anyOf:
            - type: string
            - type: 'null'
        assigneeAgent:
          description: AGENT owner — a built-in hosted Shipeasy agent (`"jarvis"`, Enterprise-gated), or `null`. Mutually exclusive with `assigneeConnectorId`.
          anyOf:
            - type: string
            - type: 'null'
      required:
        - id
        - source
        - ruleId
        - severity
        - dedupeKey
        - title
        - detail
        - href
        - observedValue
        - status
        - createdAt
        - resolvedAt
        - dismissedAt
        - assigneeId
        - assigneeConnectorId
        - assigneeAgent
      additionalProperties: false
    ListAlertsResponse:
      type: array
      description: A bare JSON array of fired alerts, ordered by `createdAt` descending. There is no pagination envelope.
      items:
        $ref: '#/components/schemas/AlertApiRow'
    UpdateAlertRequest:
      type: object
      description: |-
        Body for `PATCH /api/admin/alerts/{id}` — the triage writes the ops cockpit needs on a fired alert. All fields optional, at least one required; only the fields present are changed.

        Flipping `status` stamps the matching timestamp (`resolvedAt` on `resolved`, `dismissedAt` on `dismissed`; both cleared on `active`). The person owner (`assigneeId`) and the agent owner (`agent`) are independent halves — setting one never touches the other.
      properties:
        status:
          type: string
          enum:
            - active
            - resolved
            - dismissed
          description: New lifecycle state, written through to the queue item (`resolved` / `wont_fix` / `open`). `resolved` / `dismissed` stamp their timestamp; `active` re-opens and clears both.
        assigneeId:
          description: PERSON owner — a `users.id`, or `null` to clear the assignment.
          anyOf:
            - type: string
            - type: 'null'
        agent:
          description: AGENT owner — a connected trigger connector's id (`connectors.id`), the built-in `"jarvis"` (Enterprise plan only — rejected with `403` otherwise), or `null` to clear. Stored in `assigneeConnectorId` or `assigneeAgent` depending on the value; the two are mutually exclusive.
          anyOf:
            - type: string
            - type: 'null'
      minProperties: 1
      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.
        defaultHoldoutBp:
          type: integer
          description: Default holdout carve-out (basis points) that seeds each new universe's holdout (0 = none).
        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.
        slug:
          anyOf:
            - type: string
            - type: 'null'
          description: URL-safe project identifier used in app URLs and SDK config, or `null` if unset.
        logo:
          anyOf:
            - type: string
            - type: 'null'
          description: Cache-busted URL of the project logo (served from the admin logo route), or `null` when no logo is set.
        defaultEnv:
          type: string
          enum:
            - dev
            - staging
            - prod
          description: Default environment new resources are scoped to.
        timezone:
          type: string
          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
          description: Significance threshold (alpha) for experiment analysis, as a decimal string (e.g. `"0.05"`).
        autoRollback:
          type: boolean
          description: Whether a failing guardrail auto-rolls back the experiment.
        minSampleDays:
          type: integer
          description: Minimum number of days an experiment must run before it can be called.
        moduleUser:
          anyOf:
            - type: boolean
            - type: number
          description: Whether the user-management module is enabled.
        moduleEvents:
          anyOf:
            - type: boolean
            - type: number
          description: Whether the events module is enabled.
        allowPublicTickets:
          anyOf:
            - type: boolean
            - type: number
          description: Whether key-authenticated public ticket creation (`POST /cli/report`) is allowed into this project. Off by default.
        errorAutocloseDays:
          type: integer
          description: Days an `open` tracked error may go unseen before the nightly sweep auto-resolves it. `0` disables auto-close for this project. Ingest reopens a resolved error the moment it recurs, so this never hides a live issue.
        errorTicketMinOccurrences:
          type: integer
          description: Occurrence count a tracked error must cross before an `error` ticket is auto-filed into the ops queue. Customising it requires a paid plan; unentitled projects always run at the platform default of 10.
        stripeSubscriptionId:
          anyOf:
            - type: string
            - type: 'null'
          description: Stripe subscription id backing the project's billing, or `null` when unsubscribed.
        scheduledInterval:
          anyOf:
            - type: string
              enum:
                - monthly
                - annual
            - type: 'null'
          description: Pending billing-interval change deferred to period end (only the annual→monthly downgrade), or `null` when no switch is pending.
        spendLimitEnabled:
          anyOf:
            - type: boolean
            - type: number
          description: Whether the advisory monthly spend limit is enabled.
        spendLimitUsd:
          anyOf:
            - type: integer
            - type: 'null'
          description: Advisory monthly spend limit in whole USD, or `null` if unset.
        spendAlertEmail:
          anyOf:
            - type: string
            - type: 'null'
          description: Email address the spend alert is sent to, or `null` if unset.
        defaultAssigneePendingApproval:
          anyOf:
            - type: string
            - type: 'null'
          description: Default person owner (user id) auto-assigned to new `pending_approval` feedback items, or `null` when unset.
        defaultAssigneeConnectorPendingApproval:
          anyOf:
            - type: string
            - type: 'null'
          description: Default agent owner (connector id) auto-assigned to new `pending_approval` feedback items, or `null` when unset.
        defaultAssigneeOpen:
          anyOf:
            - type: string
            - type: 'null'
          description: Default person owner (user id) auto-assigned to new `open` feedback items, or `null` when unset.
        defaultAssigneeConnectorOpen:
          anyOf:
            - type: string
            - type: 'null'
          description: Default agent owner (connector id) auto-assigned to new `open` feedback items, or `null` when unset.
        deletedAt:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-8601 timestamp the project was soft-deleted (purged after a 14-day grace period), or `null` when live.
        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
        - moduleUser
        - moduleEvents
        - allowPublicTickets
        - errorAutocloseDays
        - errorTicketMinOccurrences
        - slug
        - logo
        - defaultEnv
        - timezone
        - statMethod
        - sigThreshold
        - autoRollback
        - minSampleDays
        - defaultHoldoutBp
        - stripeSubscriptionId
        - scheduledInterval
        - spendLimitEnabled
        - spendLimitUsd
        - spendAlertEmail
        - defaultAssigneePendingApproval
        - defaultAssigneeConnectorPendingApproval
        - defaultAssigneeOpen
        - defaultAssigneeConnectorOpen
        - deletedAt
        - createdAt
        - updatedAt
      additionalProperties: {}
      description: The project the caller's auth header resolves to. The shape is open — additional project fields may be present. Stripe billing internals (`stripeCustomerId`, the `stripeItemId*` family) are intentionally undocumented.
    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.
        errorAutocloseDays:
          type: integer
          minimum: 0
          maximum: 365
          description: Days an `open` tracked error may go unseen before the nightly sweep auto-resolves it. `0` disables auto-close for this project.
        errorTicketMinOccurrences:
          type: integer
          minimum: 1
          maximum: 10000
          description: Occurrence count a tracked error must cross before an `error` ticket is auto-filed into the ops queue. Requires a paid plan — the request is rejected with 403 on a plan without the `ops_auto_error_issues` entitlement.
      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
          - isDefault
          - createdAt
          - deletedAt
        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
              profileName:
                description: Name of the owning profile (e.g. `en:prod`), or `null` when it cannot be resolved.
                anyOf:
                  - type: string
                  - type: 'null'
              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
              - description
              - variables
              - profileId
              - profileName
              - updatedAt
              - updatedBy
            additionalProperties: false
            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.)
    UpsertI18nKeysRequest:
      type: object
      properties:
        profile_id:
          type: string
          format: uuid
          description: Target profile id to upsert keys into.
        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 upsert. Existing keys ARE overwritten — this is the bulk overwrite path.
      required:
        - profile_id
        - keys
      additionalProperties: false
      description: 'Body for `PUT /api/admin/i18n/keys`. Bulk upsert (overwrite): existing keys are replaced, new ones inserted. Backs the devtools overlay''s in-product label editing; deliberately not surfaced by the CLI or MCP.'
    UpsertI18nKeysResponse:
      type: object
      properties:
        upserted:
          type: number
          description: Number of keys written (inserted or overwritten).
      required:
        - upserted
      additionalProperties: false
      description: Result of a bulk key upsert. The affected profile's KV snapshot is rebuilt (and the CDN purged) before this returns.
    PushI18nKeysRequest:
      type: object
      properties:
        profile_id:
          type: string
          format: uuid
          description: Target profile id to add keys to.
        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 by default — existing keys are reported back as `skipped` (set `force` to overwrite them instead).
        force:
          type: boolean
          default: false
          description: Overwrite keys that already exist with the submitted value instead of skipping them. Overwritten keys come back as `updated`. Off by default so a routine push can never clobber live translations.
      required:
        - profile_id
        - keys
      additionalProperties: false
      description: 'Body for `POST /api/admin/i18n/keys`. Insert-only by default: keys that already exist are never overwritten — pass `force: true` to overwrite them in bulk, or use `PUT /keys/{id}` to change one 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. Always empty when `force` was set — those key names come back under `updated` instead.
        updated:
          type: array
          items:
            type: string
          description: Key names that already existed and were overwritten with the submitted value. Only ever non-empty when the push set `force`.
        pushed_count:
          type: number
          description: Number of keys inserted (== `added.length`).
        skipped_count:
          type: number
          description: Number of keys skipped (== `skipped.length`).
        updated_count:
          type: number
          description: Number of existing keys overwritten (== `updated.length`).
      required:
        - added
        - skipped
        - updated
        - pushed_count
        - skipped_count
        - updated_count
      additionalProperties: false
      description: Result of a key push — what was inserted, what was left alone, and (with `force`) what was overwritten.
    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.
    OkResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
          description: Always `true` — the operation succeeded (errors use the error envelope instead).
      required:
        - ok
      additionalProperties: false
      description: Generic success acknowledgement for operations with no meaningful payload.
    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
        - name
        - profileId
        - sourceProfileId
        - status
        - createdBy
        - createdAt
        - publishedAt
      additionalProperties: {}
      description: One staged translation draft. The shape is open — additional fields may be present.
    ListI18nDraftsResponse:
      type: array
      items:
        $ref: '#/components/schemas/I18nDraft'
      description: Bare array of the project's staged translation drafts.
    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.
    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.
    ListI18nDraftKeysResponse:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            description: Stable opaque draft-key id.
          draftId:
            type: string
            description: Id of the draft the key belongs to.
          key:
            type: string
            description: Dotted key path, e.g. `home.cta`.
          value:
            type: string
            description: Staged translated value for the key.
          description:
            description: Optional human note stored with the key, or `null`.
            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'
          updatedBy:
            type: string
            description: Actor email that last edited the staged key.
          updatedAt:
            type: string
            description: ISO-8601 timestamp of the last edit.
        required:
          - id
          - draftId
          - key
          - value
          - description
          - variables
          - updatedBy
          - updatedAt
        additionalProperties: false
        description: One staged draft key.
      description: Bare array of the draft's staged keys (no pagination envelope).
    UpsertI18nDraftKeyRequest:
      type: object
      properties:
        key:
          type: string
          minLength: 1
          maxLength: 256
          description: Dotted key path to stage, e.g. `home.cta`.
        value:
          type: string
          description: Staged translated value for the key.
        description:
          type: string
          description: Optional human note stored with the staged key.
      required:
        - key
        - value
      additionalProperties: false
      description: Body for `POST /api/admin/i18n/drafts/{draftId}/keys`. Upserts one staged key into an open draft — inserted when new, overwritten when it already exists. `{{var}}` placeholder names are auto-derived from the value.
    PublishI18nProfileRequest:
      type: object
      properties: {}
      additionalProperties: false
      description: Body for `POST /api/admin/i18n/profiles/{profileId}/publish`. Publishing is profile-wide — the whole profile is snapshotted into one KV blob — so the body takes no options.
    PublishI18nProfileResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
          description: Always `true` on success.
        profile_id:
          type: string
          description: Profile that was published.
        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
        - 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.
    ErrorOccurrence:
      type: object
      description: One sampled instance behind a tracked error — the minimal per-occurrence payload (what varies between instances; everything else lives on the parent `ErrorRecord`). Every column is always present on the wire; nullable columns are `null`, never absent.
      properties:
        id:
          type: string
          description: Stable opaque occurrence id.
        projectId:
          type: string
          description: Project this occurrence belongs to. Always echoes the parent error's `projectId` — redundant on this nested read (a projection candidate), kept because the raw row is returned as-is today.
        errorId:
          type: string
          description: Id of the parent tracked error (`err_…`). Always echoes the enclosing `ErrorRecord.id` — redundant on this nested read (a projection candidate), kept because the raw row is returned as-is today.
        message:
          type: string
          description: This instance's raw message (unlike the fingerprint, never normalized).
        stack:
          description: This instance's stack trace, or `null` if none was captured.
          anyOf:
            - type: string
            - type: 'null'
        url:
          description: This instance's raw URL (ids intact), or `null`.
          anyOf:
            - type: string
            - type: 'null'
        env:
          description: Published env this instance ran against, or `null`.
          anyOf:
            - type: string
            - type: 'null'
        side:
          description: Which SDK side reported it — `client` or `server`. `null` if unknown.
          anyOf:
            - type: string
            - type: 'null'
        sdkVersion:
          description: '`@shipeasy/sdk` version of this instance, or `null`.'
          anyOf:
            - type: string
            - type: 'null'
        extrasJson:
          description: This instance's sanitized extras, JSON-encoded. `null` if none.
          anyOf:
            - type: string
            - type: 'null'
        sampleRate:
          type: integer
          minimum: 1
          description: 1-in-N sampling rate in force when this instance was kept (`1` = the issue was still being recorded exhaustively).
        seenAt:
          type: string
          description: ISO-8601 timestamp this instance was ingested.
      required:
        - id
        - projectId
        - errorId
        - message
        - stack
        - url
        - env
        - side
        - sdkVersion
        - extrasJson
        - sampleRate
        - seenAt
      additionalProperties: false
    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). Every row column is always present on the wire; many are *nullable* because the reporting source may not supply them — `null`, never absent. Only `occurrences` is conditional (detail reads only).
      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 — the issue TITLE (hash of `errorType` + `subject` + `outcome`, plus the violation name for violations). Unique per project — every occurrence with the same title folds into this one row; per-instance variety (message/stack/extras) lives in `occurrences`.
        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: EXACT number of folded occurrences for this fingerprint — every occurrence increments it, regardless of detail-row sampling.
        occurrences:
          type: array
          description: Sampled per-instance detail rows behind this issue, newest first. Returned only by `GET /api/admin/errors/{id}` (never in list responses). The parent row's `count` / `firstSeenAt` / `lastSeenAt` are exact; these rows are a *sampled sketch* of the instances — exhaustive while the issue is small, thinning to roughly 1-in-10 past 10 occurrences, 1-in-100 past 100, and 1-in-1000 past 1000 (each row's `sampleRate` records the rate in force when it was kept), capped at the newest 100 rows.
          items:
            $ref: '#/components/schemas/ErrorOccurrence'
        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).
        assigneeId:
          description: PERSON owner of the triage — a `users.id` (soft reference, same value space as a feedback item's `assigneeId`), or `null` if unassigned. Set from the ops cockpit's Owner column; independent of the agent half.
          anyOf:
            - type: string
            - type: 'null'
        assigneeConnectorId:
          description: AGENT owner — the id of a connected trigger connector (`connectors.id`), or `null`. Mutually exclusive with `assigneeAgent`.
          anyOf:
            - type: string
            - type: 'null'
        assigneeAgent:
          description: AGENT owner — a built-in hosted Shipeasy agent (`"jarvis"`, Enterprise-gated), or `null`. Mutually exclusive with `assigneeConnectorId`.
          anyOf:
            - type: string
            - type: 'null'
      required:
        - id
        - projectId
        - fingerprint
        - causedByFingerprint
        - message
        - errorType
        - stack
        - source
        - url
        - seenUrls
        - subject
        - outcome
        - side
        - env
        - kind
        - lastExtrasJson
        - sdkVersion
        - count
        - status
        - firstSeenAt
        - lastSeenAt
        - createdAt
        - updatedAt
        - assigneeId
        - assigneeConnectorId
        - assigneeAgent
      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. List rows never include `occurrences` — read one error to get them.
      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:
          description: Human-facing per-project ticket number. `null` only on the idempotent dedupe path when the pre-existing ticket is a legacy row created before per-project numbering.
          anyOf:
            - type: integer
            - type: 'null'
      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.
        hasCredentials:
          type: boolean
          description: Whether an encrypted credentials cipher is stored for this connector (`true` once OAuth/token setup completed). The cipher itself is never serialised — this boolean is the only signal. `false` for a fresh OAuth stub or a tokenless trigger.
        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
        - hasCredentials
        - lastError
        - lastAttemptAt
        - lastSuccessAt
        - createdAt
        - updatedAt
      additionalProperties: false
      description: A connector row. The encrypted credentials cipher backing the connector is intentionally never serialised — `hasCredentials` reports only whether one is stored.
    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.
    CursorTriggerRepo:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: Repo the cloud agent runs against, e.g. `https://github.com/owner/repo`.
        startingRef:
          type: string
          minLength: 1
          description: Optional branch this repo's runs start from. Omit for the repo's default branch.
      required:
        - url
      additionalProperties: false
      description: One repo a trigger runs against, with the branch its runs start from.
    CursorTriggerConfig:
      type: object
      properties:
        repoUrl:
          type: string
          format: uri
          description: '**First** repo the cloud agent runs against, e.g. `https://github.com/owner/repo`. Idempotency key for the connector, and always a mirror of `repos[0].url` when `repos` is supplied.'
        startingRef:
          type: string
          minLength: 1
          description: Optional git ref the run starts from. Mirrors `repos[0].startingRef`. Pinned onto the Cursor agent at creation, so changing it provisions a replacement agent.
        repos:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CursorTriggerRepo'
          description: Every repo this trigger runs against, each with its own starting branch — Cursor launches ONE agent across the whole set. Omit for a single-repo trigger, which is then described by `repoUrl`/`startingRef` alone; when supplied, the first entry must match them. Changing the set re-provisions the agent (its repos are pinned at creation).
        projectId:
          type: string
          minLength: 1
          description: Shipeasy project id the run targets.
        agentId:
          type: string
          minLength: 1
          description: Server-managed. The reusable Cursor cloud agent (`bc-…`) Shipeasy provisions once at connect and then starts every run on. A supplied value is ignored on create; if Cursor stops recognising the id (404), the next fire provisions a replacement and stores it here.
        fireText:
          type: string
          minLength: 1
          description: Optional standing instruction prepended to every run's prompt — the trigger's base prompt. Lets two triggers on different repos steer their runs differently without changing the `/shipeasy-ops-work` task block.
      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 (secret). Sent as the Bearer for the Shipeasy MCP server handed to each run inline — never in the prompt text or the run env. 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`.
    CopilotTriggerRepo:
      type: object
      properties:
        owner:
          type: string
          minLength: 1
          description: GitHub repo owner.
        repo:
          type: string
          minLength: 1
          description: GitHub repo name.
        baseRef:
          type: string
          minLength: 1
          description: Optional base ref this repo's agent task branches from. Omit for the repo's default branch.
      required:
        - owner
        - repo
      additionalProperties: false
      description: One repo a Copilot trigger runs against, with the base branch its tasks branch from.
    CopilotTriggerConfig:
      type: object
      properties:
        owner:
          type: string
          minLength: 1
          description: '**First** GitHub repo owner. Together with `repo` forms the connector''s idempotency key (`owner/repo`), and both mirror `repos[0]` when `repos` is supplied.'
        repo:
          type: string
          minLength: 1
          description: GitHub repo name.
        baseRef:
          type: string
          minLength: 1
          description: Optional base ref the agent branches from. Mirrors `repos[0].baseRef`.
        repos:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CopilotTriggerRepo'
          description: Every repo this trigger runs against, each with its own base branch. GitHub's agent-tasks API is per-repo, so ONE fire starts one task per entry. Omit for a single-repo trigger, which is then described by `owner`/`repo`/`baseRef` alone; when supplied, the first entry must match them.
        projectId:
          type: string
          minLength: 1
          description: Shipeasy project id the run targets.
        fireText:
          type: string
          minLength: 1
          description: Optional standing instruction prepended to every run's prompt — the trigger's base prompt. Lets two triggers on different repos steer their runs differently without changing the `/shipeasy-ops-work` task block.
      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.
        fireText:
          type: string
          minLength: 1
          description: Optional standing instruction prepended to every run's prompt — the trigger's base prompt. Lets two triggers on different repos steer their runs differently without changing the `/shipeasy-ops-work` task block.
      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, except for the server-managed keys: the provisioned `agentId` is carried over (and dropped, so a replacement agent is provisioned, when `repoUrl`/`startingRef` change), as is the last-run pointer. `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.
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: Free-text note recording what the key is for (the service that holds it, the rotation owner, the ticket it was minted under). Display only — `null` unless someone set it via `PATCH /api/admin/keys/{id}`.
        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
        - description
        - 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: 160
          description: Optional human label. Programmatic (API) mints that omit it get an auto-generated descriptive name; dashboard mints may leave it blank. The cap is generous because provenance labels are composed, not typed — `shipeasy setup` mints keys named with the stack, package, date, and operator that produced them, which does not fit in a one-line-input budget.
        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
    UpdateKeyRequest:
      type: object
      description: |-
        Body for `PATCH /api/admin/keys/{id}`. Only the key's **label** is editable — `name` and `description`.

        Everything that gives a key its authority (`type`, `env`, `scopes`, `expires_at`) is fixed at mint: those are the isolation boundary the worker derives the read env and permissions from, so changing them would silently re-point a credential that is already deployed. Rotate instead — mint a replacement and revoke the old key.

        Omitted fields are left untouched; send `null` to clear one.
      properties:
        name:
          anyOf:
            - type: string
              minLength: 1
              maxLength: 160
            - type: 'null'
          description: New human label, or `null` to clear it. Same 160-char budget as create — provenance labels are composed, not typed.
        description:
          anyOf:
            - type: string
              minLength: 1
              maxLength: 500
            - type: 'null'
          description: New free-text note, or `null` to clear it.
      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
    PayloadTooLarge:
      description: The request body exceeded the intake's fixed size cap (16 KB).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            BAD_REQUEST:
              summary: Body too large
              value:
                error: Body too large
                code: BAD_REQUEST
    TooManyRequests:
      description: |-
        The public intake is rate-limited per (project, client IP). Back off and retry;
        the limit is a burst guard, not a quota, so a modest delay clears it.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            BAD_REQUEST:
              summary: Rate limited
              value:
                error: Too many requests
                code: BAD_REQUEST
    ServiceUnavailable:
      description: |-
        A backing store the endpoint needs is not bound in this environment. Transient
        and infrastructural — no stable `ErrorCode` is assigned, so `code` is omitted.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            UNAVAILABLE:
              summary: Storage unbound
              value:
                error: Unavailable
    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.'