@shipeasy/openapi 2.3.0 → 2.5.0

package/spec/components/schemas/projects.yaml

@@ -91,9 +91,9 @@ GetCurrentProjectResponse:
     defaultAllocationPct:
       type: integer
       description: Default traffic allocation (basis points) new experiments start with.
-    defaultHoldout:
+    defaultHoldoutBp:
       type: integer
-      description: Default holdout carve-out (basis points) that seeds each new universe's holdout.
+      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.
@@ -120,6 +120,110 @@ GetCurrentProjectResponse:
     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.
@@ -143,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:

package/spec/openapi.yaml

@@ -180,6 +180,25 @@ 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: |-
@@ -190,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.
@@ -252,6 +280,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}:
@@ -266,6 +296,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}:
@@ -278,6 +312,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}:
@@ -302,6 +338,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}:
@@ -314,6 +356,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/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:
     $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1comments
   /api/admin/notifications:
@@ -324,6 +374,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:
@@ -340,6 +394,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:

package/spec/paths/alerts.yaml

@@ -0,0 +1,184 @@
+/api/admin/alerts:
+  get:
+    operationId: listAlerts
+    summary: List fired alerts
+    description: |-
+      Returns the project's FIRED alerts as a **bare JSON array** (no pagination envelope), ordered by `createdAt desc`. Defaults to the currently-firing ones (`status=active`); pass a `status` to widen to resolved/dismissed history or `all`.
+
+      Fired alerts are raised only by the platform — the UI's killswitch handlers plus the worker's analysis consumer and alerts cron — never filed by hand, so this surface is list + triage (via PATCH), with no create. The rules that *define* metric-threshold alerts live at `/api/admin/alert-rules`.
+
+      **Use case:** Snapshot what is currently firing for an on-call view or the home Alerts block, or pull `status=all` to audit how a noisy rule has behaved over time.
+    tags:
+      - Fired Alerts
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: status
+        in: query
+        required: false
+        description: Filter by lifecycle state. Defaults to `active` (currently firing); `all` returns every status.
+        schema:
+          type: string
+          enum:
+            - active
+            - resolved
+            - dismissed
+            - all
+          default: active
+    responses:
+      "200":
+        description: List fired alerts
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/alerts.yaml#/ListAlertsResponse
+            example:
+              - id: al_01j7w9c4d5e6f7g8h9i0j1k2l3
+                source: metric_rule
+                ruleId: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
+                severity: danger
+                dedupeKey: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
+                title: Checkout error rate above threshold
+                detail: checkout_errors was 137 over the trailing 24h — above the rule's threshold of 50.
+                href: /dashboard/metrics/met_01j6abc2d3e4f5g6h7i8j9k0l1
+                observedValue: 137
+                status: active
+                createdAt: 2026-06-28T14:55:31.000Z
+                resolvedAt: null
+                dismissedAt: null
+                assigneeId: null
+                assigneeConnectorId: null
+                assigneeAgent: null
+              - id: al_01j7w9b2a1z0y9x8w7v6u5t4s3
+                source: killswitch_armed
+                ruleId: null
+                severity: warn
+                dedupeKey: ks_01j5checkout_kill
+                title: Kill switch "checkout_kill" is armed
+                detail: The kill switch has been armed for 3 days — confirm it is still intentional.
+                href: /dashboard/killswitches/ks_01j5checkout_kill
+                observedValue: null
+                status: active
+                createdAt: 2026-06-27T09:12:05.000Z
+                resolvedAt: null
+                dismissedAt: null
+                assigneeId: 6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c
+                assigneeConnectorId: null
+                assigneeAgent: null
+      "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
+    x-cli:
+      name: list
+/api/admin/alerts/{id}:
+  patch:
+    operationId: updateAlert
+    summary: Update a fired alert
+    description: |-
+      Triage writes on one fired alert — the only mutations this surface allows. All body fields are optional (at least one required); only the fields present are changed.
+
+      - **`status`** — flip between `active` / `resolved` / `dismissed`. `resolved` and `dismissed` stamp `resolvedAt` / `dismissedAt`; `active` re-opens and clears both. A resolved alert re-fires (as the same row, re-activated) if its condition is raised again.
+      - **`assigneeId`** — the PERSON owner (a `users.id`), or `null` to unassign.
+      - **`agent`** — the AGENT owner: a connected trigger connector's id, or the built-in `"jarvis"` (**Enterprise plan only** — `403` otherwise), or `null` to clear. Person and agent halves are independent.
+
+      Returns the updated row; `404` if the alert does not exist in the project.
+
+      **Use cases**
+
+      - **Wave off a known condition** — `{ "status": "dismissed" }` on an alert that needs no action.
+      - **Hand it to someone** — `{ "assigneeId": "…" }` from the ops cockpit's Owner column.
+    tags:
+      - Fired Alerts
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque alert id (`al_…`).
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/alerts.yaml#/UpdateAlertRequest
+          examples:
+            resolve:
+              summary: Mark resolved
+              description: Close out a fired alert once the underlying condition is handled.
+              value:
+                status: resolved
+            dismiss:
+              summary: Dismiss a benign alert
+              description: Wave off an alert that needs no action.
+              value:
+                status: dismissed
+            assignPerson:
+              summary: Assign a person owner
+              description: Hand the alert to a teammate from the ops cockpit's Owner column.
+              value:
+                assigneeId: 6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c
+            assignAgent:
+              summary: Assign an agent owner
+              description: Hand the alert to a connected coding agent (a connector id, or `"jarvis"` on Enterprise).
+              value:
+                agent: con_01j7wagentclaude0001
+    responses:
+      "200":
+        description: Update a fired alert
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/alerts.yaml#/UpdateAlertResponse
+            example:
+              id: al_01j7w9c4d5e6f7g8h9i0j1k2l3
+              source: metric_rule
+              ruleId: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
+              severity: danger
+              dedupeKey: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
+              title: Checkout error rate above threshold
+              detail: checkout_errors was 137 over the trailing 24h — above the rule's threshold of 50.
+              href: /dashboard/metrics/met_01j6abc2d3e4f5g6h7i8j9k0l1
+              observedValue: 137
+              status: resolved
+              createdAt: 2026-06-28T14:55:31.000Z
+              resolvedAt: 2026-06-28T16:40:12.000Z
+              dismissedAt: null
+              assigneeId: null
+              assigneeConnectorId: null
+              assigneeAgent: null
+      "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: update
+      positional:
+        - id

package/spec/paths/attributes.yaml

@@ -19,12 +19,30 @@
             schema:
               $ref: ../components/schemas/attributes.yaml#/ListAttributesResponse
             example:
-              - name: plan
+              - id: attr_01j7w8a1b2c3
+                name: plan
+                type: enum
+                enumValues:
+                  - free
+                  - paid
+                required: 1
+                description: Billing plan of the calling user.
+                sdkPath: user.plan
+                createdAt: 2026-06-20T09:14:08.000Z
+                source: manual
+                lastSeenAt: 2026-07-16T22:04:11.000Z
+                deprecated: 0
+              - id: attr_01j7w8a1b2c4
+                name: country
                 type: string
-              - name: country
-                type: string
-              - name: seats
-                type: number
+                enumValues: null
+                required: 0
+                description: null
+                sdkPath: null
+                createdAt: 2026-06-20T09:14:08.000Z
+                source: auto
+                lastSeenAt: 2026-07-16T22:04:11.000Z
+                deprecated: 0
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":