@shipeasy/openapi 2.2.0 → 2.4.0

package/spec/paths/alerts.yaml

@@ -0,0 +1,184 @@
+/api/admin/alerts:
+  get:
+    operationId: listAlerts
+    summary: List fired alerts
+    description: |-
+      Returns the project's FIRED alerts as a **bare JSON array** (no pagination envelope), ordered by `createdAt desc`. Defaults to the currently-firing ones (`status=active`); pass a `status` to widen to resolved/dismissed history or `all`.
+
+      Fired alerts are raised only by the platform — the UI's killswitch handlers plus the worker's analysis consumer and alerts cron — never filed by hand, so this surface is list + triage (via PATCH), with no create. The rules that *define* metric-threshold alerts live at `/api/admin/alert-rules`.
+
+      **Use case:** Snapshot what is currently firing for an on-call view or the home Alerts block, or pull `status=all` to audit how a noisy rule has behaved over time.
+    tags:
+      - Fired Alerts
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: status
+        in: query
+        required: false
+        description: Filter by lifecycle state. Defaults to `active` (currently firing); `all` returns every status.
+        schema:
+          type: string
+          enum:
+            - active
+            - resolved
+            - dismissed
+            - all
+          default: active
+    responses:
+      "200":
+        description: List fired alerts
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/alerts.yaml#/ListAlertsResponse
+            example:
+              - id: al_01j7w9c4d5e6f7g8h9i0j1k2l3
+                source: metric_rule
+                ruleId: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
+                severity: danger
+                dedupeKey: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
+                title: Checkout error rate above threshold
+                detail: checkout_errors was 137 over the trailing 24h — above the rule's threshold of 50.
+                href: /dashboard/metrics/met_01j6abc2d3e4f5g6h7i8j9k0l1
+                observedValue: 137
+                status: active
+                createdAt: 2026-06-28T14:55:31.000Z
+                resolvedAt: null
+                dismissedAt: null
+                assigneeId: null
+                assigneeConnectorId: null
+                assigneeAgent: null
+              - id: al_01j7w9b2a1z0y9x8w7v6u5t4s3
+                source: killswitch_armed
+                ruleId: null
+                severity: warn
+                dedupeKey: ks_01j5checkout_kill
+                title: Kill switch "checkout_kill" is armed
+                detail: The kill switch has been armed for 3 days — confirm it is still intentional.
+                href: /dashboard/killswitches/ks_01j5checkout_kill
+                observedValue: null
+                status: active
+                createdAt: 2026-06-27T09:12:05.000Z
+                resolvedAt: null
+                dismissedAt: null
+                assigneeId: 6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c
+                assigneeConnectorId: null
+                assigneeAgent: null
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+    x-cli:
+      name: list
+/api/admin/alerts/{id}:
+  patch:
+    operationId: updateAlert
+    summary: Update a fired alert
+    description: |-
+      Triage writes on one fired alert — the only mutations this surface allows. All body fields are optional (at least one required); only the fields present are changed.
+
+      - **`status`** — flip between `active` / `resolved` / `dismissed`. `resolved` and `dismissed` stamp `resolvedAt` / `dismissedAt`; `active` re-opens and clears both. A resolved alert re-fires (as the same row, re-activated) if its condition is raised again.
+      - **`assigneeId`** — the PERSON owner (a `users.id`), or `null` to unassign.
+      - **`agent`** — the AGENT owner: a connected trigger connector's id, or the built-in `"jarvis"` (**Enterprise plan only** — `403` otherwise), or `null` to clear. Person and agent halves are independent.
+
+      Returns the updated row; `404` if the alert does not exist in the project.
+
+      **Use cases**
+
+      - **Wave off a known condition** — `{ "status": "dismissed" }` on an alert that needs no action.
+      - **Hand it to someone** — `{ "assigneeId": "…" }` from the ops cockpit's Owner column.
+    tags:
+      - Fired Alerts
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque alert id (`al_…`).
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/alerts.yaml#/UpdateAlertRequest
+          examples:
+            resolve:
+              summary: Mark resolved
+              description: Close out a fired alert once the underlying condition is handled.
+              value:
+                status: resolved
+            dismiss:
+              summary: Dismiss a benign alert
+              description: Wave off an alert that needs no action.
+              value:
+                status: dismissed
+            assignPerson:
+              summary: Assign a person owner
+              description: Hand the alert to a teammate from the ops cockpit's Owner column.
+              value:
+                assigneeId: 6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c
+            assignAgent:
+              summary: Assign an agent owner
+              description: Hand the alert to a connected coding agent (a connector id, or `"jarvis"` on Enterprise).
+              value:
+                agent: con_01j7wagentclaude0001
+    responses:
+      "200":
+        description: Update a fired alert
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/alerts.yaml#/UpdateAlertResponse
+            example:
+              id: al_01j7w9c4d5e6f7g8h9i0j1k2l3
+              source: metric_rule
+              ruleId: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
+              severity: danger
+              dedupeKey: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
+              title: Checkout error rate above threshold
+              detail: checkout_errors was 137 over the trailing 24h — above the rule's threshold of 50.
+              href: /dashboard/metrics/met_01j6abc2d3e4f5g6h7i8j9k0l1
+              observedValue: 137
+              status: resolved
+              createdAt: 2026-06-28T14:55:31.000Z
+              resolvedAt: 2026-06-28T16:40:12.000Z
+              dismissedAt: null
+              assigneeId: null
+              assigneeConnectorId: null
+              assigneeAgent: null
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: update
+      positional:
+        - id

package/spec/paths/attributes.yaml

@@ -19,12 +19,30 @@
             schema:
               $ref: ../components/schemas/attributes.yaml#/ListAttributesResponse
             example:
-              - name: plan
+              - id: attr_01j7w8a1b2c3
+                name: plan
+                type: enum
+                enumValues:
+                  - free
+                  - paid
+                required: 1
+                description: Billing plan of the calling user.
+                sdkPath: user.plan
+                createdAt: 2026-06-20T09:14:08.000Z
+                source: manual
+                lastSeenAt: 2026-07-16T22:04:11.000Z
+                deprecated: 0
+              - id: attr_01j7w8a1b2c4
+                name: country
                 type: string
-              - name: country
-                type: string
-              - name: seats
-                type: number
+                enumValues: null
+                required: 0
+                description: null
+                sdkPath: null
+                createdAt: 2026-06-20T09:14:08.000Z
+                source: auto
+                lastSeenAt: 2026-07-16T22:04:11.000Z
+                deprecated: 0
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":

package/spec/paths/configs.yaml

@@ -25,6 +25,9 @@
                 - id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
                   name: pricing.tiers
                   description: Pricing tier definitions consumed by the checkout flow.
+                  folder: pricing
+                  creatorEmail: ana@example.com
+                  createdAt: 2026-05-01T10:12:00.000Z
                   schema:
                     type: object
                     properties:
@@ -192,6 +195,7 @@
       - FORBIDDEN
       - ALREADY_EXISTS
       - VALIDATION
+      - PLAN_LIMIT
     x-cli:
       name: create
       positional:
@@ -225,6 +229,7 @@
               id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
               name: pricing.tiers
               description: Pricing tier definitions consumed by the checkout flow.
+              folder: pricing
               schema:
                 type: object
                 properties:
@@ -687,6 +692,72 @@
       name: activity
       positional:
         - id
+/api/admin/configs/{id}/versions:
+  get:
+    operationId: listConfigVersions
+    summary: List config version history
+    description: |-
+      Returns every published version of the config's value on one env, newest first. The `env` query parameter picks the environment (`dev`, `staging`, or `prod`) and defaults to `prod`; an unknown env returns `400`. The config's JSON Schema is config-level and not versioned — this is value history only.
+
+      **Use case:** Render the History timeline in the config detail pane (value diff + restore), or audit which value was live on prod at a given version.
+    tags:
+      - Configs
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque config id (`cfg_…`) or the config's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+      - name: env
+        in: query
+        required: false
+        description: Environment to list history for (`dev`, `staging`, or `prod`). Defaults to `prod` when omitted.
+        schema:
+          $ref: ../components/schemas/common.yaml#/Env
+    responses:
+      "200":
+        description: List config version history
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/configs.yaml#/ListConfigVersionsResponse
+            example:
+              - version: 5
+                value:
+                  tiers:
+                    - name: free
+                    - name: pro
+                publishedAt: 2026-05-09T18:22:11.000Z
+                publishedBy: ana@example.com
+              - version: 4
+                value:
+                  tiers:
+                    - name: free
+                publishedAt: 2026-05-08T11:05:22.000Z
+                publishedBy: bo@example.com
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: versions
+      positional:
+        - id
 /api/admin/configs/{id}/schema:
   patch:
     operationId: updateConfigSchema

package/spec/paths/errors.yaml

@@ -73,6 +73,9 @@
                 lastSeenAt: 2026-06-28T14:55:31.000Z
                 createdAt: 2026-06-20T08:11:02.000Z
                 updatedAt: 2026-06-28T14:55:31.000Z
+                assigneeId: null
+                assigneeConnectorId: null
+                assigneeAgent: null
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -96,9 +99,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:
@@ -142,6 +145,38 @@
               lastSeenAt: 2026-06-28T14:55:31.000Z
               createdAt: 2026-06-20T08:11:02.000Z
               updatedAt: 2026-06-28T14:55:31.000Z
+              assigneeId: 6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c
+              assigneeConnectorId: null
+              assigneeAgent: null
+              occurrences:
+                - id: occ_01j7w7qq0v3k9d2m5rc8t1xh4n
+                  projectId: e976b15e-2f0d-4c6e-9b1a-3a7c1f2d8e90
+                  errorId: err_01j7w7m9q4hxbf6npe6s9zr3vc
+                  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
+                  projectId: e976b15e-2f0d-4c6e-9b1a-3a7c1f2d8e90
+                  errorId: err_01j7w7m9q4hxbf6npe6s9zr3vc
+                  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":
@@ -232,6 +267,9 @@
               lastSeenAt: 2026-06-28T14:55:31.000Z
               createdAt: 2026-06-20T08:11:02.000Z
               updatedAt: 2026-06-28T15:02:10.000Z
+              assigneeId: null
+              assigneeConnectorId: null
+              assigneeAgent: null
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -303,6 +341,78 @@
       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
+              assigneeId: null
+              assigneeConnectorId: null
+              assigneeAgent: null
+      "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

package/spec/paths/events.yaml

@@ -127,6 +127,7 @@
       - FORBIDDEN
       - ALREADY_EXISTS
       - VALIDATION
+      - PLAN_LIMIT
     x-cli:
       name: create
       positional: