@shipeasy/openapi 2.2.0 → 2.4.0

package/spec/components/schemas/i18n.yaml

@@ -23,8 +23,13 @@ ListI18nProfilesResponse:
     required:
       - id
       - name
+      - isDefault
+      - createdAt
+      - deletedAt
     additionalProperties: false
     description: One i18n locale profile.
+DeleteI18nProfileResponse:
+  $ref: "./common.yaml#/OkResponse"
 CreateI18nProfileRequest:
   type: object
   properties:
@@ -84,9 +89,19 @@ ListI18nKeysResponse:
           profileId:
             description: Owning profile id.
             type: string
+          profileName:
+            description: Name of the owning profile (e.g. `en:prod`), or `null` when it cannot be resolved.
+            anyOf:
+              - type: string
+              - type: "null"
           chunkId:
             description: Owning chunk (authoring grouping) id.
             type: string
+          chunkName:
+            description: Name of the owning chunk (authoring grouping), or `null` when it cannot be resolved.
+            anyOf:
+              - type: string
+              - type: "null"
           updatedAt:
             description: ISO-8601 timestamp of the last edit.
             type: string
@@ -97,7 +112,15 @@ ListI18nKeysResponse:
           - id
           - key
           - value
-        additionalProperties: {}
+          - description
+          - variables
+          - profileId
+          - profileName
+          - chunkId
+          - chunkName
+          - updatedAt
+          - updatedBy
+        additionalProperties: false
         description: One i18n key row.
       description: The page of matching keys.
     total:
@@ -217,47 +240,76 @@ UpdateI18nKeyResponse:
     - id
   additionalProperties: false
   description: Updated key id.
+DeleteI18nKeyResponse:
+  $ref: "./common.yaml#/OkResponse"
+UpsertI18nKeysRequest:
+  type: object
+  properties:
+    profile_id:
+      type: string
+      format: uuid
+      description: Target profile id to upsert keys into.
+    chunk:
+      description: Logical grouping the keys are filed under. Defaults to `default`.
+      type: string
+      minLength: 1
+      maxLength: 64
+      default: default
+    keys:
+      type: array
+      minItems: 1
+      maxItems: 5000
+      items:
+        type: object
+        properties:
+          key:
+            type: string
+            minLength: 1
+            maxLength: 256
+            description: Dotted key path, e.g. `home.cta`.
+          value:
+            type: string
+            description: Translated value for the key.
+          description:
+            type: string
+            description: Optional human note stored with the key.
+          variables:
+            type: array
+            maxItems: 32
+            items:
+              type: string
+              minLength: 1
+              maxLength: 64
+            description: Optional explicit list of `{{var}}` placeholder names in the value. Auto-derived from the value when omitted.
+        required:
+          - key
+          - value
+        additionalProperties: false
+      description: Keys to upsert. Existing keys ARE overwritten — this is the bulk overwrite path.
+  required:
+    - profile_id
+    - keys
+  additionalProperties: false
+  description: "Body for `PUT /api/admin/i18n/keys`. Bulk upsert (overwrite): existing keys are replaced, new ones inserted. Backs the devtools overlay's in-product label editing; deliberately not surfaced by the CLI or MCP."
+UpsertI18nKeysResponse:
+  type: object
+  properties:
+    upserted:
+      type: number
+      description: Number of keys written (inserted or overwritten).
+    chunk:
+      type: string
+      description: The chunk the keys were filed under.
+  required:
+    - upserted
+    - chunk
+  additionalProperties: false
+  description: Result of a bulk key upsert. The affected profile's KV snapshot is rebuilt (and the CDN purged) before this returns.
 ListI18nDraftsResponse:
   type: array
   items:
-    type: object
-    properties:
-      id:
-        type: string
-        description: Stable opaque draft id.
-      name:
-        description: Draft name, e.g. the target locale being staged.
-        type: string
-      profileId:
-        description: Profile the draft targets.
-        type: string
-      sourceProfileId:
-        description: Profile the draft was seeded from, or `null`.
-        anyOf:
-          - type: string
-          - type: "null"
-      status:
-        description: Lifecycle state of the draft.
-        type: string
-        enum:
-          - open
-          - merged
-          - abandoned
-      createdBy:
-        description: Actor email that created the draft.
-        type: string
-      createdAt:
-        description: ISO-8601 timestamp of creation.
-        type: string
-      publishedAt:
-        description: ISO-8601 merge/publish timestamp, or `null`.
-        anyOf:
-          - type: string
-          - type: "null"
-    required:
-      - id
-    additionalProperties: {}
-    description: One staged translation draft.
+    $ref: "#/I18nDraft"
+  description: Bare array of the project's staged translation drafts.
 I18nDraft:
   type: object
   properties:
@@ -295,8 +347,15 @@ I18nDraft:
       description: ISO-8601 merge/publish timestamp, or `null`.
   required:
     - id
+    - name
+    - profileId
+    - sourceProfileId
+    - status
+    - createdBy
+    - createdAt
+    - publishedAt
   additionalProperties: {}
-  description: One staged translation draft.
+  description: One staged translation draft. The shape is open — additional fields may be present.
 CreateI18nDraftRequest:
   type: object
   properties:
@@ -334,6 +393,76 @@ UpdateI18nDraftRequest:
   description: Body for `PATCH /api/admin/i18n/drafts/{draftId}`. Transitions the draft's lifecycle state.
 UpdateI18nDraftResponse:
   $ref: "#/I18nDraft"
+DeleteI18nDraftResponse:
+  $ref: "./common.yaml#/OkResponse"
+ListI18nDraftKeysResponse:
+  type: array
+  items:
+    type: object
+    properties:
+      id:
+        type: string
+        description: Stable opaque draft-key id.
+      draftId:
+        type: string
+        description: Id of the draft the key belongs to.
+      key:
+        type: string
+        description: Dotted key path, e.g. `home.cta`.
+      value:
+        type: string
+        description: Staged translated value for the key.
+      description:
+        description: Optional human note stored with the key, or `null`.
+        anyOf:
+          - type: string
+          - type: "null"
+      variables:
+        description: "`{{var}}` placeholder names in the value, or `null` when there are none."
+        anyOf:
+          - type: array
+            items:
+              type: string
+          - type: "null"
+      updatedBy:
+        type: string
+        description: Actor email that last edited the staged key.
+      updatedAt:
+        type: string
+        description: ISO-8601 timestamp of the last edit.
+    required:
+      - id
+      - draftId
+      - key
+      - value
+      - description
+      - variables
+      - updatedBy
+      - updatedAt
+    additionalProperties: false
+    description: One staged draft key.
+  description: Bare array of the draft's staged keys (no pagination envelope).
+UpsertI18nDraftKeyRequest:
+  type: object
+  properties:
+    key:
+      type: string
+      minLength: 1
+      maxLength: 256
+      description: Dotted key path to stage, e.g. `home.cta`.
+    value:
+      type: string
+      description: Staged translated value for the key.
+    description:
+      type: string
+      description: Optional human note stored with the staged key.
+  required:
+    - key
+    - value
+  additionalProperties: false
+  description: "Body for `POST /api/admin/i18n/drafts/{draftId}/keys`. Upserts one staged key into an open draft — inserted when new, overwritten when it already exists. `{{var}}` placeholder names are auto-derived from the value."
+UpsertI18nDraftKeyResponse:
+  $ref: "./common.yaml#/OkResponse"
 PublishI18nProfileRequest:
   type: object
   properties:

package/spec/components/schemas/keys.yaml

@@ -114,7 +114,8 @@ CreateKeyRequest:
           - events:write
           - configs:write
           - experiments:write
-      description: Optional permission strings recorded on the key for audit/display.
+          - tickets:public_create
+      description: "Optional permission strings recorded on the key. `tickets:public_create` is enforced: a client key needs it (plus the project's `allowPublicTickets` setting) to file a `pending_approval` bug via the public `POST /cli/report` endpoint. The rest are audit/display only."
     expiresInDays:
       anyOf:
         - type: integer

package/spec/components/schemas/killswitches.yaml

@@ -18,6 +18,21 @@ ListKillswitchesResponse:
               - type: string
               - type: "null"
             description: Free-form description or `null`.
+          folder:
+            description: Folder segment used for dashboard organisation, or `null` when the killswitch lives at the root.
+            anyOf:
+              - type: string
+              - type: "null"
+          creatorEmail:
+            description: Resolved email of the creator (`created_by` → `users.email`), or `null` when unknown.
+            anyOf:
+              - type: string
+              - type: "null"
+          createdAt:
+            description: ISO-8601 creation timestamp, or `null` on legacy rows created before the column existed.
+            anyOf:
+              - type: string
+              - type: "null"
           updatedAt:
             type: string
             description: ISO-8601 timestamp of last mutation.
@@ -56,6 +71,9 @@ ListKillswitchesResponse:
           - id
           - name
           - description
+          - folder
+          - creatorEmail
+          - createdAt
           - updatedAt
           - envs
         additionalProperties: false
@@ -82,6 +100,21 @@ GetKillswitchResponse:
         - type: string
         - type: "null"
       description: Free-form description or `null`.
+    folder:
+      description: Folder segment used for dashboard organisation, or `null` when the killswitch lives at the root.
+      anyOf:
+        - type: string
+        - type: "null"
+    creatorEmail:
+      description: Resolved email of the creator (`created_by` → `users.email`), or `null` when unknown.
+      anyOf:
+        - type: string
+        - type: "null"
+    createdAt:
+      description: ISO-8601 creation timestamp, or `null` on legacy rows created before the column existed.
+      anyOf:
+        - type: string
+        - type: "null"
     updatedAt:
       type: string
       description: ISO-8601 timestamp of last mutation.
@@ -120,6 +153,9 @@ GetKillswitchResponse:
     - id
     - name
     - description
+    - folder
+    - creatorEmail
+    - createdAt
     - updatedAt
     - envs
   additionalProperties: false

package/spec/components/schemas/metrics.yaml

@@ -23,7 +23,43 @@ ListMetricsResponse:
           - type: string
           - type: "null"
       queryIr:
-        $ref: "#/QueryIr"
+        description: Typed query IR, or `null` for a metric whose IR was never populated (re-save it to backfill).
+        anyOf:
+          - $ref: "#/QueryIr"
+          - type: "null"
+      displayName:
+        description: Human-friendly display name shown in the dashboard, or `null` to fall back to `name`.
+        anyOf:
+          - type: string
+          - type: "null"
+      presetId:
+        description: Id of the metric preset this metric was created from, or `null` for a custom metric.
+        anyOf:
+          - type: string
+          - type: "null"
+      unit:
+        description: Display unit (e.g. `ms`, `%`, `$`), or `null` when unitless.
+        anyOf:
+          - type: string
+          - type: "null"
+      version:
+        type: integer
+        description: Monotonic save counter — incremented on every update.
+      deletedAt:
+        description: ISO-8601 soft-delete (archive) timestamp, or `null` while the metric is live.
+        anyOf:
+          - type: string
+          - type: "null"
+      creatorEmail:
+        description: Email of the user who created the metric, or `null` when unknown. List responses only.
+        anyOf:
+          - type: string
+          - type: "null"
+      updaterEmail:
+        description: Email of the user who last edited the metric, or `null` when unknown. List responses only.
+        anyOf:
+          - type: string
+          - type: "null"
       direction:
         type: string
         enum:
@@ -34,14 +70,16 @@ ListMetricsResponse:
       winsorizePct:
         description: Winsorise percentile applied to the metric.
         type: number
-      minDetectableEffect:
-        description: Configured MDE, or `null`.
+      defaultMinEffectOfInterest:
+        description: Metric-level default minimum effect of interest (relative, 0–1), or `null`.
         anyOf:
           - type: number
           - type: "null"
       createdAt:
-        description: ISO-8601 creation timestamp.
-        type: string
+        description: ISO-8601 creation timestamp, or `null` on legacy rows created before the column existed.
+        anyOf:
+          - type: string
+          - type: "null"
       updatedAt:
         description: ISO-8601 last-update timestamp.
         type: string
@@ -52,6 +90,11 @@ ListMetricsResponse:
       - eventName
       - query
       - queryIr
+      - version
+      - displayName
+      - presetId
+      - unit
+      - deletedAt
     additionalProperties: {}
     description: A metric definition.
   description: Every metric in the project (the list endpoint is not paginated).
@@ -78,7 +121,33 @@ GetMetricResponse:
         - type: string
         - type: "null"
     queryIr:
-      $ref: "#/QueryIr"
+      description: Typed query IR, or `null` for a metric whose IR was never populated (re-save it to backfill).
+      anyOf:
+        - $ref: "#/QueryIr"
+        - type: "null"
+    displayName:
+      description: Human-friendly display name shown in the dashboard, or `null` to fall back to `name`.
+      anyOf:
+        - type: string
+        - type: "null"
+    presetId:
+      description: Id of the metric preset this metric was created from, or `null` for a custom metric.
+      anyOf:
+        - type: string
+        - type: "null"
+    unit:
+      description: Display unit (e.g. `ms`, `%`, `$`), or `null` when unitless.
+      anyOf:
+        - type: string
+        - type: "null"
+    version:
+      type: integer
+      description: Monotonic save counter — incremented on every update.
+    deletedAt:
+      description: ISO-8601 soft-delete (archive) timestamp, or `null` while the metric is live.
+      anyOf:
+        - type: string
+        - type: "null"
     direction:
       type: string
       enum:
@@ -89,14 +158,16 @@ GetMetricResponse:
     winsorizePct:
       description: Winsorise percentile applied to the metric.
       type: number
-    minDetectableEffect:
-      description: Configured MDE, or `null`.
+    defaultMinEffectOfInterest:
+      description: Metric-level default minimum effect of interest (relative, 0–1), or `null`.
       anyOf:
         - type: number
         - type: "null"
     createdAt:
-      description: ISO-8601 creation timestamp.
-      type: string
+      description: ISO-8601 creation timestamp, or `null` on legacy rows created before the column existed.
+      anyOf:
+        - type: string
+        - type: "null"
     updatedAt:
       description: ISO-8601 last-update timestamp.
       type: string
@@ -107,6 +178,11 @@ GetMetricResponse:
     - eventName
     - query
     - queryIr
+    - version
+    - displayName
+    - presetId
+    - unit
+    - deletedAt
   additionalProperties: {}
   description: A metric definition.
 QueryIr:
@@ -397,9 +473,9 @@ MetricWinsorizePct:
   type: integer
   minimum: 1
   maximum: 99
-MetricMinDetectableEffect:
+MetricDefaultMinEffectOfInterest:
   default: null
-  description: Minimum detectable effect (relative, 0–1) for power planning. `null` to omit.
+  description: Default minimum effect of interest (relative, 0–1) — the smallest change in this metric worth acting on, used as the power-planning baseline. Intrinsic to the metric; an experiment overrides it per-attachment with `min_effect_of_interest` when a specific decision has a different cost/risk bar. `null` to omit.
   anyOf:
     - type: number
     - type: "null"
@@ -429,8 +505,8 @@ CreateMetricWithQuery:
       $ref: "#/MetricQueryDsl"
     winsorize_pct:
       $ref: "#/MetricWinsorizePct"
-    min_detectable_effect:
-      $ref: "#/MetricMinDetectableEffect"
+    default_min_effect_of_interest:
+      $ref: "#/MetricDefaultMinEffectOfInterest"
     direction:
       $ref: "#/MetricDirection"
   required:
@@ -452,8 +528,8 @@ CreateMetricWithQueryIr:
       $ref: "#/QueryIr"
     winsorize_pct:
       $ref: "#/MetricWinsorizePct"
-    min_detectable_effect:
-      $ref: "#/MetricMinDetectableEffect"
+    default_min_effect_of_interest:
+      $ref: "#/MetricDefaultMinEffectOfInterest"
     direction:
       $ref: "#/MetricDirection"
   required:
@@ -479,8 +555,8 @@ UpdateMetricWithQuery:
       $ref: "#/MetricQueryDsl"
     winsorize_pct:
       $ref: "#/MetricWinsorizePct"
-    min_detectable_effect:
-      $ref: "#/MetricMinDetectableEffect"
+    default_min_effect_of_interest:
+      $ref: "#/MetricDefaultMinEffectOfInterest"
     direction:
       $ref: "#/MetricDirection"
   required:
@@ -498,8 +574,8 @@ UpdateMetricWithQueryIr:
       $ref: "#/QueryIr"
     winsorize_pct:
       $ref: "#/MetricWinsorizePct"
-    min_detectable_effect:
-      $ref: "#/MetricMinDetectableEffect"
+    default_min_effect_of_interest:
+      $ref: "#/MetricDefaultMinEffectOfInterest"
     direction:
       $ref: "#/MetricDirection"
   required:
@@ -515,12 +591,12 @@ UpdateMetricFields:
       $ref: "#/MetricEventName"
     winsorize_pct:
       $ref: "#/MetricWinsorizePct"
-    min_detectable_effect:
-      $ref: "#/MetricMinDetectableEffect"
+    default_min_effect_of_interest:
+      $ref: "#/MetricDefaultMinEffectOfInterest"
     direction:
       $ref: "#/MetricDirection"
   additionalProperties: false
-  description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, MDE, direction).
+  description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction).
 CreateMetricResponse:
   type: object
   properties:
@@ -545,3 +621,104 @@ DeleteMetricResponse:
     - ok
   additionalProperties: false
   description: Soft-delete (archive) acknowledgement.
+UnarchiveMetricResponse:
+  type: object
+  properties:
+    ok:
+      type: boolean
+      const: true
+  required:
+    - ok
+  additionalProperties: false
+  description: Unarchive (undo soft-delete) acknowledgement.
+ListMetricExperimentsResponse:
+  type: object
+  description: Experiments that attach this metric, ordered with running experiments first, then by role weight (goal > guardrail > secondary), then by name.
+  properties:
+    experiments:
+      type: array
+      items:
+        type: object
+        properties:
+          id:
+            type: string
+            description: Stable opaque experiment id.
+          name:
+            type: string
+            description: Experiment name.
+          status:
+            type: string
+            enum:
+              - draft
+              - running
+              - stopped
+              - archived
+            description: Experiment lifecycle status.
+          role:
+            type: string
+            enum:
+              - goal
+              - guardrail
+              - secondary
+            description: Role this metric plays in the experiment. `goal` drives the decision, `guardrail` blocks ship if degraded, `secondary` is informational.
+        required:
+          - id
+          - name
+          - status
+          - role
+        additionalProperties: false
+        description: One experiment attaching this metric.
+      description: Every experiment (any status) attaching this metric.
+  required:
+    - experiments
+  additionalProperties: false
+GetMetricSeriesRequest:
+  type: object
+  description: |-
+    Time window for the metric series. Bounds are epoch **seconds** (Analytics Engine stores the event timestamp in seconds). `to` must be strictly greater than `from`.
+  properties:
+    from:
+      type: integer
+      minimum: 0
+      description: Window start, epoch seconds (inclusive).
+    to:
+      type: integer
+      minimum: 0
+      description: Window end, epoch seconds (exclusive). Must be greater than `from`.
+    bucket:
+      type: integer
+      minimum: 60
+      maximum: 86400
+      default: 3600
+      description: Bucket width in seconds (60s–86400s/1d). Defaults to `3600` (hourly). Each returned point is floor-aligned to this width.
+  required:
+    - from
+    - to
+  additionalProperties: false
+GetMetricSeriesResponse:
+  type: object
+  description: Bucketed values for one metric, compiled from its typed IR and executed against the Analytics Engine SQL API, plus the SQL that produced them. Capped at 5000 rows (high-cardinality `groupBy` series are truncated).
+  properties:
+    sql:
+      type: string
+      description: The Analytics Engine SQL executed to produce `rows` (echoed for transparency / debugging).
+    rows:
+      type: array
+      description: Bucketed series, ordered by `t` ascending. For a metric with a `groupBy` clause each bucket has one row per label combination, with the label values as extra string/number properties on the row.
+      items:
+        type: object
+        properties:
+          t:
+            type: integer
+            description: Bucket start, epoch seconds, floor-aligned to `bucket`.
+          v:
+            type: number
+            description: Aggregated metric value in the bucket (sample-interval weighted).
+        required:
+          - t
+          - v
+        additionalProperties: true
+  required:
+    - sql
+    - rows
+  additionalProperties: false