@shipeasy/openapi 3.1.0 → 3.3.0

package/spec/components/schemas/projects.yaml

@@ -171,6 +171,12 @@ GetCurrentProjectResponse:
         - 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
@@ -250,6 +256,8 @@ GetCurrentProjectResponse:
     - moduleUser
     - moduleEvents
     - allowPublicTickets
+    - errorAutocloseDays
+    - errorTicketMinOccurrences
     - slug
     - logo
     - defaultEnv
@@ -462,5 +470,15 @@ UpdateProjectRequest:
       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."

package/spec/components/schemas/tags.yaml

@@ -0,0 +1,91 @@
+TaggableEntityType:
+  type: string
+  enum:
+    - ops
+    - flag
+    - config
+    - killswitch
+    - metric
+    - error
+    - alert_rule
+    - experiment
+  description: >-
+    The kind of item a tag set hangs off: `ops` (any queue item — bug, feature
+    request, error/alert/measure-plan ticket), `flag` (feature gate), `config`
+    (dynamic config), `killswitch`, `metric`, `error` (tracked error group),
+    `alert_rule`, or `experiment`.
+TagName:
+  type: string
+  minLength: 1
+  maxLength: 64
+  description: A tag name. Trimmed; matched case-insensitively against the project's existing tags.
+Tag:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Stable opaque tag id.
+    name:
+      type: string
+      description: Display name — also the tag's identity, unique case-insensitively within the project.
+  required:
+    - id
+    - name
+  additionalProperties: false
+ListTagsResponse:
+  type: array
+  items:
+    $ref: "#/Tag"
+  description: The project's tags, sorted by name.
+EntityTagsResponse:
+  type: object
+  properties:
+    entityType:
+      $ref: "#/TaggableEntityType"
+    entityId:
+      type: string
+      description: The item's canonical id (the handle you passed, resolved).
+    tags:
+      type: array
+      items:
+        type: string
+      description: The tag names now attached to the item, sorted by name.
+  required:
+    - entityType
+    - entityId
+    - tags
+  additionalProperties: false
+SetEntityTagsRequest:
+  type: object
+  properties:
+    tags:
+      type: array
+      maxItems: 50
+      items:
+        $ref: "#/TagName"
+      description: >-
+        The complete tag set the item should carry — tags not listed are
+        detached. Names are get-or-created (a new name mints a project tag),
+        deduped case-insensitively; `[]` clears every tag.
+  required:
+    - tags
+  additionalProperties: false
+UpdateEntityTagsRequest:
+  type: object
+  properties:
+    add:
+      type: array
+      maxItems: 50
+      items:
+        $ref: "#/TagName"
+      default: []
+      description: Tag names to attach (get-or-created by name, case-insensitive). Already-attached names are a no-op.
+    remove:
+      type: array
+      maxItems: 50
+      items:
+        $ref: "#/TagName"
+      default: []
+      description: Tag names to detach (case-insensitive). Names the item doesn't carry are a no-op. A name in both lists is removed.
+  additionalProperties: false
+  description: Incremental tag edit — pass `add`, `remove`, or both. Every other tag on the item is left as is.

package/spec/openapi-sdk.yaml

@@ -0,0 +1,86 @@
+# The SERVER-SDK surface of the admin API — a second root over the same
+# `paths/` and `components/schemas/` tree that `openapi.yaml` bundles.
+#
+# WHY A SECOND ROOT. The CLI and MCP consume the FULL spec (127 operations);
+# the published server SDKs ship a deliberately tiny opt-in `AdminClient`, and
+# vendoring the whole contract into eight repos bloated each generated client
+# into the megabytes for operations nobody called. This file IS that smaller
+# contract, declared rather than derived: `paths` below lists exactly the
+# operations the SDKs expose, and `redocly bundle` pulls in only the schemas
+# those operations transitively reference.
+#
+# WHY IT'S EXACT. Every path listed here is a dedicated, single-purpose route,
+# so a path item never drags in a method the SDK shouldn't have. That is the
+# reason the SDK-facing endpoints were built as their own paths instead of
+# extra query/discriminator modes on the generic CRUD routes.
+#
+# ADDING AN OPERATION is one `$ref` here — then `pnpm gen` in this package and
+# `pnpm sdk:spec:regen` in the monorepo, and commit the regenerated client
+# inside each SDK submodule. A monorepo pre-commit hook blocks any commit that
+# changes this contract while a vendored copy is stale.
+#
+# DELIBERATELY ABSENT, so nobody re-adds them by accident: everything else.
+# Listing, generic CRUD, key minting, projects, connectors, i18n, errors,
+# alerts, metrics, events, experiments, universes, templates, attributes, and
+# the AI-agent working seam (ack / link-pr / investigations) all stay reachable
+# through the CLI and MCP, which read `openapi.yaml`.
+openapi: 3.2.0
+info:
+  title: Shipeasy Admin API (server-SDK surface)
+  version: 2.0.0
+  description: |-
+    The slice of the Shipeasy admin API that the published server SDKs expose as their optional `AdminClient`. Authenticate with an admin SDK key (`Authorization: Bearer sdk_admin_…`) and scope every request to a project via the `X-Project-Id` header.
+
+    Three capabilities, nothing else:
+
+    - **File a public ticket** — a bug or a feature request onto the project's ops queue.
+    - **Toggle a kill switch** — flip the switch itself, or one of its named sub-switches, on one environment.
+    - **Manage a flag's whitelist** — read, replace, add to, or remove from the allowlist that admits specific identities ahead of every targeting rule.
+
+    Everything else in the admin API is reachable through the Shipeasy CLI and MCP server, which speak the complete contract (`openapi.yaml`).
+  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: Flags
+    description: A feature gate's whitelist — the always-first allowlist that admits named identities before any targeting rule or percentage rollout runs.
+  - name: Killswitch
+    description: Per-env boolean overrides for incident response. `toggle` reads the current value and publishes its opposite in one call, on the flat value or on one named sub-switch.
+  - name: Ops
+    description: The public ticket queue — filing a bug or a feature request, which also fires the project's GitHub/Slack connectors.
+paths:
+  /ops/bug:
+    $ref: ./paths/ops.yaml#/~1ops~1bug
+  /ops/feature-request:
+    $ref: ./paths/ops.yaml#/~1ops~1feature-request
+  /api/admin/killswitches/{id}/toggle:
+    $ref: ./paths/killswitches.yaml#/~1api~1admin~1killswitches~1{id}~1toggle
+  /api/admin/gates/{id}/whitelist:
+    $ref: ./paths/gates.yaml#/~1api~1admin~1gates~1{id}~1whitelist
+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.

package/spec/openapi.yaml

@@ -218,6 +218,24 @@ tags:
       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: Questions
+    parent: Ops
+    description: |-
+      Structured questions an agent asks the team about a queue item — the
+      `AskUserQuestion` shape: a short `header`, the `question`, 2–4 `options`
+      (label + description), and `multiSelect` for checkboxes instead of radios.
+      Every question also accepts a free-text "Other" answer. Open questions sit
+      at the very top of the item's detail panel and mark the row in the queue.
+
+      **Asking.** `ask` posts 1–4 questions at once. Several agents (or several
+      runs) may have questions open on the same item at the same time.
+
+      **Getting the answer back.** `delivery: resume` (the default for a run
+      launched through a trigger connector) re-fires that same agent on the
+      item once every question its run asked is answered, continuing the same
+      run record with the answers in the prompt. `delivery: poll` (the default
+      for a live, connector-less session such as Claude Code in a terminal)
+      fires nothing — call `list` until the status reads `completed`.
   - name: Projects
     description: |-
       Projects: the account-level container every other resource is scoped to.
@@ -260,6 +278,19 @@ tags:
       Continue) schedule on their own surface — typically a GitHub Actions
       `schedule:` cron running the platform's headless CLI with the shared
       trigger prompt.
+  - name: Tags
+    description: |-
+      Tags: free-form, project-scoped labels any item can carry — queue items
+      (bugs, feature requests, error/alert tickets), flags, configs, kill
+      switches, metrics, tracked errors, alert rules, and experiments all share
+      one tag roster.
+
+      **Identity.** A tag is its name, unique case-insensitively per project. A
+      tag is born the first time it's attached — there is no separate create.
+
+      **Addressing.** An item is named by `entityType` + its handle (an ops
+      item's number, a resource's name, or any id). `set` replaces the full tag
+      set; `update` adds/removes names incrementally.
   - name: Connectors
     description: |-
       Outbound integrations: the per-project destinations feedback + trigger
@@ -282,6 +313,8 @@ paths:
     $ref: ./paths/gates.yaml#/~1api~1admin~1gates~1{id}~1disable
   /api/admin/gates/{id}/activity:
     $ref: ./paths/gates.yaml#/~1api~1admin~1gates~1{id}~1activity
+  /api/admin/gates/{id}/whitelist:
+    $ref: ./paths/gates.yaml#/~1api~1admin~1gates~1{id}~1whitelist
   /api/admin/experiments:
     $ref: ./paths/experiments.yaml#/~1api~1admin~1experiments
   /api/admin/experiments/{id}:
@@ -322,6 +355,8 @@ paths:
     $ref: ./paths/killswitches.yaml#/~1api~1admin~1killswitches~1{id}~1switch
   /api/admin/killswitches/{id}/value:
     $ref: ./paths/killswitches.yaml#/~1api~1admin~1killswitches~1{id}~1value
+  /api/admin/killswitches/{id}/toggle:
+    $ref: ./paths/killswitches.yaml#/~1api~1admin~1killswitches~1{id}~1toggle
   /api/admin/universes:
     $ref: ./paths/universes.yaml#/~1api~1admin~1universes
   /api/admin/universes/{id}:
@@ -352,6 +387,10 @@ paths:
     $ref: ./paths/events.yaml#/~1api~1admin~1events~1{id}~1approve
   /api/admin/ops:
     $ref: ./paths/ops.yaml#/~1api~1admin~1ops
+  /ops/bug:
+    $ref: ./paths/ops.yaml#/~1ops~1bug
+  /ops/feature-request:
+    $ref: ./paths/ops.yaml#/~1ops~1feature-request
   /api/admin/ops/{handle}:
     $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}
   /api/admin/ops/{handle}/link-pr:
@@ -362,6 +401,12 @@ paths:
     $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1investigation
   /api/admin/ops/{handle}/investigation/{investigationId}:
     $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1investigation~1{investigationId}
+  /api/admin/ops/{handle}/questions:
+    $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1questions
+  /api/admin/ops/{handle}/questions/{questionId}/answer:
+    $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1questions~1{questionId}~1answer
+  /api/admin/ops/{handle}/questions/{questionId}/cancel:
+    $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1questions~1{questionId}~1cancel
   /api/admin/agent-profiles:
     $ref: ./paths/ops.yaml#/~1api~1admin~1agent-profiles
   /api/admin/ops/{handle}/comments:
@@ -426,10 +471,16 @@ paths:
     $ref: ./paths/connectors.yaml#/~1api~1admin~1connectors~1trigger
   /api/admin/keys:
     $ref: ./paths/keys.yaml#/~1api~1admin~1keys
+  /api/admin/keys/{id}:
+    $ref: ./paths/keys.yaml#/~1api~1admin~1keys~1{id}
   /api/admin/keys/{id}/revoke:
     $ref: ./paths/keys.yaml#/~1api~1admin~1keys~1{id}~1revoke
   /api/admin/search:
     $ref: ./paths/search.yaml#/~1api~1admin~1search
+  /api/admin/tags:
+    $ref: ./paths/tags.yaml#/~1api~1admin~1tags
+  /api/admin/tags/{entityType}/{entityId}:
+    $ref: ./paths/tags.yaml#/~1api~1admin~1tags~1{entityType}~1{entityId}
 components:
   securitySchemes:
     bearerSdkKey:
@@ -437,3 +488,13 @@ components:
       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.

package/spec/paths/alerts.yaml

@@ -5,7 +5,9 @@
     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`.
 
-      Fired alerts are raised 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`.
+      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:
@@ -89,7 +91,7 @@
     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. A resolved alert re-fires (as the same row, re-activated) if its condition is raised again.
+      - **`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.
 
@@ -106,7 +108,7 @@
       - name: id
         in: path
         required: true
-        description: Stable opaque alert id (`al_…`).
+        description: Stable opaque instance id — the same id as the `alert` ops item this instance is.
         schema:
           $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:

package/spec/paths/gates.yaml

@@ -601,3 +601,285 @@
       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.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque gate id (`gate_…`) or the gate's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Read a gate's whitelist
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/gates.yaml#/GetGateWhitelistResponse
+            example:
+              id: gate_01j7w8a1b2c3d4e5f6g7h8i9j0
+              name: new_checkout
+              attr: email
+              entries:
+                - alice@acme.dev
+                - bob@acme.dev
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: 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.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque gate id (`gate_…`) or the gate's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/gates.yaml#/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/gates.yaml#/SetGateWhitelistResponse
+            example:
+              id: gate_01j7w8a1b2c3d4e5f6g7h8i9j0
+              name: new_checkout
+              attr: email
+              entries:
+                - alice@acme.dev
+                - bob@acme.dev
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: 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.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque gate id (`gate_…`) or the gate's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/gates.yaml#/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/gates.yaml#/AddToGateWhitelistResponse
+            example:
+              id: gate_01j7w8a1b2c3d4e5f6g7h8i9j0
+              name: new_checkout
+              attr: email
+              entries:
+                - alice@acme.dev
+                - bob@acme.dev
+                - carol@acme.dev
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - 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.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque gate id (`gate_…`) or the gate's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/gates.yaml#/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/gates.yaml#/RemoveFromGateWhitelistResponse
+            example:
+              id: gate_01j7w8a1b2c3d4e5f6g7h8i9j0
+              name: new_checkout
+              attr: email
+              entries:
+                - alice@acme.dev
+                - bob@acme.dev
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: whitelist-remove
+      positional:
+        - id

package/spec/paths/i18n.yaml

@@ -128,11 +128,12 @@
       - name: limit
         in: query
         required: false
-        description: Max keys to return (1–500).
+        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