@shipeasy/openapi 2.1.0 → 2.3.0

package/spec/paths/gates.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 feature gates
@@ -163,6 +164,19 @@
             example:
               id: gat_01j7w7m9q4hxbf6npe6s9zr3vc
               name: checkout_v2
+        links:
+          UpdateGate:
+            operationId: updateGate
+            parameters: { id: $response.body#/id }
+          EnableGate:
+            operationId: enableGate
+            parameters: { id: $response.body#/id }
+          DisableGate:
+            operationId: disableGate
+            parameters: { id: $response.body#/id }
+          DeleteGate:
+            operationId: deleteGate
+            parameters: { id: $response.body#/id }
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -181,6 +195,7 @@
       - FORBIDDEN
       - ALREADY_EXISTS
       - VALIDATION
+      - PLAN_LIMIT
     x-cli:
       name: create
       positional:
@@ -211,7 +226,7 @@
         required: true
         description: Stable opaque gate id (`gat_…`) or the gate's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -317,7 +332,7 @@
         required: true
         description: Stable opaque gate id (`gat_…`) or the gate's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Delete a feature gate
@@ -366,9 +381,9 @@
         required: true
         description: Stable opaque gate id (`gat_…`) or the gate's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
-      "201":
+      "200":
         description: Enable a gate
         content:
           application/json:
@@ -416,9 +431,9 @@
         required: true
         description: Stable opaque gate id (`gat_…`) or the gate's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
-      "201":
+      "200":
         description: Disable a gate
         content:
           application/json:

package/spec/paths/i18n.yaml

@@ -73,6 +73,10 @@
             example:
               id: i18n_01j7w8a1b2c4
               name: fr:prod
+        links:
+          PublishI18nProfile:
+            operationId: publishI18nProfile
+            parameters: { profileId: $response.body#/id }
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -120,9 +124,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
+          maxLength: 100
       - name: limit
         in: query
         required: false
@@ -131,6 +136,14 @@
           type: integer
           minimum: 1
           maximum: 500
+      - name: offset
+        in: query
+        required: false
+        description: Number of keys to skip before returning `limit` rows (offset pagination).
+        schema:
+          type: integer
+          minimum: 0
+          default: 0
     responses:
       "200":
         description: List i18n keys
@@ -235,7 +248,7 @@
         required: true
         description: The key's id.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -383,7 +396,7 @@
         required: true
         description: The draft id to update.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -441,7 +454,7 @@
         required: true
         description: The profile id to publish.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -451,7 +464,7 @@
           example:
             chunk: default
     responses:
-      "201":
+      "200":
         description: Publish a profile chunk
         content:
           application/json:

package/spec/paths/keys.yaml

@@ -14,6 +14,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 API keys
@@ -127,6 +128,7 @@
       - UNAUTHORIZED
       - FORBIDDEN
       - VALIDATION
+      - PLAN_LIMIT
     x-cli:
       name: create
 /api/admin/keys/{id}/revoke:
@@ -148,7 +150,7 @@
         required: true
         description: Stable opaque key id (UUID) returned by `create` / `list`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Revoke an API key

package/spec/paths/killswitches.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 killswitches
@@ -114,6 +115,22 @@
             example:
               id: ksw_01j7w9d8h2k4m6n8p0q2r4s6t8
               name: payments.checkout
+        links:
+          GetKillswitch:
+            operationId: getKillswitch
+            parameters: { id: $response.body#/id }
+          UpdateKillswitch:
+            operationId: updateKillswitch
+            parameters: { id: $response.body#/id }
+          SetKillswitchSwitch:
+            operationId: setKillswitchSwitch
+            parameters: { id: $response.body#/id }
+          SetKillswitchValue:
+            operationId: setKillswitchValue
+            parameters: { id: $response.body#/id }
+          DeleteKillswitch:
+            operationId: deleteKillswitch
+            parameters: { id: $response.body#/id }
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -132,6 +149,7 @@
       - FORBIDDEN
       - ALREADY_EXISTS
       - VALIDATION
+      - PLAN_LIMIT
     x-cli:
       name: create
       positional:
@@ -153,7 +171,7 @@
         required: true
         description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Get one killswitch
@@ -225,7 +243,7 @@
         required: true
         description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -302,7 +320,7 @@
         required: true
         description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Delete a killswitch
@@ -355,7 +373,7 @@
         required: true
         description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -429,7 +447,7 @@
         required: true
         description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -498,7 +516,7 @@
         required: true
         description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:

package/spec/paths/metrics.yaml

@@ -10,6 +10,7 @@
       - Metrics
     parameters:
       - $ref: ../components/parameters.yaml#/ProjectId
+      - $ref: ../components/parameters.yaml#/Q
     responses:
       "200":
         description: List metrics
@@ -110,6 +111,16 @@
             example:
               id: met_01j7w8a1b2c3d4e5f6g7h8i9j0
               name: checkouts
+        links:
+          GetMetric:
+            operationId: getMetric
+            parameters: { id: $response.body#/id }
+          UpdateMetric:
+            operationId: updateMetric
+            parameters: { id: $response.body#/id }
+          DeleteMetric:
+            operationId: deleteMetric
+            parameters: { id: $response.body#/id }
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -130,6 +141,7 @@
       - EVENT_PENDING
       - REFERENCED_NOT_FOUND
       - VALIDATION
+      - PLAN_LIMIT
     x-cli:
       name: create
       positional:
@@ -151,7 +163,7 @@
         required: true
         description: Stable opaque metric id (`met_…`) or the metric's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Get a metric
@@ -209,7 +221,7 @@
         required: true
         description: Stable opaque metric id (`met_…`) or the metric's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -268,7 +280,7 @@
         required: true
         description: Stable opaque metric id (`met_…`) or the metric's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Archive a metric

package/spec/paths/ops.yaml

@@ -176,7 +176,7 @@
         required: true
         description: Per-project item number (e.g. `7`) or the full ops item id.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Get one queue item
@@ -235,7 +235,7 @@
         required: true
         description: Per-project item number (e.g. `7`) or the full ops item id.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -303,7 +303,7 @@
         required: true
         description: Per-project item number (e.g. `7`) or the full ops item id.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -344,6 +344,117 @@
       name: link-pr
       positional:
         - handle
+/api/admin/ops/{handle}/comments:
+  get:
+    operationId: listOpsComments
+    summary: List an item's comments
+    description: |-
+      List the comment thread on a queue item, oldest first. Each comment
+      carries its author (a teammate email, or `system` for a comment authored by
+      Jarvis — the AI agent), its markdown body, and `parentId` for the single
+      level of threaded replies. Removed comments are omitted.
+
+      **Use case:** Read the discussion on an item before replying or acting on it.
+    tags:
+      - Comments
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: handle
+        in: path
+        required: true
+        description: Per-project item number (e.g. `7`) or the full ops item id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: List an item's comments
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/ListOpsCommentsResponse
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: list
+      positional:
+        - handle
+  post:
+    operationId: createOpsComment
+    summary: Comment on an item
+    description: |-
+      Append a comment to a queue item's thread. The body is markdown (mentions
+      like `@teammate` notify that person; `@shipeasy` asks Jarvis, the AI agent,
+      to reply). Pass `parentId` to reply under an existing top-level comment
+      (one level of threading — a reply to a reply attaches to the same parent).
+
+      Create-only and append-only, so it is safe for restricted ops keys — the
+      same channel the ops loop and Jarvis use to leave a note on an item.
+    tags:
+      - Comments
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: handle
+        in: path
+        required: true
+        description: Per-project item number (e.g. `7`) or the full ops item id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/ops.yaml#/CreateOpsCommentRequest
+          examples:
+            comment:
+              summary: Leave a comment
+              value:
+                body: "Repro'd on iOS Safari 17 — the button overflows its container. cc @alice"
+            reply:
+              summary: Reply under an existing comment
+              value:
+                body: "Agreed, let's ship the fix behind @shipeasy's suggested flag."
+                parentId: cm_01j7w8a1b2c3d4e5f6g7h8i9j0
+    responses:
+      "201":
+        description: Comment on an item
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/CreateOpsCommentResponse
+            example:
+              id: cm_01j7w8a1b2c3d4e5f6g7h8i9j0
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: create
+      positional:
+        - handle
 /api/admin/notifications:
   post:
     operationId: notifyOps

package/spec/paths/projects.yaml

@@ -22,7 +22,7 @@
               name: Acme
               domain: acme.com
               ownerEmail: owner@acme.com
-              plan: paid
+              plan: pro
               status: active
               subscriptionStatus: active
               billingInterval: monthly
@@ -144,7 +144,7 @@
         required: true
         description: Stable opaque project id. Must match the caller's own project.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -172,7 +172,7 @@
               name: Acme Rockets
               domain: acme.com
               ownerEmail: owner@acme.com
-              plan: paid
+              plan: pro
               status: active
               subscriptionStatus: active
               billingInterval: monthly

package/spec/paths/universes.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 universes
@@ -100,6 +101,13 @@
             example:
               id: uni_01j7w8a1b2c3d4e5f6g7h8i9j0
               name: primary_users
+        links:
+          UpdateUniverse:
+            operationId: updateUniverse
+            parameters: { id: $response.body#/id }
+          DeleteUniverse:
+            operationId: deleteUniverse
+            parameters: { id: $response.body#/id }
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -119,6 +127,7 @@
       - PLAN_REQUIRED
       - ALREADY_EXISTS
       - VALIDATION
+      - PLAN_LIMIT
     x-cli:
       name: create
       positional:
@@ -145,7 +154,7 @@
         required: true
         description: Stable opaque universe id (`uni_…`) or the universe's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -213,7 +222,7 @@
         required: true
         description: Stable opaque universe id (`uni_…`) or the universe's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Delete a universe