@shipeasy/openapi 3.2.0 → 3.3.0

package/spec/components/schemas/tags.yaml

@@ -0,0 +1,91 @@
+TaggableEntityType:
+  type: string
+  enum:
+    - ops
+    - flag
+    - config
+    - killswitch
+    - metric
+    - error
+    - alert_rule
+    - experiment
+  description: >-
+    The kind of item a tag set hangs off: `ops` (any queue item — bug, feature
+    request, error/alert/measure-plan ticket), `flag` (feature gate), `config`
+    (dynamic config), `killswitch`, `metric`, `error` (tracked error group),
+    `alert_rule`, or `experiment`.
+TagName:
+  type: string
+  minLength: 1
+  maxLength: 64
+  description: A tag name. Trimmed; matched case-insensitively against the project's existing tags.
+Tag:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Stable opaque tag id.
+    name:
+      type: string
+      description: Display name — also the tag's identity, unique case-insensitively within the project.
+  required:
+    - id
+    - name
+  additionalProperties: false
+ListTagsResponse:
+  type: array
+  items:
+    $ref: "#/Tag"
+  description: The project's tags, sorted by name.
+EntityTagsResponse:
+  type: object
+  properties:
+    entityType:
+      $ref: "#/TaggableEntityType"
+    entityId:
+      type: string
+      description: The item's canonical id (the handle you passed, resolved).
+    tags:
+      type: array
+      items:
+        type: string
+      description: The tag names now attached to the item, sorted by name.
+  required:
+    - entityType
+    - entityId
+    - tags
+  additionalProperties: false
+SetEntityTagsRequest:
+  type: object
+  properties:
+    tags:
+      type: array
+      maxItems: 50
+      items:
+        $ref: "#/TagName"
+      description: >-
+        The complete tag set the item should carry — tags not listed are
+        detached. Names are get-or-created (a new name mints a project tag),
+        deduped case-insensitively; `[]` clears every tag.
+  required:
+    - tags
+  additionalProperties: false
+UpdateEntityTagsRequest:
+  type: object
+  properties:
+    add:
+      type: array
+      maxItems: 50
+      items:
+        $ref: "#/TagName"
+      default: []
+      description: Tag names to attach (get-or-created by name, case-insensitive). Already-attached names are a no-op.
+    remove:
+      type: array
+      maxItems: 50
+      items:
+        $ref: "#/TagName"
+      default: []
+      description: Tag names to detach (case-insensitive). Names the item doesn't carry are a no-op. A name in both lists is removed.
+  additionalProperties: false
+  description: Incremental tag edit — pass `add`, `remove`, or both. Every other tag on the item is left as is.

package/spec/openapi.yaml

@@ -218,6 +218,24 @@ tags:
       the AI-write seam the cockpit's detail panel renders: `list` reads what a
       previous run found, `create` appends a new record, and `update` fills in the
       `working` run record you were handed (findings, PR, confidence) as you work.
+  - name: Questions
+    parent: Ops
+    description: |-
+      Structured questions an agent asks the team about a queue item — the
+      `AskUserQuestion` shape: a short `header`, the `question`, 2–4 `options`
+      (label + description), and `multiSelect` for checkboxes instead of radios.
+      Every question also accepts a free-text "Other" answer. Open questions sit
+      at the very top of the item's detail panel and mark the row in the queue.
+
+      **Asking.** `ask` posts 1–4 questions at once. Several agents (or several
+      runs) may have questions open on the same item at the same time.
+
+      **Getting the answer back.** `delivery: resume` (the default for a run
+      launched through a trigger connector) re-fires that same agent on the
+      item once every question its run asked is answered, continuing the same
+      run record with the answers in the prompt. `delivery: poll` (the default
+      for a live, connector-less session such as Claude Code in a terminal)
+      fires nothing — call `list` until the status reads `completed`.
   - name: Projects
     description: |-
       Projects: the account-level container every other resource is scoped to.
@@ -260,6 +278,19 @@ tags:
       Continue) schedule on their own surface — typically a GitHub Actions
       `schedule:` cron running the platform's headless CLI with the shared
       trigger prompt.
+  - name: Tags
+    description: |-
+      Tags: free-form, project-scoped labels any item can carry — queue items
+      (bugs, feature requests, error/alert tickets), flags, configs, kill
+      switches, metrics, tracked errors, alert rules, and experiments all share
+      one tag roster.
+
+      **Identity.** A tag is its name, unique case-insensitively per project. A
+      tag is born the first time it's attached — there is no separate create.
+
+      **Addressing.** An item is named by `entityType` + its handle (an ops
+      item's number, a resource's name, or any id). `set` replaces the full tag
+      set; `update` adds/removes names incrementally.
   - name: Connectors
     description: |-
       Outbound integrations: the per-project destinations feedback + trigger
@@ -370,6 +401,12 @@ paths:
     $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1investigation
   /api/admin/ops/{handle}/investigation/{investigationId}:
     $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1investigation~1{investigationId}
+  /api/admin/ops/{handle}/questions:
+    $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1questions
+  /api/admin/ops/{handle}/questions/{questionId}/answer:
+    $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1questions~1{questionId}~1answer
+  /api/admin/ops/{handle}/questions/{questionId}/cancel:
+    $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1questions~1{questionId}~1cancel
   /api/admin/agent-profiles:
     $ref: ./paths/ops.yaml#/~1api~1admin~1agent-profiles
   /api/admin/ops/{handle}/comments:
@@ -434,10 +471,16 @@ paths:
     $ref: ./paths/connectors.yaml#/~1api~1admin~1connectors~1trigger
   /api/admin/keys:
     $ref: ./paths/keys.yaml#/~1api~1admin~1keys
+  /api/admin/keys/{id}:
+    $ref: ./paths/keys.yaml#/~1api~1admin~1keys~1{id}
   /api/admin/keys/{id}/revoke:
     $ref: ./paths/keys.yaml#/~1api~1admin~1keys~1{id}~1revoke
   /api/admin/search:
     $ref: ./paths/search.yaml#/~1api~1admin~1search
+  /api/admin/tags:
+    $ref: ./paths/tags.yaml#/~1api~1admin~1tags
+  /api/admin/tags/{entityType}/{entityId}:
+    $ref: ./paths/tags.yaml#/~1api~1admin~1tags~1{entityType}~1{entityId}
 components:
   securitySchemes:
     bearerSdkKey:

package/spec/paths/alerts.yaml

@@ -5,7 +5,9 @@
     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`.
+      A fired alert is an **instance** of an alert rule, and an instance IS its ops queue item — the same row `/api/admin/ops` returns with `type: "alert"`, viewed through the alert lens. One rule produces many instances over its life and at most one is open at a time: when the condition clears the instance closes, and the next firing is a NEW instance with its own id and history. That is why `severity` reads off the rule (the queue item carries it as `priority`) and why resolving the queue item and clearing the alert are one act, not two rows to keep in step.
+
+      Instances are opened 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:
@@ -89,7 +91,7 @@
     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.
+      - **`status`** — flip between `active` / `resolved` / `dismissed`. `resolved` and `dismissed` stamp `resolvedAt` / `dismissedAt`; `active` re-opens and clears both. These write the underlying queue item's own status (`resolved` / `wont_fix` / `open`), so clearing an alert here and resolving it in the ops queue are the same act. A cleared instance is never revived: if the condition fires again it opens a NEW instance with its own id.
       - **`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.
 
@@ -106,7 +108,7 @@
       - name: id
         in: path
         required: true
-        description: Stable opaque alert id (`al_…`).
+        description: Stable opaque instance id — the same id as the `alert` ops item this instance is.
         schema:
           $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:

package/spec/paths/i18n.yaml

@@ -128,11 +128,12 @@
       - name: limit
         in: query
         required: false
-        description: Max keys to return (1–500).
+        description: Max keys to return (1–500). Defaults to 200.
         schema:
           type: integer
           minimum: 1
           maximum: 500
+          default: 200
       - name: offset
         in: query
         required: false

package/spec/paths/keys.yaml

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

package/spec/paths/metrics.yaml

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