@shipeasy/openapi 2.2.0 → 2.4.0

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,154 @@ 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.
+    defaultHoldoutBp:
+      type: integer
+      description: Default holdout carve-out (basis points) that seeds each new universe's holdout (0 = none).
+    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.
+    slug:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: URL-safe project identifier used in app URLs and SDK config, or `null` if unset.
+    logo:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Cache-busted URL of the project logo (served from the admin logo route), or `null` when no logo is set.
+    defaultEnv:
+      type: string
+      enum:
+        - dev
+        - staging
+        - prod
+      description: Default environment new resources are scoped to.
+    timezone:
+      type: string
+      description: IANA timezone the project's daily analysis runs in.
+    statMethod:
+      type: string
+      enum:
+        - sequential
+        - fixed
+        - bayesian
+      description: Statistical method the experiment analyzer uses.
+    sigThreshold:
+      type: string
+      description: Significance threshold (alpha) for experiment analysis, as a decimal string (e.g. `"0.05"`).
+    autoRollback:
+      type: boolean
+      description: Whether a failing guardrail auto-rolls back the experiment.
+    minSampleDays:
+      type: integer
+      description: Minimum number of days an experiment must run before it can be called.
+    moduleUser:
+      anyOf:
+        - type: boolean
+        - type: number
+      description: Whether the user-management module is enabled.
+    moduleEvents:
+      anyOf:
+        - type: boolean
+        - type: number
+      description: Whether the events module is enabled.
+    allowPublicTickets:
+      anyOf:
+        - type: boolean
+        - type: number
+      description: Whether key-authenticated public ticket creation (`POST /cli/report`) is allowed into this project. Off by default.
+    stripeSubscriptionId:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Stripe subscription id backing the project's billing, or `null` when unsubscribed.
+    scheduledInterval:
+      anyOf:
+        - type: string
+          enum:
+            - monthly
+            - annual
+        - type: "null"
+      description: Pending billing-interval change deferred to period end (only the annual→monthly downgrade), or `null` when no switch is pending.
+    spendLimitEnabled:
+      anyOf:
+        - type: boolean
+        - type: number
+      description: Whether the advisory monthly spend limit is enabled.
+    spendLimitUsd:
+      anyOf:
+        - type: integer
+        - type: "null"
+      description: Advisory monthly spend limit in whole USD, or `null` if unset.
+    spendAlertEmail:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Email address the spend alert is sent to, or `null` if unset.
+    defaultAssigneePendingApproval:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Default person owner (user id) auto-assigned to new `pending_approval` feedback items, or `null` when unset.
+    defaultAssigneeConnectorPendingApproval:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Default agent owner (connector id) auto-assigned to new `pending_approval` feedback items, or `null` when unset.
+    defaultAssigneeOpen:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Default person owner (user id) auto-assigned to new `open` feedback items, or `null` when unset.
+    defaultAssigneeConnectorOpen:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Default agent owner (connector id) auto-assigned to new `open` feedback items, or `null` when unset.
+    deletedAt:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: ISO-8601 timestamp the project was soft-deleted (purged after a 14-day grace period), or `null` when live.
     createdAt:
       type: string
       description: ISO-8601 timestamp of project creation.
@@ -97,10 +247,32 @@ GetCurrentProjectResponse:
     - moduleGates
     - moduleExperiments
     - moduleFeedback
+    - moduleUser
+    - moduleEvents
+    - allowPublicTickets
+    - slug
+    - logo
+    - defaultEnv
+    - timezone
+    - statMethod
+    - sigThreshold
+    - autoRollback
+    - minSampleDays
+    - defaultHoldoutBp
+    - stripeSubscriptionId
+    - scheduledInterval
+    - spendLimitEnabled
+    - spendLimitUsd
+    - spendAlertEmail
+    - defaultAssigneePendingApproval
+    - defaultAssigneeConnectorPendingApproval
+    - defaultAssigneeOpen
+    - defaultAssigneeConnectorOpen
+    - deletedAt
     - createdAt
     - updatedAt
   additionalProperties: {}
-  description: The project the caller's auth header resolves to. The shape is open — additional project fields may be present.
+  description: The project the caller's auth header resolves to. The shape is open — additional project fields may be present. Stripe billing internals (`stripeCustomerId`, the `stripeItemId*` family) are intentionally undocumented.
 UpsertProjectRequest:
   type: object
   properties:
@@ -218,5 +390,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,35 @@ 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: Fired Alerts
+    parent: Ops
+    description: |-
+      Fired alerts: the conditions the platform has actually raised — metric-rule
+      crossings, armed kill switches, experiment SRM/peek guards, and guardrail
+      breaches. Raised only by the platform (UI killswitch handlers plus the
+      worker analysis consumer and alerts cron), never filed by hand; deduped per
+      `(source, dedupeKey)` with auto-resolve when the condition clears. This
+      surface lists them and triages one (status flip + person/agent owner). The
+      *rules* that define metric-threshold alerts are the sibling alert-rules
+      resource.
+  - name: Agents
+    parent: Ops
+    description: |-
+      Connected AI agents — one per authenticated trigger connector (Claude /
+      Cursor / Copilot / Jules). The read-only roster behind agent assignment
+      and the `ops ack` agent types: an AI ack (`ops ack <handle> --agent
+      <type>`) requires the type to appear here, so this list is where an
+      `AGENT_NOT_CONNECTED` error sends you.
+  - 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.
@@ -242,6 +271,8 @@ paths:
     $ref: ./paths/gates.yaml#/~1api~1admin~1gates~1{id}~1enable
   /api/admin/gates/{id}/disable:
     $ref: ./paths/gates.yaml#/~1api~1admin~1gates~1{id}~1disable
+  /api/admin/gates/{id}/activity:
+    $ref: ./paths/gates.yaml#/~1api~1admin~1gates~1{id}~1activity
   /api/admin/experiments:
     $ref: ./paths/experiments.yaml#/~1api~1admin~1experiments
   /api/admin/experiments/{id}:
@@ -256,6 +287,10 @@ paths:
     $ref: ./paths/experiments.yaml#/~1api~1admin~1experiments~1{id}~1timeseries
   /api/admin/experiments/{id}/reanalyze:
     $ref: ./paths/experiments.yaml#/~1api~1admin~1experiments~1{id}~1reanalyze
+  /api/admin/experiments/{id}/readouts:
+    $ref: ./paths/experiments.yaml#/~1api~1admin~1experiments~1{id}~1readouts
+  /api/admin/experiments/{id}/readouts/{readoutId}:
+    $ref: ./paths/experiments.yaml#/~1api~1admin~1experiments~1{id}~1readouts~1{readoutId}
   /api/admin/configs:
     $ref: ./paths/configs.yaml#/~1api~1admin~1configs
   /api/admin/configs/{id}:
@@ -268,6 +303,8 @@ paths:
     $ref: ./paths/configs.yaml#/~1api~1admin~1configs~1{id}~1activity
   /api/admin/configs/{id}/schema:
     $ref: ./paths/configs.yaml#/~1api~1admin~1configs~1{id}~1schema
+  /api/admin/configs/{id}/versions:
+    $ref: ./paths/configs.yaml#/~1api~1admin~1configs~1{id}~1versions
   /api/admin/killswitches:
     $ref: ./paths/killswitches.yaml#/~1api~1admin~1killswitches
   /api/admin/killswitches/{id}:
@@ -292,6 +329,12 @@ paths:
     $ref: ./paths/metrics.yaml#/~1api~1admin~1metrics
   /api/admin/metrics/{id}:
     $ref: ./paths/metrics.yaml#/~1api~1admin~1metrics~1{id}
+  /api/admin/metrics/{id}/experiments:
+    $ref: ./paths/metrics.yaml#/~1api~1admin~1metrics~1{id}~1experiments
+  /api/admin/metrics/{id}/unarchive:
+    $ref: ./paths/metrics.yaml#/~1api~1admin~1metrics~1{id}~1unarchive
+  /api/admin/metrics/{id}/series:
+    $ref: ./paths/metrics.yaml#/~1api~1admin~1metrics~1{id}~1series
   /api/admin/events:
     $ref: ./paths/events.yaml#/~1api~1admin~1events
   /api/admin/events/{id}:
@@ -304,6 +347,14 @@ 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}/ack:
+    $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/agent-profiles:
+    $ref: ./paths/ops.yaml#/~1api~1admin~1agent-profiles
+  /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:
@@ -312,6 +363,10 @@ paths:
     $ref: ./paths/alert-rules.yaml#/~1api~1admin~1alert-rules
   /api/admin/alert-rules/{id}:
     $ref: ./paths/alert-rules.yaml#/~1api~1admin~1alert-rules~1{id}
+  /api/admin/alerts:
+    $ref: ./paths/alerts.yaml#/~1api~1admin~1alerts
+  /api/admin/alerts/{id}:
+    $ref: ./paths/alerts.yaml#/~1api~1admin~1alerts~1{id}
   /api/admin/projects/current:
     $ref: ./paths/projects.yaml#/~1api~1admin~1projects~1current
   /api/admin/projects/upsert:
@@ -328,6 +383,10 @@ paths:
     $ref: ./paths/i18n.yaml#/~1api~1admin~1i18n~1drafts
   /api/admin/i18n/drafts/{draftId}:
     $ref: ./paths/i18n.yaml#/~1api~1admin~1i18n~1drafts~1{draftId}
+  /api/admin/i18n/profiles/{profileId}:
+    $ref: ./paths/i18n.yaml#/~1api~1admin~1i18n~1profiles~1{profileId}
+  /api/admin/i18n/drafts/{draftId}/keys:
+    $ref: ./paths/i18n.yaml#/~1api~1admin~1i18n~1drafts~1{draftId}~1keys
   /api/admin/i18n/profiles/{profileId}/publish:
     $ref: ./paths/i18n.yaml#/~1api~1admin~1i18n~1profiles~1{profileId}~1publish
   /api/admin/i18n/set:
@@ -338,6 +397,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: