@shipeasy/openapi 2.1.0 → 2.2.0

package/openapi.json

@@ -31,9 +31,9 @@
   "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\nthat decide which code path a user gets — feature gates (flags), kill\nswitches, dynamic configs, A/B/n experiments, and the universes that bucket\nthem — each exposed as its own subcommand group.\n\n**Groups.**\n- `flags` — boolean feature gates: AND-combined targeting rules + a percentage rollout (basis points), evaluated on the SDK hot path.\n- `killswitch` (`ks`) — per-env boolean overrides for incident response; no rules, no rollout, versioned per environment.\n- `configs` — JSON-Schema-validated structured values with a draft → publish workflow, delivered per environment.\n- `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.\n\n**Delivery model.** Every write rebuilds the project's KV blob and purges\nthe CDN — SDKs poll at the plan interval and never touch the database on\nthe hot path. The destructive verb is `archive` (soft-delete), never\n`delete`.\n\nRun `shipeasy release <group> --help` for the full contract of each group."
     },
     {
       "name": "Flags",
@@ -157,6 +157,9 @@
           },
           {
             "$ref": "#/components/parameters/PaginationCursor"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -360,6 +363,32 @@
                   "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": {
@@ -414,7 +443,7 @@
             "required": true,
             "description": "Stable opaque gate id (`gat_…`) or the gate's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -569,7 +598,7 @@
             "required": true,
             "description": "Stable opaque gate id (`gat_…`) or the gate's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -639,12 +668,12 @@
             "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": {
@@ -710,12 +739,12 @@
             "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": {
@@ -780,6 +809,18 @@
           },
           {
             "$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": {
@@ -990,6 +1031,44 @@
                   "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": {
@@ -1047,7 +1126,7 @@
             "required": true,
             "description": "Stable opaque experiment id (`exp_…`) or the experiment's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -1148,7 +1227,7 @@
             "required": true,
             "description": "Stable opaque experiment id (`exp_…`) or the experiment's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -1271,7 +1350,7 @@
             "required": true,
             "description": "Stable opaque experiment id (`exp_…`) or the experiment's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -1341,7 +1420,7 @@
             "required": true,
             "description": "Stable opaque experiment id (`exp_…`) or the experiment's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -1386,7 +1465,7 @@
           }
         },
         "responses": {
-          "201": {
+          "200": {
             "description": "Transition experiment status",
             "content": {
               "application/json": {
@@ -1475,7 +1554,7 @@
             "required": true,
             "description": "Stable opaque experiment id (`exp_…`) or the experiment's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -1515,7 +1594,7 @@
           }
         },
         "responses": {
-          "201": {
+          "200": {
             "description": "Attach metrics",
             "content": {
               "application/json": {
@@ -1592,7 +1671,7 @@
             "required": true,
             "description": "Stable opaque experiment id (`exp_…`) or the experiment's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -1688,7 +1767,7 @@
             "required": true,
             "description": "Stable opaque experiment id (`exp_…`) or the experiment's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           },
           {
@@ -1792,12 +1871,12 @@
             "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": {
@@ -1862,6 +1941,9 @@
           },
           {
             "$ref": "#/components/parameters/PaginationCursor"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -2089,6 +2171,32 @@
                   "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": {
@@ -2143,7 +2251,7 @@
             "required": true,
             "description": "Stable opaque config id (`cfg_…`) or the config's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -2298,7 +2406,7 @@
             "required": true,
             "description": "Stable opaque config id (`cfg_…`) or the config's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -2414,7 +2522,7 @@
             "required": true,
             "description": "Stable opaque config id (`cfg_…`) or the config's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -2483,7 +2591,7 @@
             "required": true,
             "description": "Stable opaque config id (`cfg_…`) or the config's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -2586,7 +2694,7 @@
             "required": true,
             "description": "Stable opaque config id (`cfg_…`) or the config's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -2674,7 +2782,7 @@
             "required": true,
             "description": "Stable opaque config id (`cfg_…`) or the config's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -2705,7 +2813,7 @@
           }
         },
         "responses": {
-          "201": {
+          "200": {
             "description": "Publish a draft",
             "content": {
               "application/json": {
@@ -2773,7 +2881,7 @@
             "required": true,
             "description": "Stable opaque config id (`cfg_…`) or the config's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           },
           {
@@ -2864,7 +2972,7 @@
             "required": true,
             "description": "Stable opaque config id (`cfg_…`) or the config's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -2965,6 +3073,9 @@
           },
           {
             "$ref": "#/components/parameters/PaginationCursor"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -3102,6 +3213,38 @@
                   "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": {
@@ -3156,7 +3299,7 @@
             "required": true,
             "description": "Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -3246,7 +3389,7 @@
             "required": true,
             "description": "Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -3357,7 +3500,7 @@
             "required": true,
             "description": "Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -3426,7 +3569,7 @@
             "required": true,
             "description": "Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -3527,7 +3670,7 @@
             "required": true,
             "description": "Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -3619,7 +3762,7 @@
             "required": true,
             "description": "Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -3724,6 +3867,9 @@
           },
           {
             "$ref": "#/components/parameters/PaginationCursor"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -3843,6 +3989,20 @@
                   "name": "primary_users"
                 }
               }
+            },
+            "links": {
+              "UpdateUniverse": {
+                "operationId": "updateUniverse",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "DeleteUniverse": {
+                "operationId": "deleteUniverse",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              }
             }
           },
           "400": {
@@ -3898,7 +4058,7 @@
             "required": true,
             "description": "Stable opaque universe id (`uni_…`) or the universe's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -3996,7 +4156,7 @@
             "required": true,
             "description": "Stable opaque universe id (`uni_…`) or the universe's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -4052,7 +4212,7 @@
       "get": {
         "operationId": "listGateTemplates",
         "summary": "List gate templates",
-        "description": "Returns the merged targeting-rule template catalog — read-only **built-ins first** (the `@team`/`@owner` audience aliases, country, email-domain, region presets, …), then this project's **customer** templates. Each item carries a `rules: [{ attr, op, value }]` definition; the alias templates carry a symbol value (`email in [\"@team\"]`) that the SDK expands to the resolved email list at rebuild.\n\n**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`.\n\nThe 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).",
+        "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.\n\n**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`.\n\nThe 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"
         ],
@@ -4060,11 +4220,15 @@
           {
             "$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"
             }
@@ -4233,7 +4397,7 @@
             "required": true,
             "description": "Built-in slug (`country`) or customer template id (`gtpl_…`).",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -4291,7 +4455,7 @@
             "required": true,
             "description": "Customer template id (`gtpl_…`) or its `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -4388,7 +4552,7 @@
             "required": true,
             "description": "Customer template id (`gtpl_…`) or its `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -4420,6 +4584,9 @@
           },
           "409": {
             "$ref": "#/components/responses/Conflict"
+          },
+          "422": {
+            "$ref": "#/components/responses/UnprocessableEntity"
           }
         },
         "x-error-codes": [
@@ -4448,6 +4615,9 @@
         "parameters": [
           {
             "$ref": "#/components/parameters/ProjectId"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -4547,6 +4717,26 @@
                   "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": {
@@ -4601,7 +4791,7 @@
             "required": true,
             "description": "The attribute id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -4676,7 +4866,7 @@
             "required": true,
             "description": "The attribute id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -4761,7 +4951,7 @@
             "required": true,
             "description": "The attribute id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -4823,6 +5013,9 @@
         "parameters": [
           {
             "$ref": "#/components/parameters/ProjectId"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -4953,6 +5146,26 @@
                   "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": {
@@ -5009,7 +5222,7 @@
             "required": true,
             "description": "Stable opaque metric id (`met_…`) or the metric's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -5090,7 +5303,7 @@
             "required": true,
             "description": "Stable opaque metric id (`met_…`) or the metric's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -5174,7 +5387,7 @@
             "required": true,
             "description": "Stable opaque metric id (`met_…`) or the metric's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -5237,6 +5450,9 @@
         "parameters": [
           {
             "$ref": "#/components/parameters/ProjectId"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -5355,6 +5571,32 @@
                   "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": {
@@ -5409,7 +5651,7 @@
             "required": true,
             "description": "Stable opaque event id (`evt_…`) or the event's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -5489,7 +5731,7 @@
             "required": true,
             "description": "Stable opaque event id (`evt_…`) or the event's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -5589,7 +5831,7 @@
             "required": true,
             "description": "Stable opaque event id (`evt_…`) or the event's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -5659,7 +5901,7 @@
             "required": true,
             "description": "Stable opaque event id (`evt_…`) or the event's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -5989,7 +6231,7 @@
             "required": true,
             "description": "Per-project item number (e.g. `7`) or the full ops item id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -6062,7 +6304,7 @@
             "required": true,
             "description": "Per-project item number (e.g. `7`) or the full ops item id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -6162,7 +6404,7 @@
             "required": true,
             "description": "Per-project item number (e.g. `7`) or the full ops item id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -6384,6 +6626,9 @@
         "parameters": [
           {
             "$ref": "#/components/parameters/ProjectId"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -6506,6 +6751,20 @@
                   "id": "ar_01j7w8a1b2c3d4e5f6g7h8i9j0"
                 }
               }
+            },
+            "links": {
+              "UpdateAlertRule": {
+                "operationId": "updateAlertRule",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "DeleteAlertRule": {
+                "operationId": "deleteAlertRule",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              }
             }
           },
           "400": {
@@ -6558,7 +6817,7 @@
             "required": true,
             "description": "Stable opaque alert-rule id (`ar_…`) or the rule's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -6660,7 +6919,7 @@
             "required": true,
             "description": "Stable opaque alert-rule id (`ar_…`) or the rule's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -6891,7 +7150,7 @@
             "required": true,
             "description": "Stable opaque project id. Must match the caller's own project.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -7088,6 +7347,14 @@
                   "name": "fr:prod"
                 }
               }
+            },
+            "links": {
+              "PublishI18nProfile": {
+                "operationId": "publishI18nProfile",
+                "parameters": {
+                  "profileId": "$response.body#/id"
+                }
+              }
             }
           },
           "400": {
@@ -7155,9 +7422,10 @@
             "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"
+              "type": "string",
+              "maxLength": 100
             }
           },
           {
@@ -7170,6 +7438,17 @@
               "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": {
@@ -7319,7 +7598,7 @@
             "required": true,
             "description": "The key's id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -7533,7 +7812,7 @@
             "required": true,
             "description": "The draft id to update.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -7617,7 +7896,7 @@
             "required": true,
             "description": "The profile id to publish.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -7635,7 +7914,7 @@
           }
         },
         "responses": {
-          "201": {
+          "200": {
             "description": "Publish a profile chunk",
             "content": {
               "application/json": {
@@ -7902,7 +8181,7 @@
             "required": true,
             "description": "Stable opaque error id (`err_…`).",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -7990,7 +8269,7 @@
             "required": true,
             "description": "Stable opaque error id (`err_…`).",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -8107,7 +8386,7 @@
             "required": true,
             "description": "Stable opaque error id (`err_…`).",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -8176,7 +8455,7 @@
             "required": true,
             "description": "Stable opaque error id (`err_…`).",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -8273,6 +8552,9 @@
         "parameters": [
           {
             "$ref": "#/components/parameters/ProjectId"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -8426,6 +8708,32 @@
                   "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": {
@@ -8475,7 +8783,7 @@
             "required": true,
             "description": "Stable opaque connector id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -8558,7 +8866,7 @@
             "required": true,
             "description": "Stable opaque connector id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -8664,7 +8972,7 @@
             "required": true,
             "description": "Stable opaque connector id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -8732,7 +9040,7 @@
             "required": true,
             "description": "Stable opaque connector id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -8761,7 +9069,7 @@
         },
         "responses": {
           "200": {
-            "description": "Fire a trigger connector",
+            "description": "The trigger run was successfully kicked off.",
             "content": {
               "application/json": {
                 "schema": {
@@ -8790,6 +9098,9 @@
           },
           "422": {
             "$ref": "#/components/responses/UnprocessableEntity"
+          },
+          "502": {
+            "$ref": "#/components/responses/BadGateway"
           }
         },
         "x-error-codes": [
@@ -8823,13 +9134,13 @@
             "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": {
@@ -8859,6 +9170,9 @@
           },
           "422": {
             "$ref": "#/components/responses/UnprocessableEntity"
+          },
+          "502": {
+            "$ref": "#/components/responses/BadGateway"
           }
         },
         "x-error-codes": [
@@ -8892,7 +9206,7 @@
             "required": true,
             "description": "Stable opaque connector id. Its stored `provider` must match the body's `provider`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -9038,6 +9352,38 @@
                   "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": {
@@ -9129,6 +9475,9 @@
           },
           {
             "$ref": "#/components/parameters/PaginationCursor"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -9306,7 +9655,7 @@
             "required": true,
             "description": "Stable opaque key id (UUID) returned by `create` / `list`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -9484,6 +9833,16 @@
         "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": {
@@ -10370,6 +10729,12 @@
         ],
         "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": {
@@ -13327,7 +13692,7 @@
         ],
         "additionalProperties": false
       },
-      "GateTemplateRule": {
+      "GateTemplateRuleResponse": {
         "type": "object",
         "properties": {
           "attr": {
@@ -13362,11 +13727,10 @@
         },
         "required": [
           "attr",
-          "op",
-          "value"
+          "op"
         ],
         "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",
@@ -13414,7 +13778,7 @@
           "rules": {
             "type": "array",
             "items": {
-              "$ref": "#/components/schemas/GateTemplateRule"
+              "$ref": "#/components/schemas/GateTemplateRuleResponse"
             },
             "description": "The rule definition — copy, substitute the value(s), pass as `rules`."
           },
@@ -13478,6 +13842,62 @@
         ],
         "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`.",
@@ -16600,8 +17020,15 @@
             }
           },
           "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.",
@@ -18816,25 +19243,21 @@
         "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": [
@@ -18845,11 +19268,7 @@
                 "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": [
@@ -18857,7 +19276,7 @@
           "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",
@@ -19555,6 +19974,24 @@
             }
           }
         }
+      },
+      "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": {
+          "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."
+                }
+              }
+            }
+          }
+        }
       }
     }
   }