@shipeasy/openapi 3.0.0 → 3.2.0

package/openapi.json

@@ -1001,6 +1001,393 @@
         }
       }
     },
+    "/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.\n\nA 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.\n\n**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.\n\nThis is the only whitelist call that can switch `attr` (`email` ⇄ `user_id`) or clear the block: `entries: []` removes the whitelist from the gate entirely.\n\n**Use cases**\n\n- **Pin an exact list** — `{ \"entries\": [\"alice@acme.dev\", \"bob@acme.dev\"] }`.\n- **Switch to user ids** — `{ \"attr\": \"user_id\", \"entries\": [\"usr_123\"] }`.\n- **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.\n\nAdding 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.\n\n**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.\n\nRemoving the last entry leaves an empty whitelist block in place; to drop the block itself use `PUT` with `entries: []`.\n\n**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",
@@ -4316,15 +4703,115 @@
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/UnsetKillswitchSwitchRequest"
+                "$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.\n\nUse this to trip (or untrip) a killswitch on one environment without replacing its per-key overrides.\n\n**Use cases**\n\n- **Trip on prod** — `{ \"env\": \"prod\", \"value\": true }`.\n- **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": {
-                "removeRegion": {
-                  "summary": "Remove eu_region from prod",
-                  "description": "Drops the `eu_region` override on prod so the flat `value` applies again.",
+                "tripProd": {
+                  "summary": "Trip on prod",
+                  "description": "Publishes `value: true` on prod only, bumping that env's version.",
                   "value": {
                     "env": "prod",
-                    "switchKey": "eu_region"
+                    "value": true
+                  }
+                },
+                "untripProd": {
+                  "summary": "Untrip on prod",
+                  "description": "Publishes `value: false` on prod only.",
+                  "value": {
+                    "env": "prod",
+                    "value": false
                   }
                 }
               }
@@ -4333,17 +4820,22 @@
         },
         "responses": {
           "200": {
-            "description": "Remove one switch entry",
+            "description": "Set the flat value on one env",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/UnsetKillswitchSwitchResponse"
+                  "$ref": "#/components/schemas/SetKillswitchValueResponse"
                 },
                 "example": {
                   "id": "ksw_01j7w9d8h2k4m6n8p0q2r4s6t8",
                   "env": "prod",
-                  "switchKey": "eu_region",
-                  "removed": true
+                  "version": 6,
+                  "published": {
+                    "value": true,
+                    "switches": {
+                      "eu_region": true
+                    }
+                  }
                 }
               }
             }
@@ -4371,21 +4863,22 @@
           "BAD_REQUEST",
           "UNAUTHORIZED",
           "FORBIDDEN",
-          "NOT_FOUND"
+          "NOT_FOUND",
+          "VALIDATION"
         ],
         "x-cli": {
-          "name": "unset",
+          "name": "set-value",
           "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.\n\nUse this to trip (or untrip) a killswitch on one environment without replacing its per-key overrides.\n\n**Use cases**\n\n- **Trip on prod** — `{ \"env\": \"prod\", \"value\": true }`.\n- **Untrip on prod** — `{ \"env\": \"prod\", \"value\": false }`.",
+    "/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.\n\nEvery body field is optional, which is what makes the call widen cleanly:\n\n- **Flip the killswitch** — `{}`. Flips the flat `value` on `prod`.\n- **Flip one sub-switch** — `{ \"switchKey\": \"eu_region\" }`. Flips that entry on `prod`, creating it (from `false`) if it isn't in the map yet.\n- **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\".\n- **Choose the environment** — add `\"env\": \"staging\"`. Omitted, `env` is `prod`.\n\nThe response reports both `previous` and `value`, so a caller that asked for a flip can see what it actually changed.\n\nPrefer this over `PUT /{id}/value` and `PUT /{id}/switch` unless you specifically need those endpoints' unconditional set semantics.",
         "tags": [
           "Killswitch"
         ],
@@ -4404,27 +4897,40 @@
           }
         ],
         "requestBody": {
-          "required": true,
+          "required": false,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/SetKillswitchValueRequest"
+                "$ref": "#/components/schemas/ToggleKillswitchRequest"
               },
               "examples": {
-                "tripProd": {
-                  "summary": "Trip on prod",
-                  "description": "Publishes `value: true` on prod only, bumping that env's version.",
+                "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": {
-                    "env": "prod",
+                    "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
                   }
                 },
-                "untripProd": {
-                  "summary": "Untrip on prod",
-                  "description": "Publishes `value: false` on prod only.",
+                "setOneSwitchOnStaging": {
+                  "summary": "Trip one sub-switch on a chosen env",
+                  "description": "The same idempotent set, published on staging instead of prod.",
                   "value": {
-                    "env": "prod",
-                    "value": false
+                    "switchKey": "eu_region",
+                    "value": true,
+                    "env": "staging"
                   }
                 }
               }
@@ -4433,18 +4939,21 @@
         },
         "responses": {
           "200": {
-            "description": "Set the flat value on one env",
+            "description": "Toggle a killswitch or one of its switches",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/SetKillswitchValueResponse"
+                  "$ref": "#/components/schemas/ToggleKillswitchResponse"
                 },
                 "example": {
                   "id": "ksw_01j7w9d8h2k4m6n8p0q2r4s6t8",
                   "env": "prod",
-                  "version": 6,
+                  "switchKey": "eu_region",
+                  "previous": false,
+                  "value": true,
+                  "version": 7,
                   "published": {
-                    "value": true,
+                    "value": false,
                     "switches": {
                       "eu_region": true
                     }
@@ -4480,7 +4989,7 @@
           "VALIDATION"
         ],
         "x-cli": {
-          "name": "set-value",
+          "name": "toggle",
           "positional": [
             "id"
           ]
@@ -6939,7 +7448,7 @@
             "name": "status",
             "in": "query",
             "required": false,
-            "description": "Filter by lifecycle status, or `all`. The human-gated holding states (`pending_approval`, `triage`) are excluded from `all`/default and returned only when requested as the exact status.",
+            "description": "Filter by lifecycle status, or `all`. The human-gated holding state (`pending_approval`) is excluded from `all`/default and returned only when requested as the exact status.",
             "schema": {
               "anyOf": [
                 {
@@ -7016,35 +7525,273 @@
           "403": {
             "$ref": "#/components/responses/Forbidden"
           },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
+          "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.\n\n**Use cases**\n\n- **File a bug** — `{ \"type\": \"bug\", \"title\": \"Checkout 500s on Safari\", \"stepsToReproduce\": \"…\" }`.\n- **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.\n\nThree gates decide whether a ticket is filed, and nothing else the caller sends can widen them:\n\n1. the key is a `client` key carrying the `tickets:public_create` scope,\n2. the key's project has public ticket creation enabled, and\n3. the item is filed as `pending_approval` — parked out of the work queue until a human promotes it in the dashboard.\n\nThe 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.\n\nThis endpoint is served by the Shipeasy **edge worker** (`api.shipeasy.ai`), not the admin API — see `servers` below.\n\n**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"
           },
-          "409": {
-            "$ref": "#/components/responses/Conflict"
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
           },
-          "422": {
-            "$ref": "#/components/responses/UnprocessableEntity"
+          "503": {
+            "$ref": "#/components/responses/ServiceUnavailable"
           }
         },
         "x-error-codes": [
           "BAD_REQUEST",
           "UNAUTHORIZED",
-          "FORBIDDEN"
+          "FORBIDDEN",
+          "VALIDATION"
         ],
         "x-cli": {
-          "name": "list"
+          "hidden": true
         }
-      },
+      }
+    },
+    "/ops/feature-request": {
       "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.\n\n**Use cases**\n\n- **File a bug** — `{ \"type\": \"bug\", \"title\": \"Checkout 500s on Safari\", \"stepsToReproduce\": \"…\" }`.\n- **File a feature request** — `{ \"type\": \"feature_request\", \"title\": \"Dark mode\", \"priority\": \"nice_to_have\" }`.",
+        "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.\n\nThe 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.\n\nThis endpoint is served by the Shipeasy **edge worker** (`api.shipeasy.ai`), not the admin API — see `servers` below.\n\n**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"
         ],
-        "parameters": [
+        "servers": [
           {
-            "$ref": "#/components/parameters/ProjectId"
+            "url": "https://api.shipeasy.ai",
+            "description": "Shipeasy edge worker (production)"
+          },
+          {
+            "url": "http://localhost:8787",
+            "description": "Local `wrangler dev`"
+          }
+        ],
+        "security": [
+          {
+            "clientSdkKey": []
           }
         ],
         "requestBody": {
@@ -7052,28 +7799,23 @@
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/CreateOpsItemRequest"
+                "$ref": "#/components/schemas/CreatePublicFeatureRequestRequest"
               },
               "examples": {
-                "bug": {
-                  "summary": "File a bug report",
+                "minimal": {
+                  "summary": "Just a title",
                   "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"
+                    "title": "Dark mode for the dashboard"
                   }
                 },
-                "featureRequest": {
-                  "summary": "File a feature request",
+                "full": {
+                  "summary": "A full 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"
+                    "priority": "nice_to_have",
+                    "reporterEmail": "alice@acme.dev"
                   }
                 }
               }
@@ -7081,16 +7823,30 @@
           }
         },
         "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 queue item",
+            "description": "File a feature request",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/CreateOpsItemResponse"
+                  "$ref": "#/components/schemas/CreatePublicTicketResponse"
                 },
                 "example": {
                   "id": "fb_01j7w8a1b2c3d4e5f6g7h8i9j0",
-                  "number": 7
+                  "number": 8
                 }
               }
             }
@@ -7104,48 +7860,24 @@
           "403": {
             "$ref": "#/components/responses/Forbidden"
           },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
+          "413": {
+            "$ref": "#/components/responses/PayloadTooLarge"
           },
-          "409": {
-            "$ref": "#/components/responses/Conflict"
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
           },
-          "422": {
-            "$ref": "#/components/responses/UnprocessableEntity"
+          "503": {
+            "$ref": "#/components/responses/ServiceUnavailable"
           }
         },
         "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"
-              }
-            }
-          ]
+          "hidden": true
         }
       }
     },
@@ -12187,6 +12919,12 @@
         "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.\n\nClient 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.\n\nThe key must additionally carry the `tickets:public_create` scope, and its project must have public ticket creation enabled."
       }
     },
     "parameters": {
@@ -13683,6 +14421,118 @@
         },
         "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": {
@@ -16713,8 +17563,96 @@
           "id": {
             "type": "string"
           },
-          "env": {
-            "$ref": "#/components/schemas/Env"
+          "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:\n\n- `{}` — flip the flat value on prod.\n- `{ \"switchKey\": \"eu_region\" }` — flip that sub-switch on prod.\n- `{ \"switchKey\": \"eu_region\", \"value\": true }` — set that sub-switch on prod, idempotently.\n- `{ \"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",
@@ -16729,6 +17667,9 @@
         "required": [
           "id",
           "env",
+          "switchKey",
+          "previous",
+          "value",
           "version",
           "published"
         ],
@@ -19272,8 +20213,6 @@
         "enum": [
           "open",
           "pending_approval",
-          "triage",
-          "triaged",
           "investigating_by_ai",
           "in_progress",
           "blocked",
@@ -19281,7 +20220,7 @@
           "resolved",
           "wont_fix"
         ],
-        "description": "Lifecycle status of a queue item. The working flow is `open` → `triaged` → `in_progress` → `ready_for_qa` → `resolved` (or `wont_fix`, terminal from any earlier stage). `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. Two human-gated holding states park an item OUT of the work queue until a human promotes it to `open` in the dashboard, so `GET /api/admin/ops` excludes them under `status=all`/default and returns them only when requested as an exact `status`: `pending_approval` is the pre-open approval gate for untriaged inbound (e.g. connector requests filed from a customer's connectors panel) so it never gets auto-implemented — approving = flipping the status to `open`; `triage` is the onboarding-help bucket — questions/errors submitted to the \"Stuck in onboarding?\" assistant are funnelled into the platform project as `triage` rows so the team can see where people get stuck and follow up, keeping onboarding chatter out of the work queue until a human moves real items to `open`."
+        "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",
@@ -19297,17 +20236,16 @@
         "type": "string",
         "enum": [
           "pr_ready",
+          "pr_merged",
           "investigated",
           "detected",
           "question",
           "ready_for_qa",
           "pending_approval",
-          "needs_triage",
           "working",
-          "triaged_low",
           "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 `needs_triage`/`backlog` (by priority) or `investigated`/`detected` for auto-filed error/alert tickets. `triaged_low` marks a low-signal item AI has looked at but that nothing is moving. Absent on rows filed before the field existed — consumers should treat a missing value as \"derive from the other fields\"."
+        "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` is derived client-side by scanning the linked pull request on GitHub, so it is accepted on write but not currently emitted by the API. Absent on rows filed before the field existed — consumers should treat a missing value as \"derive from the other fields\"."
       },
       "OpsBrowserContext": {
         "type": "object",
@@ -20497,42 +21435,382 @@
             },
             "createdAt": {
               "type": "string",
-              "description": "ISO-8601 creation timestamp."
+              "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"
             },
-            "updatedAt": {
-              "type": "string",
-              "description": "ISO-8601 last-update timestamp."
-            }
+            "default": [],
+            "description": "Emails of teammates to subscribe to this item's Slack pings at creation."
           },
-          "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."
+          "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."
+          }
         },
-        "description": "A page of queue items, newest first."
+        "required": [
+          "type",
+          "title"
+        ],
+        "additionalProperties": false,
+        "description": "Feature-request-kind fields for `POST /api/admin/ops` (sent with `type: feature_request`)."
       },
-      "CreateBugRequest": {
+      "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": {
-          "type": {
+          "id": {
             "type": "string",
-            "enum": [
-              "bug"
-            ],
-            "description": "Discriminator — files a bug."
+            "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,
@@ -20678,22 +21956,36 @@
           }
         },
         "required": [
-          "type",
           "title"
         ],
         "additionalProperties": false,
-        "description": "Bug-kind fields for `POST /api/admin/ops` (sent with `type: bug`)."
+        "description": "Body for `POST /ops/bug`. The same bug fields as `CreateBugRequest`, minus the `type` discriminator — the path already says what is being filed."
       },
-      "CreateFeatureRequestRequest": {
+      "CreatePublicTicketResponse": {
         "type": "object",
         "properties": {
-          "type": {
+          "id": {
             "type": "string",
-            "enum": [
-              "feature_request"
-            ],
-            "description": "Discriminator — files a feature request."
+            "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,
@@ -20821,54 +22113,10 @@
           }
         },
         "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`."
+        "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",
@@ -25745,8 +26993,8 @@
           "name": {
             "type": "string",
             "minLength": 1,
-            "maxLength": 80,
-            "description": "Optional human label. Programmatic (API) mints that omit it get an auto-generated descriptive name; dashboard mints may leave it blank."
+            "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",
@@ -26093,6 +27341,62 @@
           }
         }
       },
+      "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;\nthe 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\nand 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\nthe endpoint delegates to (e.g. a connector's Slack/GitHub/cloud-agent dispatch)\nfailed. The failure is upstream of this API, not a client error. No stable\n`ErrorCode` is assigned to upstream failures, so `code` is omitted.",
         "content": {