@shipeasy/openapi 2.1.0 → 2.2.0

package/openapi.yaml

@@ -21,9 +21,26 @@ security:
   - bearerSdkKey: []
 tags:
   - name: Release
-    summary: Feature delivery
+    summary: Feature delivery — flags, kill switches, dynamic configs, A/B experiments, and the universes they bucket in.
     kind: nav
-    description: Flags, kill switches, dynamic configs, experiments, and the universes they bucket in — the feature-delivery surface.
+    description: |-
+      Release: the feature-delivery surface. One roof over the five resources
+      that decide which code path a user gets — feature gates (flags), kill
+      switches, dynamic configs, A/B/n experiments, and the universes that bucket
+      them — each exposed as its own subcommand group.
+
+      **Groups.**
+      - `flags` — boolean feature gates: AND-combined targeting rules + a percentage rollout (basis points), evaluated on the SDK hot path.
+      - `killswitch` (`ks`) — per-env boolean overrides for incident response; no rules, no rollout, versioned per environment.
+      - `configs` — JSON-Schema-validated structured values with a draft → publish workflow, delivered per environment.
+      - `experiments` — randomised A/B/n assignment plus the analysis pipeline (t-test, sequential testing, SRM detection); `universes` hold the shared bucketing space and holdouts the experiments draw from.
+
+      **Delivery model.** Every write rebuilds the project's KV blob and purges
+      the CDN — SDKs poll at the plan interval and never touch the database on
+      the hot path. The destructive verb is `archive` (soft-delete), never
+      `delete`.
+
+      Run `shipeasy release <group> --help` for the full contract of each group.
   - name: Flags
     parent: Release
     description: |-
@@ -229,6 +246,7 @@ paths:
         - $ref: '#/components/parameters/ProjectId'
         - $ref: '#/components/parameters/PaginationLimit'
         - $ref: '#/components/parameters/PaginationCursor'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List feature gates
@@ -380,6 +398,23 @@ paths:
               example:
                 id: gat_01j7w7m9q4hxbf6npe6s9zr3vc
                 name: checkout_v2
+          links:
+            UpdateGate:
+              operationId: updateGate
+              parameters:
+                id: $response.body#/id
+            EnableGate:
+              operationId: enableGate
+              parameters:
+                id: $response.body#/id
+            DisableGate:
+              operationId: disableGate
+              parameters:
+                id: $response.body#/id
+            DeleteGate:
+              operationId: deleteGate
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -428,7 +463,7 @@ paths:
           required: true
           description: Stable opaque gate id (`gat_…`) or the gate's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -534,7 +569,7 @@ paths:
           required: true
           description: Stable opaque gate id (`gat_…`) or the gate's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Delete a feature gate
@@ -583,9 +618,9 @@ paths:
           required: true
           description: Stable opaque gate id (`gat_…`) or the gate's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
-        '201':
+        '200':
           description: Enable a gate
           content:
             application/json:
@@ -633,9 +668,9 @@ paths:
           required: true
           description: Stable opaque gate id (`gat_…`) or the gate's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
-        '201':
+        '200':
           description: Disable a gate
           content:
             application/json:
@@ -680,6 +715,13 @@ paths:
         - $ref: '#/components/parameters/ProjectId'
         - $ref: '#/components/parameters/PaginationLimit'
         - $ref: '#/components/parameters/PaginationCursor'
+        - name: status
+          in: query
+          required: false
+          description: Filter by lifecycle status. Pass `archived` to return the archive tab; any other value (or omitting it) returns the non-archived experiments.
+          schema:
+            type: string
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List experiments
@@ -827,6 +869,31 @@ paths:
               example:
                 id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
                 name: checkout_button_color
+          links:
+            GetExperiment:
+              operationId: getExperiment
+              parameters:
+                id: $response.body#/id
+            UpdateExperiment:
+              operationId: updateExperiment
+              parameters:
+                id: $response.body#/id
+            SetExperimentMetrics:
+              operationId: setExperimentMetrics
+              parameters:
+                id: $response.body#/id
+            SetExperimentStatus:
+              operationId: setExperimentStatus
+              parameters:
+                id: $response.body#/id
+            ReanalyzeExperiment:
+              operationId: reanalyzeExperiment
+              parameters:
+                id: $response.body#/id
+            DeleteExperiment:
+              operationId: deleteExperiment
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -869,7 +936,7 @@ paths:
           required: true
           description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get one experiment
@@ -949,7 +1016,7 @@ paths:
           required: true
           description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -1034,7 +1101,7 @@ paths:
           required: true
           description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Delete an experiment
@@ -1095,7 +1162,7 @@ paths:
           required: true
           description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -1124,7 +1191,7 @@ paths:
                 value:
                   status: draft
       responses:
-        '201':
+        '200':
           description: Transition experiment status
           content:
             application/json:
@@ -1190,7 +1257,7 @@ paths:
           required: true
           description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -1213,7 +1280,7 @@ paths:
                 value:
                   metrics: []
       responses:
-        '201':
+        '200':
           description: Attach metrics
           content:
             application/json:
@@ -1267,7 +1334,7 @@ paths:
           required: true
           description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get analysis results
@@ -1336,7 +1403,7 @@ paths:
           required: true
           description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
         - name: metric
           in: query
           required: false
@@ -1410,9 +1477,9 @@ paths:
           required: true
           description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
-        '201':
+        '200':
           description: Re-queue analysis
           content:
             application/json:
@@ -1457,6 +1524,7 @@ paths:
         - $ref: '#/components/parameters/ProjectId'
         - $ref: '#/components/parameters/PaginationLimit'
         - $ref: '#/components/parameters/PaginationCursor'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List dynamic configs
@@ -1605,6 +1673,23 @@ paths:
               example:
                 id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
                 name: pricing.tiers
+          links:
+            GetConfig:
+              operationId: getConfig
+              parameters:
+                id: $response.body#/id
+            UpdateConfig:
+              operationId: updateConfig
+              parameters:
+                id: $response.body#/id
+            PublishConfigDraft:
+              operationId: publishConfigDraft
+              parameters:
+                id: $response.body#/id
+            DeleteConfig:
+              operationId: deleteConfig
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -1644,7 +1729,7 @@ paths:
           required: true
           description: Stable opaque config id (`cfg_…`) or the config's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get one config
@@ -1746,7 +1831,7 @@ paths:
           required: true
           description: Stable opaque config id (`cfg_…`) or the config's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -1822,7 +1907,7 @@ paths:
           required: true
           description: Stable opaque config id (`cfg_…`) or the config's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Delete a dynamic config
@@ -1872,7 +1957,7 @@ paths:
           required: true
           description: Stable opaque config id (`cfg_…`) or the config's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -1940,7 +2025,7 @@ paths:
           required: true
           description: Stable opaque config id (`cfg_…`) or the config's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -2002,7 +2087,7 @@ paths:
           required: true
           description: Stable opaque config id (`cfg_…`) or the config's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -2021,7 +2106,7 @@ paths:
                 value:
                   env: prod
       responses:
-        '201':
+        '200':
           description: Publish a draft
           content:
             application/json:
@@ -2071,7 +2156,7 @@ paths:
           required: true
           description: Stable opaque config id (`cfg_…`) or the config's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
         - name: limit
           in: query
           required: false
@@ -2135,7 +2220,7 @@ paths:
           required: true
           description: Stable opaque config id (`cfg_…`) or the config's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -2201,6 +2286,7 @@ paths:
         - $ref: '#/components/parameters/ProjectId'
         - $ref: '#/components/parameters/PaginationLimit'
         - $ref: '#/components/parameters/PaginationCursor'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List killswitches
@@ -2303,6 +2389,27 @@ paths:
               example:
                 id: ksw_01j7w9d8h2k4m6n8p0q2r4s6t8
                 name: payments.checkout
+          links:
+            GetKillswitch:
+              operationId: getKillswitch
+              parameters:
+                id: $response.body#/id
+            UpdateKillswitch:
+              operationId: updateKillswitch
+              parameters:
+                id: $response.body#/id
+            SetKillswitchSwitch:
+              operationId: setKillswitchSwitch
+              parameters:
+                id: $response.body#/id
+            SetKillswitchValue:
+              operationId: setKillswitchValue
+              parameters:
+                id: $response.body#/id
+            DeleteKillswitch:
+              operationId: deleteKillswitch
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -2342,7 +2449,7 @@ paths:
           required: true
           description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get one killswitch
@@ -2414,7 +2521,7 @@ paths:
           required: true
           description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -2491,7 +2598,7 @@ paths:
           required: true
           description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Delete a killswitch
@@ -2544,7 +2651,7 @@ paths:
           required: true
           description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -2618,7 +2725,7 @@ paths:
           required: true
           description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -2687,7 +2794,7 @@ paths:
           required: true
           description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -2758,6 +2865,7 @@ paths:
         - $ref: '#/components/parameters/ProjectId'
         - $ref: '#/components/parameters/PaginationLimit'
         - $ref: '#/components/parameters/PaginationCursor'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List universes
@@ -2846,6 +2954,15 @@ paths:
               example:
                 id: uni_01j7w8a1b2c3d4e5f6g7h8i9j0
                 name: primary_users
+          links:
+            UpdateUniverse:
+              operationId: updateUniverse
+              parameters:
+                id: $response.body#/id
+            DeleteUniverse:
+              operationId: deleteUniverse
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -2891,7 +3008,7 @@ paths:
           required: true
           description: Stable opaque universe id (`uni_…`) or the universe's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -2959,7 +3076,7 @@ paths:
           required: true
           description: Stable opaque universe id (`uni_…`) or the universe's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Delete a universe
@@ -2998,17 +3115,19 @@ paths:
       description: |-
         Returns the merged targeting-rule template catalog — read-only **built-ins first** (the `@team`/`@owner` audience aliases, country, email-domain, region presets, …), then this project's **customer** templates. Each item carries a `rules: [{ attr, op, value }]` definition; the alias templates carry a symbol value (`email in ["@team"]`) that the SDK expands to the resolved email list at rebuild.
 
-        **Turn "launch X in country Y" into a gated flag:** list templates (optionally with `query`), take the matching template's `rules`, substitute the concrete value(s), and pass them as the `rules` arg of `release_flags_create`.
+        **Turn "launch X in country Y" into a gated flag:** list templates (optionally with `q`), take the matching template's `rules`, substitute the concrete value(s), and pass them as the `rules` arg of `release_flags_create`.
 
         The catalog is small and bounded, so the full merged set is returned in one page — this endpoint is **not** paginated (`next_cursor` is always `null`; there are no `limit`/`cursor` params).
       tags:
         - Templates
       parameters:
         - $ref: '#/components/parameters/ProjectId'
+        - $ref: '#/components/parameters/Q'
         - name: query
           in: query
           required: false
-          description: Case-insensitive substring filter over each template's `name` + `description`. Omit to return the whole catalog.
+          deprecated: true
+          description: Deprecated alias for `q`, kept working for one release. Prefer `q`.
           schema:
             type: string
       responses:
@@ -3120,7 +3239,7 @@ paths:
           required: true
           description: Built-in slug (`country`) or customer template id (`gtpl_…`).
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get one gate template
@@ -3158,7 +3277,7 @@ paths:
           required: true
           description: Customer template id (`gtpl_…`) or its `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -3221,7 +3340,7 @@ paths:
           required: true
           description: Customer template id (`gtpl_…`) or its `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Delete a gate template
@@ -3241,6 +3360,8 @@ paths:
           $ref: '#/components/responses/NotFound'
         '409':
           $ref: '#/components/responses/Conflict'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
       x-error-codes:
         - BAD_REQUEST
         - UNAUTHORIZED
@@ -3263,6 +3384,7 @@ paths:
         - Attributes
       parameters:
         - $ref: '#/components/parameters/ProjectId'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List targeting attributes
@@ -3329,6 +3451,19 @@ paths:
               example:
                 id: attr_01j7w8a1b2c3
                 name: plan
+          links:
+            GetAttribute:
+              operationId: getAttribute
+              parameters:
+                id: $response.body#/id
+            UpdateAttribute:
+              operationId: updateAttribute
+              parameters:
+                id: $response.body#/id
+            DeleteAttribute:
+              operationId: deleteAttribute
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -3368,7 +3503,7 @@ paths:
           required: true
           description: The attribute id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get a targeting attribute
@@ -3422,7 +3557,7 @@ paths:
           required: true
           description: The attribute id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -3481,7 +3616,7 @@ paths:
           required: true
           description: The attribute id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Archive a targeting attribute
@@ -3524,6 +3659,7 @@ paths:
         - Metrics
       parameters:
         - $ref: '#/components/parameters/ProjectId'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List metrics
@@ -3625,6 +3761,19 @@ paths:
               example:
                 id: met_01j7w8a1b2c3d4e5f6g7h8i9j0
                 name: checkouts
+          links:
+            GetMetric:
+              operationId: getMetric
+              parameters:
+                id: $response.body#/id
+            UpdateMetric:
+              operationId: updateMetric
+              parameters:
+                id: $response.body#/id
+            DeleteMetric:
+              operationId: deleteMetric
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -3666,7 +3815,7 @@ paths:
           required: true
           description: Stable opaque metric id (`met_…`) or the metric's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get a metric
@@ -3725,7 +3874,7 @@ paths:
           required: true
           description: Stable opaque metric id (`met_…`) or the metric's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -3784,7 +3933,7 @@ paths:
           required: true
           description: Stable opaque metric id (`met_…`) or the metric's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Archive a metric
@@ -3828,6 +3977,7 @@ paths:
         - Events
       parameters:
         - $ref: '#/components/parameters/ProjectId'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List events
@@ -3913,6 +4063,23 @@ paths:
               example:
                 id: evt_01j7w8a1b2c3d4e5f6g7h8i9j0
                 name: checkout_completed
+          links:
+            GetEvent:
+              operationId: getEvent
+              parameters:
+                id: $response.body#/id
+            UpdateEvent:
+              operationId: updateEvent
+              parameters:
+                id: $response.body#/id
+            ApproveEvent:
+              operationId: approveEvent
+              parameters:
+                id: $response.body#/id
+            DeleteEvent:
+              operationId: deleteEvent
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -3952,7 +4119,7 @@ paths:
           required: true
           description: Stable opaque event id (`evt_…`) or the event's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get an event
@@ -4011,7 +4178,7 @@ paths:
           required: true
           description: Stable opaque event id (`evt_…`) or the event's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -4079,7 +4246,7 @@ paths:
           required: true
           description: Stable opaque event id (`evt_…`) or the event's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Archive an event
@@ -4130,7 +4297,7 @@ paths:
           required: true
           description: Stable opaque event id (`evt_…`) or the event's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -4357,7 +4524,7 @@ paths:
           required: true
           description: Per-project item number (e.g. `7`) or the full ops item id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get one queue item
@@ -4416,7 +4583,7 @@ paths:
           required: true
           description: Per-project item number (e.g. `7`) or the full ops item id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -4484,7 +4651,7 @@ paths:
           required: true
           description: Per-project item number (e.g. `7`) or the full ops item id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -4637,6 +4804,7 @@ paths:
         - Alerts
       parameters:
         - $ref: '#/components/parameters/ProjectId'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List alert rules
@@ -4730,6 +4898,15 @@ paths:
                 $ref: '#/components/schemas/CreateAlertRuleResponse'
               example:
                 id: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
+          links:
+            UpdateAlertRule:
+              operationId: updateAlertRule
+              parameters:
+                id: $response.body#/id
+            DeleteAlertRule:
+              operationId: deleteAlertRule
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -4773,7 +4950,7 @@ paths:
           required: true
           description: Stable opaque alert-rule id (`ar_…`) or the rule's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -4844,7 +5021,7 @@ paths:
           required: true
           description: Stable opaque alert-rule id (`ar_…`) or the rule's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Delete an alert rule
@@ -5018,7 +5195,7 @@ paths:
           required: true
           description: Stable opaque project id. Must match the caller's own project.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -5157,6 +5334,11 @@ paths:
               example:
                 id: i18n_01j7w8a1b2c4
                 name: fr:prod
+          links:
+            PublishI18nProfile:
+              operationId: publishI18nProfile
+              parameters:
+                profileId: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -5204,9 +5386,10 @@ paths:
         - name: q
           in: query
           required: false
-          description: Free-text search — matches keys whose name OR value contains this substring (case-insensitive). Use it to find the key behind a piece of on-screen copy.
+          description: Free-text search — matches keys whose name, value, OR description contains this substring (case-insensitive). Use it to find the key behind a piece of on-screen copy.
           schema:
             type: string
+            maxLength: 100
         - name: limit
           in: query
           required: false
@@ -5215,6 +5398,14 @@ paths:
             type: integer
             minimum: 1
             maximum: 500
+        - name: offset
+          in: query
+          required: false
+          description: Number of keys to skip before returning `limit` rows (offset pagination).
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
       responses:
         '200':
           description: List i18n keys
@@ -5319,7 +5510,7 @@ paths:
           required: true
           description: The key's id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -5467,7 +5658,7 @@ paths:
           required: true
           description: The draft id to update.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -5525,7 +5716,7 @@ paths:
           required: true
           description: The profile id to publish.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -5535,7 +5726,7 @@ paths:
             example:
               chunk: default
       responses:
-        '201':
+        '200':
           description: Publish a profile chunk
           content:
             application/json:
@@ -5736,7 +5927,7 @@ paths:
           required: true
           description: Stable opaque error id (`err_…`).
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get a tracked error
@@ -5811,7 +6002,7 @@ paths:
           required: true
           description: Stable opaque error id (`err_…`).
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -5900,7 +6091,7 @@ paths:
           required: true
           description: Stable opaque error id (`err_…`).
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '201':
           description: File a feedback ticket for an error
@@ -5948,7 +6139,7 @@ paths:
           required: true
           description: Stable opaque error id (`err_…`).
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -6022,6 +6213,7 @@ paths:
         - Connectors
       parameters:
         - $ref: '#/components/parameters/ProjectId'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List connectors
@@ -6140,6 +6332,23 @@ paths:
                 $ref: '#/components/schemas/CreateConnectorResponse'
               example:
                 id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
+          links:
+            GetConnector:
+              operationId: getConnector
+              parameters:
+                id: $response.body#/id
+            UpdateConnector:
+              operationId: updateConnector
+              parameters:
+                id: $response.body#/id
+            TestConnector:
+              operationId: testConnector
+              parameters:
+                id: $response.body#/id
+            DeleteConnector:
+              operationId: deleteConnector
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -6175,7 +6384,7 @@ paths:
           required: true
           description: Stable opaque connector id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get a connector
@@ -6243,7 +6452,7 @@ paths:
           required: true
           description: Stable opaque connector id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -6316,7 +6525,7 @@ paths:
           required: true
           description: Stable opaque connector id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Delete a connector
@@ -6365,7 +6574,7 @@ paths:
           required: true
           description: Stable opaque connector id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: false
         content:
@@ -6383,7 +6592,7 @@ paths:
                   text: Triage only the P0 bugs reported in the last 24h.
       responses:
         '200':
-          description: Fire a trigger connector
+          description: The trigger run was successfully kicked off.
           content:
             application/json:
               schema:
@@ -6402,6 +6611,8 @@ paths:
           $ref: '#/components/responses/Conflict'
         '422':
           $ref: '#/components/responses/UnprocessableEntity'
+        '502':
+          $ref: '#/components/responses/BadGateway'
       x-error-codes:
         - UNAUTHORIZED
         - FORBIDDEN
@@ -6429,10 +6640,10 @@ paths:
           required: true
           description: Stable opaque connector id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
-          description: Test a connector
+          description: The test dispatch reached the destination.
           content:
             application/json:
               schema:
@@ -6452,6 +6663,8 @@ paths:
           $ref: '#/components/responses/Conflict'
         '422':
           $ref: '#/components/responses/UnprocessableEntity'
+        '502':
+          $ref: '#/components/responses/BadGateway'
       x-error-codes:
         - UNAUTHORIZED
         - FORBIDDEN
@@ -6481,7 +6694,7 @@ paths:
           required: true
           description: Stable opaque connector id. Its stored `provider` must match the body's `provider`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -6587,6 +6800,27 @@ paths:
                 $ref: '#/components/schemas/CreateConnectorResponse'
               example:
                 id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
+          links:
+            FireConnector:
+              operationId: fireConnector
+              parameters:
+                id: $response.body#/id
+            TestConnector:
+              operationId: testConnector
+              parameters:
+                id: $response.body#/id
+            GetConnector:
+              operationId: getConnector
+              parameters:
+                id: $response.body#/id
+            UpdateTriggerConnector:
+              operationId: updateTriggerConnector
+              parameters:
+                id: $response.body#/id
+            DeleteConnector:
+              operationId: deleteConnector
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -6783,6 +7017,7 @@ paths:
         - $ref: '#/components/parameters/ProjectId'
         - $ref: '#/components/parameters/PaginationLimit'
         - $ref: '#/components/parameters/PaginationCursor'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List API keys
@@ -6917,7 +7152,7 @@ paths:
           required: true
           description: Stable opaque key id (UUID) returned by `create` / `list`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Revoke an API key
@@ -7042,6 +7277,14 @@ components:
       description: Opaque cursor returned in the previous page's `next_cursor`. Omit for the first page.
       schema:
         type: string
+    Q:
+      name: q
+      in: query
+      required: false
+      description: Case-insensitive substring filter across the resource's human-readable text columns (e.g. `name`, `title`, `description`). OR-matched across those columns; omit to return everything.
+      schema:
+        type: string
+        maxLength: 100
   schemas:
     ListGatesResponse:
       type: object
@@ -7690,6 +7933,11 @@ components:
         - id
         - name
       additionalProperties: false
+    ResourceId:
+      type: string
+      minLength: 1
+      maxLength: 128
+      description: A resource path identifier — an opaque `xxx_<ULID>` id (~30 chars) or the resource's `name`/`key`. 1–128 characters; the upper bound matches the longest name/key any resource accepts, so an over-long value can never name a real row.
     DeleteGateResponse:
       type: object
       properties:
@@ -9729,7 +9977,7 @@ components:
       required:
         - id
       additionalProperties: false
-    GateTemplateRule:
+    GateTemplateRuleResponse:
       type: object
       properties:
         attr:
@@ -9760,9 +10008,8 @@ components:
       required:
         - attr
         - op
-        - value
       additionalProperties: false
-      description: Single targeting predicate. Copy a template's rules, substitute the concrete `value`(s), and pass them as the `rules` arg of `release_flags_create`.
+      description: Single targeting predicate as returned by the API. `value` is optional here — read-only built-in templates (e.g. `@owner`, or presets whose operand is supplied at substitution time) legitimately omit it. Request bodies still require `value`.
     GateTemplate:
       type: object
       description: 'A reusable targeting-rule template. Built-ins are read-only (`builtin: true`, stable slug `id`); per-project customer templates are `builtin: false` with a `gtpl_…` id.'
@@ -9796,7 +10043,7 @@ components:
         rules:
           type: array
           items:
-            $ref: '#/components/schemas/GateTemplateRule'
+            $ref: '#/components/schemas/GateTemplateRuleResponse'
           description: The rule definition — copy, substitute the value(s), pass as `rules`.
         createdAt:
           anyOf:
@@ -9832,6 +10079,46 @@ components:
         - data
         - next_cursor
       additionalProperties: false
+    GateTemplateRule:
+      type: object
+      properties:
+        attr:
+          type: string
+          description: Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input. May be empty on a built-in template whose attribute is supplied at substitution time (e.g. the `exp_in` "in any experiment" preset — you fill in the experiment name).
+        op:
+          type: string
+          enum:
+            - eq
+            - neq
+            - in
+            - not_in
+            - gt
+            - gte
+            - lt
+            - lte
+            - contains
+            - regex
+            - semver_gt
+            - semver_gte
+            - semver_lt
+            - semver_lte
+            - gate_pass
+            - exp_in
+          description: 'Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte`. String: `contains` (substring), `regex` (JS-flavour pattern). Cross-resource: `gate_pass` (value is another gate''s name), `exp_in` (attr is an experiment name, value is a variant / `"$holdout"` / `"$any"`).'
+        value:
+          description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; variant selector for `exp_in`. Required on every request rule (value-ops need it; the valueless built-in presets are read-only and never created via the API).'
+          anyOf:
+            - type: string
+            - type: number
+            - type: boolean
+            - type: array
+              items: {}
+      required:
+        - attr
+        - op
+        - value
+      additionalProperties: false
+      description: Single targeting predicate. Copy a template's rules, substitute the concrete `value`(s), and pass them as the `rules` arg of `release_flags_create`.
     CreateGateTemplateRequest:
       type: object
       description: Body for `POST /api/admin/gate-templates`. Creates a per-project (customer) template. At minimum supply `name` + `rules`.
@@ -11907,8 +12194,10 @@ components:
           items:
             type: string
         href:
-          description: Dashboard-relative deep link to the related item.
-          type: string
+          description: Dashboard-relative deep link to the related item. `null` is accepted and treated as "no link".
+          anyOf:
+            - type: string
+            - type: 'null'
         dedupeKey:
           description: Stable per-escalation key (e.g. `feedback:7`) so re-runs dedupe to one row.
           type: string
@@ -13478,33 +13767,27 @@ components:
       properties:
         ok:
           type: boolean
-          description: '`true` when the trigger run was successfully kicked off; `false` when the dispatch itself failed (still HTTP 200, with `error` set).'
-        error:
-          type: string
-          description: Failure reason. Present only when `ok` is `false` — the fire reached the handler but the underlying dispatch to the provider failed.
+          description: Always `true` — a successful fire returns HTTP 200. A dispatch failure returns HTTP 502 with the `Error` envelope, not this body.
       required:
         - ok
       additionalProperties: false
-      description: 'Result of firing a trigger connector. `{ ok: true }` on success; `{ ok: false, error }` when the dispatch fails (the request still returns HTTP 200).'
+      description: 'Result of a successful trigger fire: `{ ok: true }`. When the downstream dispatch fails the endpoint returns HTTP 502 (see the `Error` response), never `ok: false`.'
     TestConnectorResponse:
       type: object
       properties:
         ok:
           type: boolean
-          description: '`true` when the test dispatch reached the destination; `false` when the dispatch itself failed (still HTTP 200, with `error` set).'
+          description: Always `true` — a successful test returns HTTP 200. A dispatch failure returns HTTP 502 with the `Error` envelope, not this body.
         issueUrl:
           anyOf:
             - type: string
             - type: 'null'
-          description: URL of the artifact the test produced (e.g. the GitHub Issue created by a `github` connector), or `null` when the provider produces no linkable artifact (or the dispatch failed).
-        error:
-          type: string
-          description: Failure reason. Present only when `ok` is `false` — the test reached the handler but the underlying dispatch to the provider failed.
+          description: URL of the artifact the test produced (e.g. the GitHub Issue created by a `github` connector), or `null` when the provider produces no linkable artifact.
       required:
         - ok
         - issueUrl
       additionalProperties: false
-      description: 'Result of testing a connector. `{ ok: true, issueUrl }` on success; `{ ok: false, issueUrl: null, error }` when the dispatch fails (the request still returns HTTP 200).'
+      description: 'Result of a successful connector test: `{ ok: true, issueUrl }`. When the downstream dispatch fails the endpoint returns HTTP 502 (see the `Error` response), never `ok: false`.'
     UpdateClaudeTriggerRequest:
       type: object
       properties:
@@ -13977,3 +14260,18 @@ components:
               value:
                 error: The referenced event is still pending review and cannot back a metric yet.
                 code: EVENT_PENDING
+    BadGateway:
+      description: |-
+        The request was well-formed and the resource exists, but a downstream provider
+        the endpoint delegates to (e.g. a connector's Slack/GitHub/cloud-agent dispatch)
+        failed. The failure is upstream of this API, not a client error. No stable
+        `ErrorCode` is assigned to upstream failures, so `code` is omitted.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            UPSTREAM_FAILURE:
+              summary: Downstream provider dispatch failed
+              value:
+                error: 'GitHub API responded 403: resource not accessible by integration.'