@shipeasy/openapi 2.3.0 → 2.5.0

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:
@@ -84,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:
@@ -126,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:
@@ -137,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
@@ -226,6 +224,7 @@
               id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
               name: pricing.tiers
               description: Pricing tier definitions consumed by the checkout flow.
+              folder: pricing
               schema:
                 type: object
                 properties:
@@ -298,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:
@@ -332,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.
@@ -492,6 +498,7 @@
       - VALIDATION
     x-cli:
       name: draft
+      hidden: true
       positional:
         - id
   delete:
@@ -551,6 +558,7 @@
       - NOT_FOUND
     x-cli:
       name: discard-draft
+      hidden: true
       positional:
         - id
 /api/admin/configs/{id}/publish:
@@ -622,6 +630,7 @@
       - VALIDATION
     x-cli:
       name: publish
+      hidden: true
       positional:
         - id
 /api/admin/configs/{id}/activity:
@@ -686,6 +695,74 @@
       - NOT_FOUND
     x-cli:
       name: activity
+      hidden: true
+      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
+      hidden: true
       positional:
         - id
 /api/admin/configs/{id}/schema:

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":
@@ -142,8 +145,13 @@
               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')
@@ -156,6 +164,8 @@
                   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')
@@ -257,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":
@@ -377,6 +390,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":

package/spec/paths/experiments.yaml

@@ -648,21 +648,51 @@
                 status: running
               results:
                 - metric: checkout_completed
-                  group_name: control
+                  groupName: control
                   ds: 2026-05-09
                   n: 12421
                   mean: 0.1834
-                  delta_pct: null
-                  p_value: null
-                  srm_detected: 0
+                  variance: 0.1498
+                  delta: null
+                  deltaPct: null
+                  ci95Low: null
+                  ci95High: null
+                  ci99Low: null
+                  ci99High: null
+                  ciLow: null
+                  ciHigh: null
+                  pValue: null
+                  expectedN: 15000
+                  realizedMde: null
+                  srmPValue: 0.82
+                  srmDetected: 0
+                  msprtSignificant: null
+                  msprtLambda: null
+                  isFinal: 0
+                  peekWarning: 0
                 - metric: checkout_completed
-                  group_name: treatment
+                  groupName: treatment
                   ds: 2026-05-09
                   n: 12519
                   mean: 0.1922
-                  delta_pct: 4.8
-                  p_value: 0.018
-                  srm_detected: 0
+                  variance: 0.1553
+                  delta: 0.0088
+                  deltaPct: 4.8
+                  ci95Low: 0.0015
+                  ci95High: 0.0161
+                  ci99Low: -0.0008
+                  ci99High: 0.0184
+                  ciLow: 0.0015
+                  ciHigh: 0.0161
+                  pValue: 0.018
+                  expectedN: 15000
+                  realizedMde: 0.0079
+                  srmPValue: 0.82
+                  srmDetected: 0
+                  msprtSignificant: null
+                  msprtLambda: null
+                  isFinal: 0
+                  peekWarning: 0
               verdict: ship
       "400":
         $ref: ../components/responses.yaml#/BadRequest
@@ -723,21 +753,51 @@
                 status: running
               series:
                 - metric: checkout_completed
-                  group_name: treatment
+                  groupName: treatment
                   ds: 2026-05-08
                   n: 11200
                   mean: 0.1903
-                  delta_pct: 3.9
-                  p_value: 0.034
-                  srm_detected: 0
+                  variance: 0.1541
+                  delta: 0.0071
+                  deltaPct: 3.9
+                  ci95Low: -0.0004
+                  ci95High: 0.0146
+                  ci99Low: -0.0028
+                  ci99High: 0.017
+                  ciLow: -0.0004
+                  ciHigh: 0.0146
+                  pValue: 0.034
+                  expectedN: 15000
+                  realizedMde: 0.0083
+                  srmPValue: 0.79
+                  srmDetected: 0
+                  msprtSignificant: null
+                  msprtLambda: null
+                  isFinal: 0
+                  peekWarning: 0
                 - metric: checkout_completed
-                  group_name: treatment
+                  groupName: treatment
                   ds: 2026-05-09
                   n: 12519
                   mean: 0.1922
-                  delta_pct: 4.8
-                  p_value: 0.018
-                  srm_detected: 0
+                  variance: 0.1553
+                  delta: 0.0088
+                  deltaPct: 4.8
+                  ci95Low: 0.0015
+                  ci95High: 0.0161
+                  ci99Low: -0.0008
+                  ci99High: 0.0184
+                  ciLow: 0.0015
+                  ciHigh: 0.0161
+                  pValue: 0.018
+                  expectedN: 15000
+                  realizedMde: 0.0079
+                  srmPValue: 0.82
+                  srmDetected: 0
+                  msprtSignificant: null
+                  msprtLambda: null
+                  isFinal: 0
+                  peekWarning: 0
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -759,6 +819,166 @@
       name: timeseries
       positional:
         - id
+/api/admin/experiments/{id}/readouts:
+  post:
+    operationId: createExperimentReadout
+    summary: Mint a readout snapshot
+    description: |-
+      Freezes the current results view into an immutable, dated readout snapshot — verdict, headline, per-metric numbers, the caveat list with its acknowledgment state, enrollment, and a hash of the assignment-relevant config. Ship/stop flows mint one automatically; "Share readout" mints one on demand. Snapshots are never updated after insert.
+
+      Pass `requireAllAcknowledged: true` to enforce ship gating server-side — returns `422` while any open caveat is not listed in `acknowledgedCaveatIds`.
+
+      **Use case:** Capture "what the data said when we decided" before shipping or stopping, so the decision stays auditable even after results move.
+    tags:
+      - Experiments
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/experiments.yaml#/CreateExperimentReadoutRequest
+          examples:
+            manual:
+              summary: Manual — "Share readout"
+              description: Snapshot the current results view on demand.
+              value:
+                kind: manual
+            shipGated:
+              summary: Ship — with caveat gating
+              description: Mint a ship readout, acknowledging the open caveats; fails with `422` if any open caveat is missing from the list.
+              value:
+                kind: ship
+                acknowledgedCaveatIds:
+                  - srm
+                  - min_runtime
+                requireAllAcknowledged: true
+    responses:
+      "200":
+        description: Mint a readout snapshot
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/experiments.yaml#/CreateExperimentReadoutResponse
+            example:
+              id: 5f0c1f2d-8e90-4c6e-9b1a-3a7c1f2d8e90
+        links:
+          GetExperimentReadout:
+            operationId: getExperimentReadout
+            parameters: { readoutId: $response.body#/id }
+      "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: readout-create
+      positional:
+        - id
+/api/admin/experiments/{id}/readouts/{readoutId}:
+  get:
+    operationId: getExperimentReadout
+    summary: Get a readout snapshot
+    description: |-
+      Returns one immutable readout snapshot — the frozen results view (verdict, headline, per-metric numbers, caveats, enrollment) captured when it was minted, plus the `configHash` that tells you whether it is still comparable to the live view.
+
+      **Use case:** Render a shared, dated readout exactly as it looked at decision time.
+    tags:
+      - Experiments
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+      - name: readoutId
+        in: path
+        required: true
+        description: Readout snapshot id, as returned by `createExperimentReadout`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Get a readout snapshot
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/experiments.yaml#/GetExperimentReadoutResponse
+            example:
+              id: 5f0c1f2d-8e90-4c6e-9b1a-3a7c1f2d8e90
+              experimentId: exp_01j7wb12c3d4e5f6g7h8j9k0l1
+              experimentName: checkout_button_color
+              kind: ship
+              createdBy: pm@example.com
+              createdAt: 2026-05-09T18:22:11.000Z
+              verdict: ship
+              title: Treatment wins on checkout conversion
+              why: Goal metric significant with guardrails flat after 8 days.
+              configHash: 9c1f4f1f2c0c4a5fa1c2b6d3e7c8e3a19c1f4f1f2c0c4a5fa1c2b6d3e7c8e3a1
+              metricsJson:
+                - name: checkout_completed
+                  role: goal
+                  delta: 0.0088
+                  deltaPct: 4.8
+                  ci: [0.0015, 0.0161]
+                  p: 0.018
+                  sig: true
+              caveatsJson:
+                - id: min_runtime
+                  severity: warn
+                  text: Below the 14-day minimum runtime.
+                  acknowledged: true
+              usersJson:
+                groups:
+                  - name: control
+                    n: 12421
+                  - name: treatment
+                    n: 12519
+                days: 8
+      "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: readout-get
+      positional:
+        - id
+        - readoutId
 /api/admin/experiments/{id}/reanalyze:
   post:
     operationId: reanalyzeExperiment

package/spec/paths/gates.yaml

@@ -43,6 +43,10 @@
                   groupName: growth
                   ownerEmail: ana@example.com
                   stack: null
+                  creatorEmail: ana@example.com
+                  updaterEmail: bo@example.com
+                  version: 4
+                  createdAt: 2026-05-01T10:12:00.000Z
                   updatedAt: 2026-05-09T16:01:22.000Z
               next_cursor: null
       "400":
@@ -201,6 +205,76 @@
       positional:
         - name
 /api/admin/gates/{id}:
+  get:
+    operationId: getGate
+    summary: Get one gate
+    description: |-
+      Returns the full gate row — including the gatekeeper `stack`, resolved creator/last-editor emails, and the edit `version` — for one gate, addressed by id or `name`.
+
+      **Use case:** Inspect a single gate's current rollout, rules, and stack before editing it, without paging through the whole list.
+    tags:
+      - Flags
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque gate id (`gat_…`) or the gate's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Get one gate
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/gates.yaml#/GetGateResponse
+            example:
+              id: gat_01j7w7m9q4hxbf6npe6s9zr3vc
+              name: checkout_v2
+              enabled: 1
+              type: targeting
+              rolloutPct: 5000
+              rules:
+                - attr: country
+                  op: in
+                  value:
+                    - US
+                    - CA
+                    - GB
+              salt: 9c1f4f1f2c0c4a5fa1c2b6d3e7c8e3a1
+              title: Checkout v2
+              description: New checkout flow. Pro users in US/CA/GB only.
+              folder: checkout
+              groupName: growth
+              ownerEmail: ana@example.com
+              stack: null
+              creatorEmail: ana@example.com
+              updaterEmail: bo@example.com
+              version: 4
+              createdAt: 2026-05-01T10:12:00.000Z
+              updatedAt: 2026-05-09T16:01:22.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:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: get
+      positional:
+        - id
   patch:
     operationId: updateGate
     summary: Update a feature gate
@@ -464,3 +538,66 @@
       name: disable
       positional:
         - id
+/api/admin/gates/{id}/activity:
+  get:
+    operationId: listGateActivity
+    summary: List gate activity
+    description: |-
+      Returns recent audit rows for one gate (create, update, enable, disable, delete) ordered newest first. Use the `limit` query parameter to cap the result (1–100, default 20).
+
+      **Use case:** Render the activity feed in the gate detail panel or answer "who ramped this gate, and when?" during an incident review.
+    tags:
+      - Flags
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque gate id (`gat_…`) or the gate's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+      - name: limit
+        in: query
+        required: false
+        description: Max rows to return (1–100). Defaults to 20.
+        schema:
+          default: 20
+          type: integer
+          minimum: 1
+          maximum: 100
+    responses:
+      "200":
+        description: List gate activity
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/gates.yaml#/ListGateActivityResponse
+            example:
+              - id: act_01j7waf01a2b3c4d5e6f7g8h9i
+                action: gate.update
+                actorEmail: ana@example.com
+                actorType: user
+                payload:
+                  rollout_pct: 5000
+                createdAt: 2026-05-09T16:01:22.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:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: activity
+      positional:
+        - id