@shipeasy/openapi 3.1.0 → 3.3.0

package/spec/paths/keys.yaml

@@ -32,6 +32,7 @@
                   expires_at: null
                   created_by_email: ana@example.com
                   name: production back-end
+                  description: Held by the checkout service; rotate with the quarterly credential sweep
                   scopes:
                     - gates:evaluate
                     - events:write
@@ -131,6 +132,84 @@
       - PLAN_LIMIT
     x-cli:
       name: create
+/api/admin/keys/{id}:
+  patch:
+    operationId: updateKey
+    summary: Update an API key's label
+    description: |-
+      Renames a key or re-notes what it is for. **Only `name` and `description` are editable** — everything that gives the key its authority (`type`, `env`, `scopes`, `expires_at`) is fixed at mint, because the worker derives the read env and permissions from the key itself. To change any of those, rotate: mint a replacement and revoke this one.
+
+      Omitted fields are left untouched; send `null` to clear one. Returns the updated key row. Revoked keys can still be relabelled (the audit trail outlives the credential). Returns `404` if no such key exists in the project.
+
+      **Use case:** A key minted by `shipeasy setup` carries an auto-composed provenance label — rename it to the service that actually holds it and note the rotation owner.
+    tags:
+      - API Keys
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque key id (UUID) returned by `create` / `list`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/keys.yaml#/UpdateKeyRequest
+          examples:
+            rename:
+              summary: Rename and note the key
+              value:
+                name: checkout-service · production
+                description: Held by the checkout service; rotation owner is the payments team
+            clearDescription:
+              summary: Clear the note
+              value:
+                description: null
+    responses:
+      "200":
+        description: Update an API key's label
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/keys.yaml#/KeyRecord
+            example:
+              id: 3f2a9b1c-7d4e-4a8f-9c2b-1e5d6f7a8b90
+              type: server
+              env: prod
+              created_at: 2026-05-09T16:01:22.000Z
+              revoked_at: null
+              expires_at: null
+              created_by_email: ana@example.com
+              name: checkout-service · production
+              description: Held by the checkout service; rotation owner is the payments team
+              scopes:
+                - gates:evaluate
+                - events:write
+              last4: a1b2
+      "400":
+        $ref: ../components/responses.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:
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: update
+      positional:
+        - id
 /api/admin/keys/{id}/revoke:
   post:
     operationId: revokeKey

package/spec/paths/killswitches.yaml

@@ -579,3 +579,99 @@
       name: set-value
       positional:
         - id
+/api/admin/killswitches/{id}/toggle:
+  post:
+    operationId: toggleKillswitch
+    summary: Toggle a killswitch or one of its switches
+    description: |-
+      Flips a killswitch on one environment and publishes a new version there. This is the one-call incident verb: it reads the current value, flips it, and publishes, so you don't have to fetch the killswitch first.
+
+      Every body field is optional, which is what makes the call widen cleanly:
+
+      - **Flip the killswitch** — `{}`. Flips the flat `value` on `prod`.
+      - **Flip one sub-switch** — `{ "switchKey": "eu_region" }`. Flips that entry on `prod`, creating it (from `false`) if it isn't in the map yet.
+      - **Set it idempotently** — `{ "switchKey": "eu_region", "value": true }`. Publishes exactly that value, so a retried call can't undo the first one. A `null` `value` means "flip", not "set to null".
+      - **Choose the environment** — add `"env": "staging"`. Omitted, `env` is `prod`.
+
+      The response reports both `previous` and `value`, so a caller that asked for a flip can see what it actually changed.
+
+      Prefer this over `PUT /{id}/value` and `PUT /{id}/switch` unless you specifically need those endpoints' unconditional set semantics.
+    tags:
+      - Killswitch
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: false
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/killswitches.yaml#/ToggleKillswitchRequest
+          examples:
+            flipOnProd:
+              summary: Flip the killswitch on prod
+              description: No body fields — reads the flat `value` on prod and publishes its opposite.
+              value: {}
+            flipOneSwitch:
+              summary: Flip one sub-switch on prod
+              description: Flips `switches.eu_region` on prod, leaving the flat `value` and every other key alone.
+              value:
+                switchKey: eu_region
+            setOneSwitch:
+              summary: Trip one sub-switch idempotently
+              description: Publishes `switches.eu_region = true` on prod whatever it was before — safe to retry.
+              value:
+                switchKey: eu_region
+                value: true
+            setOneSwitchOnStaging:
+              summary: Trip one sub-switch on a chosen env
+              description: The same idempotent set, published on staging instead of prod.
+              value:
+                switchKey: eu_region
+                value: true
+                env: staging
+    responses:
+      "200":
+        description: Toggle a killswitch or one of its switches
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/killswitches.yaml#/ToggleKillswitchResponse
+            example:
+              id: ksw_01j7w9d8h2k4m6n8p0q2r4s6t8
+              env: prod
+              switchKey: eu_region
+              previous: false
+              value: true
+              version: 7
+              published:
+                value: false
+                switches:
+                  eu_region: true
+      "400":
+        $ref: ../components/responses.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: toggle
+      positional:
+        - id

package/spec/paths/metrics.yaml

@@ -23,11 +23,14 @@
                 name: checkouts
                 folder: null
                 eventName: checkout_completed
-                query: count_users(checkout_completed)
+                query: count(checkout_completed)
                 queryIr:
-                  agg: { kind: count_users }
-                  metric: checkout_completed
-                  filters: []
+                  v: 2
+                  expr:
+                    node: agg
+                    event: checkout_completed
+                    agg: { kind: count }
+                    filters: []
                 direction: higher_better
                 version: 1
       "400":
@@ -61,7 +64,7 @@
 
       **Use cases**
 
-      - **Track an event** — `count_users(<event>)` for unique-user counts.
+      - **Track an event** — `count(<event>)` for event counts.
       - **Sum a value** — `sum(<event>, <label>)` for revenue / quantity metrics.
       - **Experiment success metric** — create the metric, then attach its id to an experiment.
     tags:
@@ -75,13 +78,13 @@
           schema:
             $ref: ../components/schemas/metrics.yaml#/CreateMetricRequest
           examples:
-            countUsers:
-              summary: Count unique users (DSL)
-              description: Unique users who completed checkout, expressed with the query DSL.
+            countEvents:
+              summary: Count an event (DSL)
+              description: Completed checkouts, expressed with the query DSL.
               value:
                 name: checkouts
                 event_name: checkout_completed
-                query: count_users(checkout_completed)
+                query: count(checkout_completed)
             sumRevenue:
               summary: Sum a value label (DSL)
               description: Total revenue, summing the `amount` property of the `purchase` event.
@@ -98,10 +101,13 @@
                 name: checkouts
                 event_name: checkout_completed
                 query_ir:
-                  agg:
-                    kind: count_users
-                  metric: checkout_completed
-                  filters: []
+                  v: 2
+                  expr:
+                    node: agg
+                    event: checkout_completed
+                    agg:
+                      kind: count
+                    filters: []
     responses:
       "201":
         description: Create a metric
@@ -179,10 +185,13 @@
               eventName: purchase
               query: sum(purchase, amount)
               queryIr:
-                agg: { kind: sum }
-                metric: purchase
-                valueLabel: amount
-                filters: []
+                v: 2
+                expr:
+                  node: agg
+                  event: purchase
+                  agg: { kind: sum }
+                  valueLabel: amount
+                  filters: []
               direction: higher_better
               winsorizePct: 99
               version: 1