@shipeasy/openapi 2.2.0 → 2.3.0

package/spec/components/schemas/ops.yaml

@@ -245,6 +245,11 @@ OpsErrorContext:
       items:
         type: string
       description: "Distinct, id-normalized routes this error has surfaced on (UUIDs/ids collapsed to `#`)."
+    stackTail:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "The last 3 non-empty lines of the latest occurrence's stack — the innermost frames closest to where the throw bubbled out, baked in as an at-a-glance locator. `null` when the source supplied no stack. Fetch the full stack via `related.error`."
     sdkVersion:
       anyOf:
         - type: string
@@ -380,6 +385,11 @@ OpsAlertMetricSummary:
 OpsMeasurePlanContext:
   type: object
   properties:
+    goal:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "The customer's underlying intent in their own words — WHAT they want to learn or achieve and WHY, independent of the specific steps. The plan below is a best-effort proposal made without repo access; when the code reveals a better path, this goal is the target you optimize for, not literal step-adherence."
     created:
       type: array
       items:
@@ -927,6 +937,97 @@ LinkPrToOpsItemResponse:
     - id
   additionalProperties: false
   description: Response for the update / link-pr endpoints.
+OpsCommentAuthorType:
+  type: string
+  enum:
+    - user
+    - system
+  description: >-
+    Who wrote a comment. `user` is a teammate (their email is in `authorEmail`);
+    `system` is Jarvis — the AI agent — which authors comments when an ops-notify
+    escalation lands on the item and when it is `@shipeasy`-mentioned in a thread.
+OpsComment:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Comment id.
+    feedbackId:
+      type: string
+      description: The queue item this comment hangs off.
+    parentId:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: The top-level comment this is a reply to, or `null` for a top-level comment.
+    authorType:
+      $ref: "#/OpsCommentAuthorType"
+    authorEmail:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: The teammate who wrote it, or `null` for a `system` (Jarvis) comment.
+    body:
+      type: string
+      description: Comment body as markdown (may contain sanitised inline image/video embeds).
+    createdAt:
+      type: string
+      description: ISO-8601 creation timestamp.
+    updatedAt:
+      type: string
+      description: ISO-8601 last-edit timestamp.
+  required:
+    - id
+    - feedbackId
+    - parentId
+    - authorType
+    - authorEmail
+    - body
+    - createdAt
+    - updatedAt
+  additionalProperties: false
+  description: A single comment on a queue item.
+ListOpsCommentsResponse:
+  type: object
+  properties:
+    comments:
+      type: array
+      items:
+        $ref: "#/OpsComment"
+  required:
+    - comments
+  additionalProperties: false
+  description: Response for `GET /api/admin/ops/{handle}/comments` — the thread, oldest first.
+CreateOpsCommentRequest:
+  type: object
+  properties:
+    body:
+      type: string
+      minLength: 1
+      maxLength: 10000
+      description: The comment body as markdown. Mentions (`@teammate`, `@shipeasy`) are parsed from it.
+    parentId:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: >-
+        Reply under this top-level comment. Omit / `null` for a top-level
+        comment. Replying to a reply attaches to the same top-level parent
+        (threading is one level deep).
+  required:
+    - body
+  additionalProperties: false
+  description: Body for `POST /api/admin/ops/{handle}/comments`.
+CreateOpsCommentResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Newly created comment id.
+  required:
+    - id
+  additionalProperties: false
+  description: Response for `POST /api/admin/ops/{handle}/comments`.
 NotifyOpsRequest:
   type: object
   properties:

package/spec/components/schemas/projects.yaml

@@ -19,7 +19,9 @@ GetCurrentProjectResponse:
       type: string
       enum:
         - free
-        - paid
+        - pro
+        - business
+        - enterprise
       description: Billing plan tier.
     status:
       type: string
@@ -74,6 +76,50 @@ GetCurrentProjectResponse:
         - type: boolean
         - type: number
       description: Whether the feedback/ops module is enabled.
+    minSampleSize:
+      type: integer
+      description: Verdict power guard — minimum users per arm before a ship/hold verdict.
+    minRuntimeDays:
+      type: integer
+      description: Minimum days an experiment must run before a verdict (peeking guard).
+    defaultPower:
+      type: number
+      description: Target statistical power (1−β) feeding the realized-MDE calculation.
+    ciConfidence:
+      type: number
+      description: Confidence level for the interval surfaced on results.
+    defaultAllocationPct:
+      type: integer
+      description: Default traffic allocation (basis points) new experiments start with.
+    defaultHoldout:
+      type: integer
+      description: Default holdout carve-out (basis points) that seeds each new universe's holdout.
+    defaultWinsorizePct:
+      type: integer
+      description: Default winsorization percentile new metrics start with.
+    defaultMei:
+      anyOf:
+        - type: number
+        - type: "null"
+      description: Default minimum effect of interest (relative, 0–1) new metrics start with, or null.
+    cupedBaselineDays:
+      type: integer
+      description: CUPED baseline window — days of pre-experiment history, frozen at start.
+    cupedMinOverlap:
+      type: number
+      description: CUPED selection-bias guard — min share of users with a baseline, else skip.
+    cupedMinBaselineUsers:
+      type: integer
+      description: CUPED — minimum users with a baseline before it runs at all.
+    msprtTauMeiFactor:
+      type: number
+      description: mSPRT prior width — τ = minimum effect of interest × this factor.
+    msprtTauSdFactor:
+      type: number
+      description: mSPRT fallback prior width — τ = this × control SD when no MEI is set.
+    srmThreshold:
+      type: number
+      description: SRM chi-square p-value below which the run is called invalid.
     createdAt:
       type: string
       description: ISO-8601 timestamp of project creation.
@@ -218,5 +264,77 @@ UpdateProjectRequest:
     moduleEvents:
       type: boolean
       description: Enable/disable the events module.
+    minSampleSize:
+      type: integer
+      minimum: 2
+      maximum: 1000000
+      description: Verdict power guard — minimum users per arm before a ship/hold verdict.
+    minRuntimeDays:
+      type: integer
+      minimum: 0
+      maximum: 365
+      description: Minimum days an experiment must run before a verdict (peeking guard).
+    defaultPower:
+      type: number
+      minimum: 0.5
+      maximum: 0.99
+      description: Target statistical power (1−β) feeding the realized-MDE calculation.
+    ciConfidence:
+      type: number
+      minimum: 0.5
+      maximum: 0.999
+      description: Confidence level for the interval surfaced on results (any value in [0.5, 0.999], e.g. 0.90, 0.95, 0.975, 0.99).
+    defaultAllocationPct:
+      type: integer
+      minimum: 1
+      maximum: 10000
+      description: Default traffic allocation (basis points, 1000 = 10%) new experiments start with; overridable per experiment.
+    defaultHoldout:
+      type: integer
+      minimum: 0
+      maximum: 10000
+      description: Default holdout carve-out (basis points) that seeds each new universe's holdout (0 = none).
+    defaultWinsorizePct:
+      type: integer
+      minimum: 1
+      maximum: 99
+      description: Default winsorization percentile new metrics start with; overridable per metric.
+    defaultMei:
+      anyOf:
+        - type: number
+          minimum: 0
+          maximum: 1
+        - type: "null"
+      description: Default minimum effect of interest (relative, 0–1) new metrics start with; overridable per metric and per experiment. Null clears it.
+    cupedBaselineDays:
+      type: integer
+      minimum: 1
+      maximum: 365
+      description: CUPED baseline window — days of pre-experiment history, frozen at start.
+    cupedMinOverlap:
+      type: number
+      minimum: 0.01
+      maximum: 0.99
+      description: CUPED selection-bias guard — min share of users with a baseline, else skip.
+    cupedMinBaselineUsers:
+      type: integer
+      minimum: 10
+      maximum: 100000
+      description: CUPED — minimum users with a baseline before it runs at all.
+    msprtTauMeiFactor:
+      type: number
+      minimum: 0.1
+      maximum: 2
+      description: mSPRT prior width — τ = minimum effect of interest × this factor.
+    msprtTauSdFactor:
+      type: number
+      minimum: 0.05
+      maximum: 1
+      description: mSPRT fallback prior width — τ = this × control SD when no MEI is set.
+    srmThreshold:
+      type: number
+      minimum: 0.0001
+      maximum: 0.05
+      description: SRM chi-square p-value below which the run is called invalid.
   additionalProperties: false
   description: "Body for `PATCH /api/admin/projects/{id}`. Partial — every field is optional; only supplied fields change. The project id in the path must match the caller's own project."

package/spec/components/schemas/universes.yaml

@@ -1,3 +1,35 @@
+# The universe owns the config schema for every experiment/variant in it — an
+# ordered list of `{ name, type, default }`. Experiments may only override the
+# per-variant value of a declared param, never add fields (universe rework).
+UniverseParam:
+  type: object
+  properties:
+    name:
+      type: string
+      minLength: 1
+      maxLength: 128
+      pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
+      description: Param key, referenced by `groups[].params` on every experiment in the universe.
+    type:
+      type: string
+      enum:
+        - bool
+        - string
+        - int
+        - number
+      description: Scalar type of the param's value.
+    default:
+      description: "Universe-wide default. Returned when the assigned variant doesn't override this param (resolution: variant override → universe default)."
+  required:
+    - name
+    - type
+    - default
+  additionalProperties: false
+UniverseParamSchema:
+  type: array
+  items:
+    $ref: "#/UniverseParam"
+  description: The universe's ordered config schema — the single source of truth for its params.
 ListUniversesResponse:
   type: object
   properties:
@@ -14,6 +46,11 @@ ListUniversesResponse:
             maxLength: 128
             pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
             description: Stable universe key. Single segment or `folder.name`. Lowercase letters, digits, `_` or `-`; max 128 chars. Immutable after create.
+          description:
+            anyOf:
+              - type: string
+              - type: "null"
+            description: Human-readable blurb shown in the universe picker/hovercard.
           unitType:
             type: string
             description: Unit of randomisation. Snake-case in request (`unit_type`), camelCase in response.
@@ -26,6 +63,16 @@ ListUniversesResponse:
                 maxItems: 2
               - type: "null"
             description: Reserved holdout bucket range, or `null` if none.
+          recommendedHeadroom:
+            type: integer
+            minimum: 0
+            maximum: 10000
+            description: Basis points of headroom seeded into each new experiment's reserved tail (0 = none).
+          paramSchema:
+            anyOf:
+              - $ref: "#/UniverseParamSchema"
+              - type: "null"
+            description: The universe-owned config schema, or `null` on pre-rework universes not yet seeded.
           createdAt:
             type: string
             description: ISO-8601 timestamp of creation.
@@ -54,6 +101,13 @@ CreateUniverseRequest:
       description: Stable universe key. Single segment or `folder.name`. Lowercase letters, digits, `_` or `-`; max 128 chars. Immutable after create.
     folder:
       $ref: ./common.yaml#/Folder
+    description:
+      default: null
+      anyOf:
+        - type: string
+          maxLength: 2000
+        - type: "null"
+      description: Human-readable blurb shown in the universe picker/hovercard.
     unit_type:
       default: user_id
       description: Unit of randomisation. Typically `user_id`. Use `account_id` to keep whole accounts in the same group across an experiment.
@@ -70,6 +124,18 @@ CreateUniverseRequest:
           maxItems: 2
         - type: "null"
       description: Inclusive `[lo, hi]` bucket range (0–9999) reserved as the **holdout** — callers hashed into this slice are excluded from every experiment in the universe. `null` disables the holdout. Pro plan or higher required.
+    recommended_headroom:
+      default: 0
+      type: integer
+      minimum: 0
+      maximum: 10000
+      description: Basis points of reserved headroom seeded into each new experiment created in this universe (0 = none). Lets variants be appended into a running experiment without reshuffling.
+    param_schema:
+      default: null
+      anyOf:
+        - $ref: "#/UniverseParamSchema"
+        - type: "null"
+      description: The universe-owned config schema — an ordered `{ name, type, default }[]`. Experiments may only override values per variant, never add fields. `null` starts an empty schema.
   required:
     - name
   additionalProperties: false
@@ -94,6 +160,12 @@ UpdateUniverseRequest:
   properties:
     folder:
       $ref: ./common.yaml#/Folder
+    description:
+      anyOf:
+        - type: string
+          maxLength: 2000
+        - type: "null"
+      description: Human-readable blurb shown in the universe picker/hovercard.
     holdout_range:
       anyOf:
         - type: array
@@ -105,8 +177,18 @@ UpdateUniverseRequest:
           maxItems: 2
         - type: "null"
       description: Inclusive `[lo, hi]` bucket range (0–9999) reserved as the **holdout** — callers hashed into this slice are excluded from every experiment in the universe. `null` disables the holdout. Pro plan or higher required.
+    recommended_headroom:
+      type: integer
+      minimum: 0
+      maximum: 10000
+      description: Basis points of reserved headroom seeded into new experiments in this universe.
+    param_schema:
+      anyOf:
+        - $ref: "#/UniverseParamSchema"
+        - type: "null"
+      description: Replace the universe config schema. Additive changes + default edits are always allowed; removing a param a running experiment overrides is rejected (deprecate-only).
   additionalProperties: false
-  description: Body for `PATCH /api/admin/universes/{id}`. Only `holdout_range` is mutable — name and unit_type are immutable after create.
+  description: Body for `PATCH /api/admin/universes/{id}`. `name` and `unit_type` are immutable after create; `holdout_range`, `description`, `recommended_headroom` and `param_schema` are mutable.
 UpdateUniverseResponse:
   type: object
   properties:

package/spec/openapi.yaml

@@ -180,6 +180,16 @@ tags:
       **Immutable metric.** The bound metric (and its aggregation) is fixed at create time — there is no update path for `metricId`. Tune `threshold`/`comparator`/`windowHours`/`severity`/`name`/`enabled` instead, or delete + recreate to repoint the rule at a different metric.
 
       **Delivery.** `notify` optionally targets a Slack channel and/or email for this rule; `null` falls back to the project's default notification settings. Slack targets require a connected Slack connector.
+  - name: Comments
+    parent: Ops
+    description: |-
+      Comments on a queue item — the discussion thread that hangs off any bug,
+      feature request, or auto-filed error/alert ticket. Append a comment or read
+      the thread; one level of threaded replies via `parentId`.
+
+      **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: Projects
     description: |-
       Projects: the account-level container every other resource is scoped to.
@@ -304,6 +314,8 @@ paths:
     $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}
   /api/admin/ops/{handle}/link-pr:
     $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1link-pr
+  /api/admin/ops/{handle}/comments:
+    $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1comments
   /api/admin/notifications:
     $ref: ./paths/ops.yaml#/~1api~1admin~1notifications
   /api/admin/slack/channels:
@@ -338,6 +350,8 @@ paths:
     $ref: ./paths/errors.yaml#/~1api~1admin~1errors~1{id}
   /api/admin/errors/{id}/file:
     $ref: ./paths/errors.yaml#/~1api~1admin~1errors~1{id}~1file
+  /api/admin/errors/{id}/resolve:
+    $ref: ./paths/errors.yaml#/~1api~1admin~1errors~1{id}~1resolve
   /api/admin/errors/{id}/series:
     $ref: ./paths/errors.yaml#/~1api~1admin~1errors~1{id}~1series
   /api/admin/connectors:

package/spec/paths/alert-rules.yaml

@@ -128,6 +128,7 @@
       - UNAUTHORIZED
       - FORBIDDEN
       - ALREADY_EXISTS
+      - METRIC_NOT_FOUND
       - REFERENCED_NOT_FOUND
       - VALIDATION
     x-cli:

package/spec/paths/configs.yaml

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

package/spec/paths/errors.yaml

@@ -96,9 +96,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 +142,31 @@
               lastSeenAt: 2026-06-28T14:55:31.000Z
               createdAt: 2026-06-20T08:11:02.000Z
               updatedAt: 2026-06-28T14:55:31.000Z
+              occurrences:
+                - id: occ_01j7w7qq0v3k9d2m5rc8t1xh4n
+                  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
+                  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":
@@ -303,6 +328,75 @@
       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
+      "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:

package/spec/paths/experiments.yaml

@@ -372,6 +372,7 @@
       - GROUPS_WEIGHT_SUM
       - REFERENCED_NOT_FOUND
       - VALIDATION
+      - EXPERIMENT_IMMUTABLE_FIELD
     x-cli:
       name: update
       positional:
@@ -510,6 +511,12 @@
       - NOT_FOUND
       - INVALID_TRANSITION
       - VALIDATION
+      - PLAN_LIMIT
+      - EXPERIMENT_NO_GOAL_METRIC
+      - EXPERIMENT_ARCHIVED_RESTART
+      - EXPERIMENT_NOT_RUNNING
+      - EXPERIMENT_RUNNING_ARCHIVE
+      - EXPERIMENT_RESTORE_INVALID
     x-cli:
       positional:
         - id
@@ -604,6 +611,7 @@
       - EVENT_PENDING
       - REFERENCED_NOT_FOUND
       - VALIDATION
+      - METRIC_UNKNOWN_ID
     x-cli:
       name: set-metrics
       positional:

package/spec/paths/gates.yaml

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

package/spec/paths/keys.yaml

@@ -128,6 +128,7 @@
       - UNAUTHORIZED
       - FORBIDDEN
       - VALIDATION
+      - PLAN_LIMIT
     x-cli:
       name: create
 /api/admin/keys/{id}/revoke:

package/spec/paths/killswitches.yaml

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

package/spec/paths/metrics.yaml

@@ -141,6 +141,7 @@
       - EVENT_PENDING
       - REFERENCED_NOT_FOUND
       - VALIDATION
+      - PLAN_LIMIT
     x-cli:
       name: create
       positional: