@shipeasy/openapi 2.1.0 → 2.3.0

package/spec/paths/configs.yaml

@@ -12,6 +12,7 @@
       - $ref: ../components/parameters.yaml#/ProjectId
       - $ref: ../components/parameters.yaml#/PaginationLimit
       - $ref: ../components/parameters.yaml#/PaginationCursor
+      - $ref: ../components/parameters.yaml#/Q
     responses:
       "200":
         description: List dynamic configs
@@ -160,6 +161,19 @@
             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.yaml#/BadRequest
       "401":
@@ -178,6 +192,7 @@
       - FORBIDDEN
       - ALREADY_EXISTS
       - VALIDATION
+      - PLAN_LIMIT
     x-cli:
       name: create
       positional:
@@ -199,7 +214,7 @@
         required: true
         description: Stable opaque config id (`cfg_…`) or the config's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Get one config
@@ -301,7 +316,7 @@
         required: true
         description: Stable opaque config id (`cfg_…`) or the config's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -377,7 +392,7 @@
         required: true
         description: Stable opaque config id (`cfg_…`) or the config's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Delete a dynamic config
@@ -427,7 +442,7 @@
         required: true
         description: Stable opaque config id (`cfg_…`) or the config's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -495,7 +510,7 @@
         required: true
         description: Stable opaque config id (`cfg_…`) or the config's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -557,7 +572,7 @@
         required: true
         description: Stable opaque config id (`cfg_…`) or the config's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -576,7 +591,7 @@
               value:
                 env: prod
     responses:
-      "201":
+      "200":
         description: Publish a draft
         content:
           application/json:
@@ -626,7 +641,7 @@
         required: true
         description: Stable opaque config id (`cfg_…`) or the config's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
       - name: limit
         in: query
         required: false
@@ -690,7 +705,7 @@
         required: true
         description: Stable opaque config id (`cfg_…`) or the config's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:

package/spec/paths/connectors.yaml

@@ -12,6 +12,7 @@
       - Connectors
     parameters:
       - $ref: ../components/parameters.yaml#/ProjectId
+      - $ref: ../components/parameters.yaml#/Q
     responses:
       "200":
         description: List connectors
@@ -130,6 +131,19 @@
               $ref: ../components/schemas/connectors.yaml#/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.yaml#/BadRequest
       "401":
@@ -165,7 +179,7 @@
         required: true
         description: Stable opaque connector id.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Get a connector
@@ -233,7 +247,7 @@
         required: true
         description: Stable opaque connector id.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -306,7 +320,7 @@
         required: true
         description: Stable opaque connector id.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Delete a connector
@@ -355,7 +369,7 @@
         required: true
         description: Stable opaque connector id.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: false
       content:
@@ -373,7 +387,7 @@
                 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:
@@ -392,6 +406,8 @@
         $ref: ../components/responses.yaml#/Conflict
       "422":
         $ref: ../components/responses.yaml#/UnprocessableEntity
+      "502":
+        $ref: ../components/responses.yaml#/BadGateway
     x-error-codes:
       - UNAUTHORIZED
       - FORBIDDEN
@@ -419,10 +435,10 @@
         required: true
         description: Stable opaque connector id.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
-        description: Test a connector
+        description: The test dispatch reached the destination.
         content:
           application/json:
             schema:
@@ -442,6 +458,8 @@
         $ref: ../components/responses.yaml#/Conflict
       "422":
         $ref: ../components/responses.yaml#/UnprocessableEntity
+      "502":
+        $ref: ../components/responses.yaml#/BadGateway
     x-error-codes:
       - UNAUTHORIZED
       - FORBIDDEN
@@ -471,7 +489,7 @@
         required: true
         description: Stable opaque connector id. Its stored `provider` must match the body's `provider`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -577,6 +595,22 @@
               $ref: ../components/schemas/connectors.yaml#/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.yaml#/BadRequest
       "401":

package/spec/paths/errors.yaml

@@ -96,9 +96,9 @@
     operationId: getError
     summary: Get a tracked error
     description: |-
-      Returns a single tracked error by its id, including the latest occurrence's stack, extras, and consequence. Returns `404` if no such error exists in the project.
+      Returns a single tracked error by its id, including the latest occurrence's stack, extras, and consequence, plus `occurrences` — the sampled per-instance detail rows behind the issue (newest first; exhaustive while the issue is small, thinned at volume, capped at 100). Returns `404` if no such error exists in the project.
 
-      **Use case:** Drill into one issue — fetch its full stack and `seenUrls` to investigate, or to render the detail panel behind a row in the errors list.
+      **Use case:** Drill into one issue — fetch its full stack and `seenUrls` to investigate, or walk `occurrences` to see how the failing message/stack varies across instances.
     tags:
       - Errors
     parameters:
@@ -108,7 +108,7 @@
         required: true
         description: Stable opaque error id (`err_…`).
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Get a tracked error
@@ -142,6 +142,31 @@
               lastSeenAt: 2026-06-28T14:55:31.000Z
               createdAt: 2026-06-20T08:11:02.000Z
               updatedAt: 2026-06-28T14:55:31.000Z
+              occurrences:
+                - id: occ_01j7w7qq0v3k9d2m5rc8t1xh4n
+                  message: Cannot read properties of undefined (reading 'id')
+                  stack: |-
+                    TypeError: Cannot read properties of undefined (reading 'id')
+                        at GateEditor (/app/gates/[id]/page.tsx:42:18)
+                  url: https://app.example.com/dashboard/gat_01j7/edit
+                  env: prod
+                  side: client
+                  sdkVersion: 6.0.0
+                  extrasJson: '{"gateId":"gat_01j7"}'
+                  sampleRate: 100
+                  seenAt: 2026-06-28T14:55:31.000Z
+                - id: occ_01j7w7pk8s6e3f9b0zad7y5w2q
+                  message: Cannot read properties of undefined (reading 'id')
+                  stack: |-
+                    TypeError: Cannot read properties of undefined (reading 'id')
+                        at GateEditor (/app/gates/[id]/page.tsx:42:18)
+                  url: https://app.example.com/dashboard/gat_02c4/edit
+                  env: prod
+                  side: client
+                  sdkVersion: 6.0.0
+                  extrasJson: '{"gateId":"gat_02c4"}'
+                  sampleRate: 10
+                  seenAt: 2026-06-24T09:12:05.000Z
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -183,7 +208,7 @@
         required: true
         description: Stable opaque error id (`err_…`).
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -272,7 +297,7 @@
         required: true
         description: Stable opaque error id (`err_…`).
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "201":
         description: File a feedback ticket for an error
@@ -303,6 +328,75 @@
       name: file
       positional:
         - id
+/api/admin/errors/{id}/resolve:
+  post:
+    operationId: resolveError
+    summary: Resolve a tracked error
+    description: |-
+      Marks one tracked error `resolved` — the single-purpose "close out" action. Takes no body; it is `PATCH /api/admin/errors/{id}` pinned to `{ "status": "resolved" }`, exposed so tooling can close an error without being handed the full open/resolved/ignored status machine. A resolved error reopens automatically (ingestion-side) if it recurs, so resolving is always safe: a premature resolve un-does itself on the next occurrence. Returns the updated row; `404` if the error does not exist.
+
+      **Use case:** Close out a tracked error from an agent or script once its fix has shipped — e.g. after a deploy, resolve every open issue the change addressed and let recurrence reopen anything that wasn't actually fixed.
+    tags:
+      - Errors
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque error id (`err_…`).
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Resolve a tracked error
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/errors-api.yaml#/ErrorRecord
+            example:
+              id: err_01j7w7m9q4hxbf6npe6s9zr3vc
+              projectId: e976b15e-2f0d-4c6e-9b1a-3a7c1f2d8e90
+              fingerprint: 9c1f4f1f2c0c4a5fa1c2b6d3e7c8e3a1
+              causedByFingerprint: null
+              message: Cannot read properties of undefined (reading 'id')
+              errorType: TypeError
+              stack: null
+              source: shipeasy
+              url: https://app.example.com/dashboard/gat_01j7/edit
+              seenUrls: null
+              subject: gate editor
+              outcome: crash on load
+              side: client
+              env: prod
+              kind: uncaught
+              lastExtrasJson: null
+              sdkVersion: 6.0.0
+              count: 137
+              status: resolved
+              firstSeenAt: 2026-06-20T08:11:02.000Z
+              lastSeenAt: 2026-06-28T14:55:31.000Z
+              createdAt: 2026-06-20T08:11:02.000Z
+              updatedAt: 2026-06-28T15:02:10.000Z
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: resolve
+      positional:
+        - id
 /api/admin/errors/{id}/series:
   post:
     operationId: getErrorSeries
@@ -320,7 +414,7 @@
         required: true
         description: Stable opaque error id (`err_…`).
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:

package/spec/paths/events.yaml

@@ -10,6 +10,7 @@
       - Events
     parameters:
       - $ref: ../components/parameters.yaml#/ProjectId
+      - $ref: ../components/parameters.yaml#/Q
     responses:
       "200":
         description: List events
@@ -95,6 +96,19 @@
             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.yaml#/BadRequest
       "401":
@@ -113,6 +127,7 @@
       - FORBIDDEN
       - ALREADY_EXISTS
       - VALIDATION
+      - PLAN_LIMIT
     x-cli:
       name: create
       positional:
@@ -134,7 +149,7 @@
         required: true
         description: Stable opaque event id (`evt_…`) or the event's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Get an event
@@ -193,7 +208,7 @@
         required: true
         description: Stable opaque event id (`evt_…`) or the event's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -261,7 +276,7 @@
         required: true
         description: Stable opaque event id (`evt_…`) or the event's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Archive an event
@@ -312,7 +327,7 @@
         required: true
         description: Stable opaque event id (`evt_…`) or the event's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:

package/spec/paths/experiments.yaml

@@ -12,6 +12,13 @@
       - $ref: ../components/parameters.yaml#/ProjectId
       - $ref: ../components/parameters.yaml#/PaginationLimit
       - $ref: ../components/parameters.yaml#/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.yaml#/Q
     responses:
       "200":
         description: List experiments
@@ -159,6 +166,25 @@
             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.yaml#/BadRequest
       "401":
@@ -201,7 +227,7 @@
         required: true
         description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Get one experiment
@@ -281,7 +307,7 @@
         required: true
         description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -346,6 +372,7 @@
       - GROUPS_WEIGHT_SUM
       - REFERENCED_NOT_FOUND
       - VALIDATION
+      - EXPERIMENT_IMMUTABLE_FIELD
     x-cli:
       name: update
       positional:
@@ -366,7 +393,7 @@
         required: true
         description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Delete an experiment
@@ -427,7 +454,7 @@
         required: true
         description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -456,7 +483,7 @@
               value:
                 status: draft
     responses:
-      "201":
+      "200":
         description: Transition experiment status
         content:
           application/json:
@@ -484,6 +511,12 @@
       - NOT_FOUND
       - INVALID_TRANSITION
       - VALIDATION
+      - PLAN_LIMIT
+      - EXPERIMENT_NO_GOAL_METRIC
+      - EXPERIMENT_ARCHIVED_RESTART
+      - EXPERIMENT_NOT_RUNNING
+      - EXPERIMENT_RUNNING_ARCHIVE
+      - EXPERIMENT_RESTORE_INVALID
     x-cli:
       positional:
         - id
@@ -522,7 +555,7 @@
         required: true
         description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -545,7 +578,7 @@
               value:
                 metrics: []
     responses:
-      "201":
+      "200":
         description: Attach metrics
         content:
           application/json:
@@ -578,6 +611,7 @@
       - EVENT_PENDING
       - REFERENCED_NOT_FOUND
       - VALIDATION
+      - METRIC_UNKNOWN_ID
     x-cli:
       name: set-metrics
       positional:
@@ -599,7 +633,7 @@
         required: true
         description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Get analysis results
@@ -668,7 +702,7 @@
         required: true
         description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
       - name: metric
         in: query
         required: false
@@ -742,9 +776,9 @@
         required: true
         description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
-      "201":
+      "200":
         description: Re-queue analysis
         content:
           application/json:

package/spec/paths/gate-templates.yaml

@@ -5,17 +5,19 @@
     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.yaml#/ProjectId
+      - $ref: ../components/parameters.yaml#/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:
@@ -128,7 +130,7 @@
         required: true
         description: Built-in slug (`country`) or customer template id (`gtpl_…`).
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Get one gate template
@@ -167,7 +169,7 @@
         required: true
         description: Customer template id (`gtpl_…`) or its `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -231,7 +233,7 @@
         required: true
         description: Customer template id (`gtpl_…`) or its `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Delete a gate template
@@ -251,6 +253,8 @@
         $ref: ../components/responses.yaml#/NotFound
       "409":
         $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
     x-error-codes:
       - BAD_REQUEST
       - UNAUTHORIZED