@shipeasy/openapi 2.4.0 → 2.5.0

package/spec/components/schemas/configs.yaml

@@ -223,12 +223,26 @@ CreateConfigRequest:
       additionalProperties: {}
       description: JSON Schema (draft 2020-12) describing the shape of the config value. Top-level `type` must be `'object'`; every published value is validated against this schema.
     value:
+      type: object
+      additionalProperties: {}
       description: "Initial config value. Either a single JSON object applied to every env, or a `{ env: value }` map seeding per-env values. Must match `schema`. Defaults to `{}` on every env when omitted."
+    dev:
+      type: object
+      additionalProperties: {}
+      description: "Seed the **dev** env's initial value (version 1), overriding `value` for dev. Published immediately. Must match `schema`."
+    staging:
+      type: object
+      additionalProperties: {}
+      description: "Seed the **staging** env's initial value (version 1), overriding `value` for staging. Published immediately. Must match `schema`."
+    prod:
+      type: object
+      additionalProperties: {}
+      description: "Seed the **prod** env's initial value (version 1), overriding `value` for prod. Published immediately. Must match `schema`."
   required:
     - name
     - schema
   additionalProperties: false
-  description: Body for `POST /api/admin/configs`. `name` + `schema` required.
+  description: "Body for `POST /api/admin/configs`. `name` + `schema` required. Per-env `dev`/`staging`/`prod` values are published to that env at version 1 (overriding `value`)."
 CreateConfigResponse:
   type: object
   properties:
@@ -251,11 +265,25 @@ UpdateConfigRequest:
       type: object
       additionalProperties: {}
     value:
-      description: Flat value applied to **every** env. Publishes a new version per env. To target one env, use `PUT /{id}/drafts` then `POST /{id}/publish`.
+      type: object
+      additionalProperties: {}
+      description: Flat value applied to **every** env. Publishes a new version per env. To publish one env only, pass that env's key (`dev`/`staging`/`prod`) instead.
+    dev:
+      type: object
+      additionalProperties: {}
+      description: "Publish a new version to the **dev** env only, immediately (no draft). Overrides `value` for dev. Must match the effective schema."
+    staging:
+      type: object
+      additionalProperties: {}
+      description: "Publish a new version to the **staging** env only, immediately (no draft). Overrides `value` for staging. Must match the effective schema."
+    prod:
+      type: object
+      additionalProperties: {}
+      description: "Publish a new version to the **prod** env only, immediately (no draft). Overrides `value` for prod. Must match the effective schema."
     folder:
       $ref: ./common.yaml#/Folder
   additionalProperties: false
-  description: Body for `PATCH /api/admin/configs/{id}`. Partial — only supplied fields change. `value` republishes on every env.
+  description: "Body for `PATCH /api/admin/configs/{id}`. Partial — only supplied fields change. `value` republishes on every env; per-env `dev`/`staging`/`prod` publish a new version to just that env."
 UpdateConfigResponse:
   type: object
   properties:
@@ -300,6 +328,8 @@ SaveConfigDraftRequest:
     env:
       $ref: ./common.yaml#/Env
     value:
+      type: object
+      additionalProperties: {}
       description: Draft value to stage on `env`. Validated against the config's current schema.
   required:
     - env

package/spec/components/schemas/gates.yaml

@@ -205,6 +205,9 @@ GateApiRow:
                   locked:
                     description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
                     type: boolean
+                  whitelist:
+                    description: Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first "whitelist" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.
+                    type: boolean
                 required:
                   - id
                   - type
@@ -517,6 +520,9 @@ CreateGateRequest:
                   locked:
                     description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
                     type: boolean
+                  whitelist:
+                    description: Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first "whitelist" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.
+                    type: boolean
                 required:
                   - id
                   - type
@@ -802,6 +808,9 @@ UpdateGateRequest:
                   locked:
                     description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
                     type: boolean
+                  whitelist:
+                    description: Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first "whitelist" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.
+                    type: boolean
                 required:
                   - id
                   - type

package/spec/components/schemas/metrics.yaml

@@ -487,6 +487,11 @@ MetricDirection:
     - lower_better
     - neutral
   description: Desired direction of movement. `higher_better` (default), `lower_better`, or `neutral` (guardrail).
+MetricDisplayUnit:
+  description: Display unit (e.g. `ms`, `%`, `$`), or `null` when unitless.
+  anyOf:
+    - type: string
+    - type: "null"
 CreateMetricRequest:
   oneOf:
     - $ref: "#/CreateMetricWithQuery"
@@ -509,6 +514,8 @@ CreateMetricWithQuery:
       $ref: "#/MetricDefaultMinEffectOfInterest"
     direction:
       $ref: "#/MetricDirection"
+    unit:
+      $ref: "#/MetricDisplayUnit"
   required:
     - name
     - event_name
@@ -532,6 +539,8 @@ CreateMetricWithQueryIr:
       $ref: "#/MetricDefaultMinEffectOfInterest"
     direction:
       $ref: "#/MetricDirection"
+    unit:
+      $ref: "#/MetricDisplayUnit"
   required:
     - name
     - event_name
@@ -559,6 +568,8 @@ UpdateMetricWithQuery:
       $ref: "#/MetricDefaultMinEffectOfInterest"
     direction:
       $ref: "#/MetricDirection"
+    unit:
+      $ref: "#/MetricDisplayUnit"
   required:
     - query
   additionalProperties: false
@@ -578,6 +589,8 @@ UpdateMetricWithQueryIr:
       $ref: "#/MetricDefaultMinEffectOfInterest"
     direction:
       $ref: "#/MetricDirection"
+    unit:
+      $ref: "#/MetricDisplayUnit"
   required:
     - query_ir
   additionalProperties: false
@@ -595,8 +608,10 @@ UpdateMetricFields:
       $ref: "#/MetricDefaultMinEffectOfInterest"
     direction:
       $ref: "#/MetricDirection"
+    unit:
+      $ref: "#/MetricDisplayUnit"
   additionalProperties: false
-  description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction).
+  description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction, display unit).
 CreateMetricResponse:
   type: object
   properties:

package/spec/components/schemas/ops.yaml

@@ -356,6 +356,11 @@ OpsRun:
         - type: string
         - type: "null"
       description: The agent-run session id recorded on the ack (dashboard deep-links to the run page), or `null`.
+    sessionUrl:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "The run's session-page deep link, or `null`. DERIVED (never stored): rebuilt from `sessionId` + the run's trigger connector — Claude's routine id (`?trigger=`), Copilot's repo (`/tasks/`), Cursor/Jules from the id alone."
     startedAt:
       type: string
       description: ISO-8601 timestamp the run started (the ack time).
@@ -365,15 +370,7 @@ OpsRun:
         - type: "null"
       description: ISO-8601 timestamp the run closed, or `null` while still open.
     completedAction:
-      anyOf:
-        - type: string
-          enum:
-            - link_pr
-            - notify
-            - status
-            - superseded
-        - type: "null"
-      description: "Which final action closed the run — `link_pr`/`notify` are the agent's terminal ops actions, `status` a completion status flip (ready_for_qa/resolved), `superseded` a newer ack replacing it. `null` while the run is open."
+      $ref: "#/OpsRunActionOrNull"
     prNumber:
       anyOf:
         - type: number
@@ -390,6 +387,7 @@ OpsRun:
     - connectorId
     - ackedBy
     - sessionId
+    - sessionUrl
     - startedAt
     - completedAt
     - completedAction
@@ -918,6 +916,28 @@ CreateBugRequest:
         - $ref: "#/OpsItemPriority"
         - type: "null"
       description: Initial triage priority, or `null`.
+    status:
+      anyOf:
+        - $ref: "#/OpsItemStatus"
+      description: Initial lifecycle status; defaults to `open` when omitted.
+    assigneeId:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: The `users.id` of the person to assign as owner at creation, or `null`.
+    subscribers:
+      type: array
+      items:
+        type: string
+        format: email
+      default: []
+      description: Emails of teammates to subscribe to this item's Slack pings at creation.
+    tags:
+      type: array
+      items:
+        type: string
+      default: []
+      description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
     reporterEmail:
       anyOf:
         - type: string
@@ -987,6 +1007,28 @@ CreateFeatureRequestRequest:
         - $ref: "#/OpsItemPriority"
         - type: "null"
       description: Initial triage priority, or `null`.
+    status:
+      anyOf:
+        - $ref: "#/OpsItemStatus"
+      description: Initial lifecycle status; defaults to `open` when omitted.
+    assigneeId:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: The `users.id` of the person to assign as owner at creation, or `null`.
+    subscribers:
+      type: array
+      items:
+        type: string
+        format: email
+      default: []
+      description: Emails of teammates to subscribe to this item's Slack pings at creation.
+    tags:
+      type: array
+      items:
+        type: string
+      default: []
+      description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
     reporterEmail:
       anyOf:
         - type: string
@@ -1127,6 +1169,22 @@ OpsItemNotifyOrNull:
     - $ref: ./common.yaml#/NotificationTarget
     - type: "null"
   description: Where this item's completion notification lands, or `null`.
+OpsRunAction:
+  type: string
+  enum:
+    - link_pr
+    - notify
+    - status
+    - superseded
+  description: >-
+    The final action that closed a run record — `link_pr`/`notify` are the
+    agent's terminal ops actions, `status` a completion status flip
+    (ready_for_qa/resolved), `superseded` a newer ack replacing an open run.
+OpsRunActionOrNull:
+  anyOf:
+    - $ref: "#/OpsRunAction"
+    - type: "null"
+  description: Which final action closed the run, or `null` while it is open (or a non-run record).
 UpdateOpsItemStatusRequest:
   type: object
   properties:
@@ -1681,22 +1739,19 @@ OpsInvestigation:
       anyOf:
         - type: string
         - type: "null"
-      description: The agent-run session id, or `null`.
-    ackedBy:
+      description: "The agent-run session id, or `null`."
+    sessionUrl:
       anyOf:
         - type: string
         - type: "null"
-      description: Email of the human who acked (run records for a human ack), or `null`.
-    completedAction:
+      description: "The run's session-page deep link, or `null`. DERIVED (never stored): rebuilt from `sessionId` + the run's trigger connector — Claude's routine id (`?trigger=`), Copilot's repo (`/tasks/`), Cursor/Jules from the id alone. Only `working` run records carry one."
+    ackedBy:
       anyOf:
         - type: string
-          enum:
-            - link_pr
-            - notify
-            - status
-            - superseded
         - type: "null"
-      description: "Which final action closed a `working` run record, or `null` (open run / non-run record)."
+      description: Email of the human who acked (run records for a human ack), or `null`.
+    completedAction:
+      $ref: "#/OpsRunActionOrNull"
     createdAt:
       type: string
       description: ISO-8601 creation timestamp.
@@ -1724,6 +1779,7 @@ OpsInvestigation:
     - startedAt
     - completedAt
     - sessionId
+    - sessionUrl
     - ackedBy
     - completedAction
     - createdAt
@@ -1840,6 +1896,94 @@ CreateOpsInvestigationRequest:
     - kind
   additionalProperties: false
   description: "Body for `POST /api/admin/ops/{handle}/investigation`. `kind` is required; include at least one content field (`summary`/`findings`/`question`/`qaNotes`) — the panel renders whatever it gets."
+UpdateOpsInvestigationRequest:
+  type: object
+  properties:
+    kind:
+      type: string
+      enum:
+        - investigated
+        - detected
+        - question
+        - ready_for_qa
+        - working
+        - note
+      description: Reclassify the record's lifecycle stage (e.g. flip a `working` run into `investigated` once findings land).
+    summary:
+      type: string
+      maxLength: 2000
+      description: One-line summary of the record.
+    findings:
+      type: string
+      maxLength: 50000
+      description: The full findings write-up (markdown).
+    question:
+      type: string
+      maxLength: 10000
+      description: A blocking question for the team (markdown).
+    qaNotes:
+      type: string
+      maxLength: 50000
+      description: How to verify the fix — QA notes (markdown).
+    model:
+      type: string
+      maxLength: 200
+      description: The model the agent ran on.
+    prNumber:
+      type: integer
+      description: A PR the record references.
+    prUrl:
+      type: string
+      format: uri
+      maxLength: 2000
+      description: HTML URL of that PR.
+    sources:
+      type: array
+      maxItems: 200
+      items:
+        type: object
+        properties:
+          path:
+            type: string
+            description: Repo-relative file path inspected.
+          url:
+            type: string
+            description: External link consulted.
+          label:
+            type: string
+            description: Human-readable label for the source.
+        additionalProperties: false
+        description: One file/link inspected while producing the record.
+      description: The files/links inspected.
+    confidence:
+      type: string
+      enum:
+        - low
+        - medium
+        - high
+      description: Self-reported confidence in the record.
+    tokensUsed:
+      type: integer
+      description: Tokens the run consumed.
+    durationMs:
+      type: integer
+      description: Run duration in milliseconds.
+    visibility:
+      type: string
+      enum:
+        - draft
+        - published
+      description: Record visibility. `draft` keeps it out of the panel; `published` surfaces it.
+    completedAt:
+      type: string
+      description: ISO-8601 timestamp the work finished. Set it (or flip `kind` off `working`) to mark a run record done.
+    sessionId:
+      type: string
+      maxLength: 300
+      description: The agent-run session id, so the dashboard can deep-link to the run.
+  additionalProperties: false
+  minProperties: 1
+  description: "Body for `PATCH /api/admin/ops/{handle}/investigation/{investigationId}` — a partial update of one existing investigation record (typically the `working` run record you were handed). Send only the fields you want to change; at least one is required."
 NotificationFeedItem:
   type: object
   properties:

package/spec/openapi.yaml

@@ -209,6 +209,15 @@ tags:
       **Mentions.** `@teammate` in a body raises an in-app notification for that
       person; `@shipeasy` asks Jarvis (the AI agent) to read the item and reply.
       Comments authored by Jarvis carry `authorType: system`.
+  - name: Investigations
+    parent: Ops
+    description: |-
+      Investigation records on a queue item — the structured, read-only write-ups
+      an AI agent produces while working it (findings / a blocking question / QA
+      notes), plus the `working` run rows an ack or an AI hand-off opens. This is
+      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: Projects
     description: |-
       Projects: the account-level container every other resource is scoped to.
@@ -351,6 +360,8 @@ paths:
     $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1ack
   /api/admin/ops/{handle}/investigation:
     $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/agent-profiles:
     $ref: ./paths/ops.yaml#/~1api~1admin~1agent-profiles
   /api/admin/ops/{handle}/comments:

package/spec/paths/configs.yaml

@@ -87,7 +87,7 @@
 
       - **Minimal create** — `name` + `schema`. Initial value defaults to `{}`.
       - **Seeded create** — supply a flat `value` to publish the same object on every env.
-      - **Per-env seed** — supply a `{ env: value }` map for different per-env starting values.
+      - **Per-env seed** — supply a `{ env: value }` map under `value`, or pass the env keys `dev`/`staging`/`prod` directly (each overrides `value` for that env and is published at version 1).
     tags:
       - Configs
     parameters:
@@ -129,8 +129,8 @@
                     - name: free
                     - name: pro
             perEnvSeed:
-              summary: Per-env seed
-              description: "Pass a `{ env: value }` map to seed different initial values per env."
+              summary: Per-env seed (env keys)
+              description: "Pass the env keys directly to seed different initial values per env. Each overrides `value` for that env and is published at version 1."
               value:
                 name: pricing.tiers
                 schema:
@@ -140,20 +140,15 @@
                       type: array
                   required:
                     - tiers
-                value:
-                  dev:
-                    tiers:
-                      - name: free
-                      - name: pro
-                      - name: enterprise
-                  stage:
-                    tiers:
-                      - name: free
-                      - name: pro
-                  prod:
-                    tiers:
-                      - name: free
-                      - name: pro
+                dev:
+                  tiers:
+                    - name: free
+                    - name: pro
+                    - name: enterprise
+                prod:
+                  tiers:
+                    - name: free
+                    - name: pro
     responses:
       "201":
         description: Create a dynamic config
@@ -302,15 +297,13 @@
     operationId: updateConfig
     summary: Update a dynamic config
     description: |-
-      Partial update. When `value` is supplied it is **republished on every env** (new version per env). When `schema` is supplied it replaces the current schema; every existing value is re-validated.
-
-      For env-scoped edits, use the draft/publish flow (`PUT /{id}/drafts` then `POST /{id}/publish`) instead.
+      Partial update. When `value` is supplied it is **republished on every env** (new version per env). A per-env key (`dev`/`staging`/`prod`) publishes a new version to **only that env**, immediately, overriding `value` for it. When `schema` is supplied it replaces the current schema; every existing value is re-validated.
 
       **Use cases**
 
       - **Republish flat value** — `{ "value": {…} }` sets the same value on every env.
+      - **Publish one env** — `{ "prod": {…} }` publishes a new version to prod only, instantly.
       - **Schema migration** — `{ "schema": {…} }` replaces the schema; existing values are re-validated.
-      - **Env-scoped edits** — use `PUT /{id}/drafts` + `POST /{id}/publish` instead of PATCH.
     tags:
       - Configs
     parameters:
@@ -336,6 +329,15 @@
                   tiers:
                     - name: free
                     - name: pro
+            prodOnly:
+              summary: Per-env — publish prod only
+              description: Publishes a new version to prod only, immediately. dev/staging untouched.
+              value:
+                prod:
+                  tiers:
+                    - name: free
+                    - name: pro
+                    - name: enterprise
             schemaOnly:
               summary: Schema-only update
               description: Replaces the schema. Existing values must still validate or the update fails.
@@ -496,6 +498,7 @@
       - VALIDATION
     x-cli:
       name: draft
+      hidden: true
       positional:
         - id
   delete:
@@ -555,6 +558,7 @@
       - NOT_FOUND
     x-cli:
       name: discard-draft
+      hidden: true
       positional:
         - id
 /api/admin/configs/{id}/publish:
@@ -626,6 +630,7 @@
       - VALIDATION
     x-cli:
       name: publish
+      hidden: true
       positional:
         - id
 /api/admin/configs/{id}/activity:
@@ -690,6 +695,7 @@
       - NOT_FOUND
     x-cli:
       name: activity
+      hidden: true
       positional:
         - id
 /api/admin/configs/{id}/versions:
@@ -756,6 +762,7 @@
       - NOT_FOUND
     x-cli:
       name: versions
+      hidden: true
       positional:
         - id
 /api/admin/configs/{id}/schema:

package/spec/paths/ops.yaml

@@ -505,7 +505,7 @@
       **Use case:** Read what a previous agent run already found before starting
       your own investigation of the item.
     tags:
-      - Ops
+      - Investigations
     parameters:
       - $ref: ../components/parameters.yaml#/ProjectId
       - name: handle
@@ -536,6 +536,10 @@
       - UNAUTHORIZED
       - FORBIDDEN
       - NOT_FOUND
+    x-cli:
+      name: list
+      positional:
+        - handle
   post:
     operationId: createOpsInvestigation
     summary: Record an investigation
@@ -551,7 +555,7 @@
       markdown findings, sources inspected, confidence) so the team — and the
       next agent run — sees what you learned.
     tags:
-      - Ops
+      - Investigations
     parameters:
       - $ref: ../components/parameters.yaml#/ProjectId
       - name: handle
@@ -609,6 +613,85 @@
       - FORBIDDEN
       - NOT_FOUND
       - VALIDATION
+    x-cli:
+      name: create
+      positional:
+        - handle
+/api/admin/ops/{handle}/investigation/{investigationId}:
+  patch:
+    operationId: updateOpsInvestigation
+    summary: Update an investigation record
+    description: |-
+      Update one existing investigation record in place — the write-back seam for
+      the `working` run record you were handed when a run was launched. Fill in
+      the `summary`/`findings`, attach the fixing PR, record your `confidence`
+      and the `sources` you inspected, or flip its `kind` off `working` once the
+      investigation is done. A partial patch: send only the fields you want to
+      change. Safe for restricted ops keys (it never reads or deletes).
+
+      **Use case:** A run started with an empty `working` record; as you work,
+      PATCH it with your findings so the cockpit's detail panel fills in live —
+      no need to append a second record.
+    tags:
+      - Investigations
+    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
+      - name: investigationId
+        in: path
+        required: true
+        description: The investigation record id (from `POST`/`GET .../investigation` or the `runId` an ack/launch returned).
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/ops.yaml#/UpdateOpsInvestigationRequest
+          examples:
+            findings:
+              summary: Fill in the run record's findings
+              value:
+                kind: investigated
+                summary: Root cause is a stale KV read on the checkout flag.
+                findings: "The `checkout.cta` gate is rebuilt without a CDN purge, so…"
+                confidence: high
+                prNumber: 4821
+                prUrl: https://github.com/acme/web/pull/4821
+    responses:
+      "200":
+        description: The updated investigation record
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/OpsInvestigation
+      "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: update
+      positional:
+        - handle
+        - investigationId
 /api/admin/agent-profiles:
   get:
     operationId: listOpsAgents