@shipeasy/openapi 1.6.0 → 2.2.0

package/spec/openapi.yaml

@@ -0,0 +1,367 @@
+openapi: 3.2.0
+info:
+  title: Shipeasy Admin API
+  version: 2.0.0
+  description: |-
+    REST API for managing feature gates, experiments, configs, universes, and killswitches in a Shipeasy project. Authenticate with an admin SDK key (`Authorization: Bearer sdk_admin_…`) and scope every request to a project via the `X-Project-Id` header.
+
+    Mint admin keys via `POST /api/admin/keys` with `type: "admin"`. Keys expire after 90 days; rotate with the `revoke` action.
+  contact:
+    name: Shipeasy
+    url: https://shipeasy.ai
+  license:
+    name: Proprietary
+    identifier: LicenseRef-Proprietary
+servers:
+  - url: https://shipeasy.ai
+    description: Production
+  - url: http://localhost:3000
+    description: Local Next.js dev server
+security:
+  - bearerSdkKey: []
+tags:
+  - name: Release
+    summary: >-
+      Feature delivery — flags, kill switches, dynamic configs, A/B experiments,
+      and the universes they bucket in.
+    kind: nav
+    description: |-
+      Release: the feature-delivery surface. One roof over the five resources
+      that decide which code path a user gets — feature gates (flags), kill
+      switches, dynamic configs, A/B/n experiments, and the universes that bucket
+      them — each exposed as its own subcommand group.
+
+      **Groups.**
+      - `flags` — boolean feature gates: AND-combined targeting rules + a percentage rollout (basis points), evaluated on the SDK hot path.
+      - `killswitch` (`ks`) — per-env boolean overrides for incident response; no rules, no rollout, versioned per environment.
+      - `configs` — JSON-Schema-validated structured values with a draft → publish workflow, delivered per environment.
+      - `experiments` — randomised A/B/n assignment plus the analysis pipeline (t-test, sequential testing, SRM detection); `universes` hold the shared bucketing space and holdouts the experiments draw from.
+
+      **Delivery model.** Every write rebuilds the project's KV blob and purges
+      the CDN — SDKs poll at the plan interval and never touch the database on
+      the hot path. The destructive verb is `archive` (soft-delete), never
+      `delete`.
+
+      Run `shipeasy release <group> --help` for the full contract of each group.
+  - name: Flags
+    parent: Release
+    description: |-
+      Feature gates: boolean flags evaluated at runtime against project rules + a percentage rollout.
+
+      **Identity.** Each gate is keyed by a stable `name` (a-z, 0-9, `_`/`-`, max 64 chars) which is what SDKs pass to `Shipeasy.checkGate(user, '<name>')`. The `name` is immutable — rename means delete + recreate.
+
+      **Evaluation model.** A gate returns `true` when (a) `enabled` is true, and (b) the caller satisfies the gate's rules. There are two evaluation shapes:
+      - **Flat** — `rules` (AND-combined predicates) gate the caller, then `rollout_pct` (basis points, 0–10000) hashes them into a bucket. Used for simple `is in X% rollout` gates.
+      - **Gatekeeper stack** — an ordered array of `condition` and `rollout` sub-gates, evaluated top-to-bottom; first match wins. Used to express `internal-only ∪ 1% beta ∪ 50% public` in one gate. When `stack` is present it takes precedence over the flat fields.
+
+      **Rules.** Each rule is `{ attr, op, value }`. Supported ops: `eq`, `neq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `contains`, `regex`. Attribute names match the keys on the SDK evaluation context (e.g. `country`, `plan`, `email`).
+
+      **Rollout basis points.** `rollout_pct` is in **basis points**, not percent. `0` = 0%, `100` = 1%, `5000` = 50%, `10000` = 100%. This allows sub-1% precision (e.g. `7` = 0.07%).
+
+      **Lifecycle.** Create dark (`rollout_pct: 0`) → attach rules → ramp via PATCH → flip kill-switch via `disable`/`enable` → delete once retired. Deletion is blocked while a running experiment references the gate as a targeting gate.
+  - name: Killswitch
+    parent: Release
+    x-cli:
+      aliases:
+        - ks
+    description: |-
+      Killswitches: per-env boolean overrides for kill-style operational toggles. Optimised for incident response — no rules, no rollout, just a flat boolean (plus optional per-key overrides) versioned per environment.
+
+      **Identity.** Each killswitch is keyed by `name` in `folder.name` form (e.g. `payments.checkout`). Immutable after create.
+
+      **Per-env values.** Every killswitch stores one version stream per env (`dev`, `stage`, `prod`). A `PATCH` with `value`/`switches` applies to **every** env in one shot (publishes a new version per env). To touch a single env, use `PUT /{id}/switch` and friends.
+
+      **Switches map.** Optional `switches: { key: bool }` overrides the flat `value` for specific named call sites — useful for region/feature-scoped kills.
+
+      **Versioning.** Each publish (create, update, set-switch, unset-switch) bumps the per-env `version` monotonically. SDKs deliver the latest published version.
+  - name: Configs
+    parent: Release
+    description: |-
+      Dynamic configs: JSON-Schema-validated structured values delivered to SDKs and editable per environment with a draft/publish workflow.
+
+      **Identity.** Each config is keyed by `name` in `folder.name` form (e.g. `pricing.tiers`). Immutable after create.
+
+      **Schema-first.** Every config carries a JSON Schema (draft 2020-12, top-level `type: 'object'`). Every published value is validated against it.
+
+      **Drafts → publish.** Per-env edits go through `PUT /{id}/drafts` (stages a value) then `POST /{id}/publish` (promotes to a new version). The flat `PATCH /{id}` republishes on **every** env in one shot — bypassing drafts.
+
+      **Versioning.** Each publish bumps the per-env `version` monotonically. SDKs deliver the latest published version for each env.
+  - name: Experiments
+    parent: Release
+    description: |-
+      A/B/n experiments: randomised group assignment plus the analysis pipeline (t-test, sequential testing, SRM detection) on top of a universe.
+
+      **Identity.** Stable `name` (a-z, 0-9, `_`/`-`, max 64 chars). Immutable after create.
+
+      **Lifecycle.** `draft → running → stopped → archived`. Transition via `POST /{id}/status`. An archived experiment that never started can be restored with `archived → draft`; restarting an archived experiment directly is not allowed.
+
+      **Allocation.** `allocation_pct` (basis points, 0–10000) is the share of the targeted audience enrolled; `groups[].weight` (must sum to 10000) splits the enrolled audience. `targeting_gate` narrows the eligible audience before allocation.
+
+      **Immutable while running.** `allocation_pct`, `groups`, `salt`, `universe`, `params` cannot be edited on a running experiment — stop it first.
+
+      **Metrics.** Attach via `POST /{id}/metrics`. Each metric has a role: `goal` drives the decision, `guardrail` blocks ship on regression, `secondary` is informational.
+
+      **Analysis.** Daily cron writes results to D1. Read via `GET /{id}/results` (latest per metric/group/day) or `GET /{id}/timeseries` (full history). `POST /{id}/reanalyze` requeues the analysis pass.
+  - name: Universes
+    parent: Experiments
+    description: |-
+      Universes: the shared bucketing space all experiments draw from.
+
+      **Identity.** Each universe is keyed by a stable `name` (a-z, 0-9, `_`/`-`, max 64 chars). Experiments reference it via `universe: '<name>'`. The name is immutable.
+
+      **Unit of randomisation.** `unit_type` selects the attribute hashed into a 0–9999 bucket — default `user_id` for per-user randomisation, `account_id` to keep a whole account in the same group.
+
+      **Holdout.** `holdout_range` is an inclusive `[lo, hi]` bucket range (0–9999) reserved for measurement — callers hashed into the holdout are excluded from every experiment in the universe. Pro plan or higher.
+
+      **Deletion.** Blocked while any non-archived experiment references the universe — archive those first.
+  - name: Templates
+    parent: Flags
+    description: |-
+      Targeting-rule templates: reusable `{ attr, op, value }` rule definitions
+      (country, email-domain, region presets, …). Read-only built-ins ship with
+      the platform; each project can also save its own. To target by
+      country/plan/region, list templates, copy the matching template's `rules`,
+      substitute the concrete value(s), and pass them to `release flags create`.
+  - name: Attributes
+    parent: Flags
+    description: |-
+      Targeting attributes: the auto-inferred schema of user-context keys the
+      platform has observed in evaluation calls. Read-only — populated by the
+      SDK hot path, surfaced here so you can see which keys (and value types)
+      are available when writing gate/experiment targeting rules.
+  - name: Metrics
+    description: |-
+      Metrics: the event-backed queries that drive tracking dashboards and
+      experiment success / guardrail measurement.
+
+      **Definition.** Each metric pins one source event (`event_name`), one
+      aggregation, and (for `sum`/`avg`/quantile) a numeric value label. The
+      query is expressed as the DSL string (`query`, e.g. `sum(purchase, amount)`)
+      or its typed IR (`query_ir`) — supply exactly one.
+
+      **Identity.** Keyed by a stable `name` (single segment or `folder.name`).
+      Resolve endpoints accept the `id` or the `name`.
+
+      **Deletion.** Archive (soft-delete). Blocked while the metric is attached
+      to a running experiment — stop those first.
+  - name: Events
+    parent: Metrics
+    description: |-
+      Events: the catalog of event names (and their typed properties) that metric queries reference.
+
+      **Auto-discovery.** The SDK's `/collect` ingest path records any unknown event name it receives as a `pending` row (`pending: 1`) so you can review it. Metrics defined on a pending event fail until it is approved.
+
+      **Approval.** `POST /{id}/approve` promotes a pending event to usable (`pending: 0`), optionally declaring its folder/description/properties in the same call. Registering a brand-new event via `POST` that matches a pending name approves it instead of failing with a conflict.
+
+      **Properties.** Each event can declare typed properties (`name`, `type` of `string|number|boolean`, `required`). On update/approve the `properties` array replaces the full set — there is no merge.
+
+      **Deletion.** Soft-delete (the user-facing verb is `archive`). Blocked while any metric still references the event — delete those metrics first.
+  - name: Ops
+    description: |-
+      Operational queue: the unified table of bug reports, feature requests, and
+      auto-filed error/alert tickets, all over `/api/admin/ops`. One `create`
+      endpoint files either user type (`type: bug | feature_request`); list, get,
+      update, and link-pr are unified across every type. Also exposes the
+      `notify` escalation bell and the read-only Slack-channels list used to
+      resolve alert-rule notification targets.
+
+      **Handles.** A queue item is addressed by its per-project `number` (e.g. `7`)
+      or its full id — the API resolves either.
+  - name: Alerts
+    parent: Ops
+    x-cli:
+      aliases:
+        - ar
+    description: |-
+      Alert rules: the metric-threshold definitions the analysis cron evaluates each run.
+
+      **What fires.** Each rule binds a `metricId`, a `comparator` (`gt`/`gte`/`lt`/`lte`), and a `threshold`. On every cron pass the cron aggregates the metric over the trailing `windowHours` and raises an alert at `severity` when `value comparator threshold` holds.
+
+      **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: Projects
+    description: |-
+      Projects: the account-level container every other resource is scoped to.
+
+      **Account-level, not bound-project-level.** Both operations resolve from the caller's credential rather than the `.shipeasy`-bound project — `current` reads the project the auth header maps to, and `upsert` find-or-creates under the session's owner. Neither touches the local `.shipeasy` binding; recording the result there is a consumer side-effect layered on top.
+
+      **Idempotent upsert.** A project is keyed by `(owner_email, domain)`. Calling `upsert` again with the same domain returns the existing project with `created: false`, so it is safe to run on every install.
+  - name: i18n
+    description: |-
+      String Manager (i18n): the worker-safe REST surface — locale profiles, the
+      insert-only key push, single-key overwrite, chunk publish, and the read-only
+      key/draft listings.
+
+      The fs/AST parts (scan, validate, install-loader, codemod) are NOT part of
+      this API — they stay in the fs-having CLI/MCP.
+  - name: Profiles
+    parent: i18n
+    description: Locale profiles (e.g. `en:prod`) — create, list, and publish a profile's chunks to the CDN.
+  - name: Keys
+    parent: i18n
+    description: Translation keys — the insert-only push, single-key overwrite, and key listing.
+  - name: Drafts
+    parent: i18n
+    description: Machine-translation drafts awaiting review before publish.
+  - name: Errors
+    description: |-
+      Tracked production errors: the deduplicated, fingerprinted error stream the
+      SDK + framework error sinks feed. Read-only list/get plus a status update
+      (`open`/`resolved`/`ignored`), an auto-file-to-GitHub-issue action, and a
+      time-series rollup. Errors are ingestion-only — there is no create route.
+  - name: Trigger
+    parent: Ops
+    description: |-
+      Recurring coding-agent triggers: the scheduled, unattended runs that burn
+      down the ops queue in `--pr` mode (one PR per fixed item; nothing
+      auto-merges). Shipeasy can fire four providers directly — Claude routines,
+      Cursor cloud agents, Copilot cloud agents, and Google Jules (the Gemini
+      path) — registered here as trigger connectors (idempotent per provider
+      key). Other platforms (Codex, Windsurf, Cline, OpenClaw, OpenCode,
+      Continue) schedule on their own surface — typically a GitHub Actions
+      `schedule:` cron running the platform's headless CLI with the shared
+      trigger prompt.
+  - name: Connectors
+    description: |-
+      Outbound integrations: the per-project destinations feedback + trigger
+      events are dispatched to (GitHub, Google Sheets, Slack, and the
+      Claude/Cursor/Copilot/Jules autopilot triggers). CRUD plus a manual
+      `fire` (trigger-only) and a `test` payload.
+  - name: API Keys
+    description: |-
+      Admin + SDK key management: mint, list, and revoke the `sdk_*` keys that
+      authenticate every other endpoint. The plaintext key is returned exactly
+      once, on create. Revoke is the rotation verb.
+paths:
+  /api/admin/gates:
+    $ref: ./paths/gates.yaml#/~1api~1admin~1gates
+  /api/admin/gates/{id}:
+    $ref: ./paths/gates.yaml#/~1api~1admin~1gates~1{id}
+  /api/admin/gates/{id}/enable:
+    $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/experiments:
+    $ref: ./paths/experiments.yaml#/~1api~1admin~1experiments
+  /api/admin/experiments/{id}:
+    $ref: ./paths/experiments.yaml#/~1api~1admin~1experiments~1{id}
+  /api/admin/experiments/{id}/status:
+    $ref: ./paths/experiments.yaml#/~1api~1admin~1experiments~1{id}~1status
+  /api/admin/experiments/{id}/metrics:
+    $ref: ./paths/experiments.yaml#/~1api~1admin~1experiments~1{id}~1metrics
+  /api/admin/experiments/{id}/results:
+    $ref: ./paths/experiments.yaml#/~1api~1admin~1experiments~1{id}~1results
+  /api/admin/experiments/{id}/timeseries:
+    $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/configs:
+    $ref: ./paths/configs.yaml#/~1api~1admin~1configs
+  /api/admin/configs/{id}:
+    $ref: ./paths/configs.yaml#/~1api~1admin~1configs~1{id}
+  /api/admin/configs/{id}/drafts:
+    $ref: ./paths/configs.yaml#/~1api~1admin~1configs~1{id}~1drafts
+  /api/admin/configs/{id}/publish:
+    $ref: ./paths/configs.yaml#/~1api~1admin~1configs~1{id}~1publish
+  /api/admin/configs/{id}/activity:
+    $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/killswitches:
+    $ref: ./paths/killswitches.yaml#/~1api~1admin~1killswitches
+  /api/admin/killswitches/{id}:
+    $ref: ./paths/killswitches.yaml#/~1api~1admin~1killswitches~1{id}
+  /api/admin/killswitches/{id}/switch:
+    $ref: ./paths/killswitches.yaml#/~1api~1admin~1killswitches~1{id}~1switch
+  /api/admin/killswitches/{id}/value:
+    $ref: ./paths/killswitches.yaml#/~1api~1admin~1killswitches~1{id}~1value
+  /api/admin/universes:
+    $ref: ./paths/universes.yaml#/~1api~1admin~1universes
+  /api/admin/universes/{id}:
+    $ref: ./paths/universes.yaml#/~1api~1admin~1universes~1{id}
+  /api/admin/gates/templates:
+    $ref: ./paths/gate-templates.yaml#/~1api~1admin~1gates~1templates
+  /api/admin/gates/templates/{id}:
+    $ref: ./paths/gate-templates.yaml#/~1api~1admin~1gates~1templates~1{id}
+  /api/admin/attributes:
+    $ref: ./paths/attributes.yaml#/~1api~1admin~1attributes
+  /api/admin/attributes/{id}:
+    $ref: ./paths/attributes.yaml#/~1api~1admin~1attributes~1{id}
+  /api/admin/metrics:
+    $ref: ./paths/metrics.yaml#/~1api~1admin~1metrics
+  /api/admin/metrics/{id}:
+    $ref: ./paths/metrics.yaml#/~1api~1admin~1metrics~1{id}
+  /api/admin/events:
+    $ref: ./paths/events.yaml#/~1api~1admin~1events
+  /api/admin/events/{id}:
+    $ref: ./paths/events.yaml#/~1api~1admin~1events~1{id}
+  /api/admin/events/{id}/approve:
+    $ref: ./paths/events.yaml#/~1api~1admin~1events~1{id}~1approve
+  /api/admin/ops:
+    $ref: ./paths/ops.yaml#/~1api~1admin~1ops
+  /api/admin/ops/{handle}:
+    $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/notifications:
+    $ref: ./paths/ops.yaml#/~1api~1admin~1notifications
+  /api/admin/slack/channels:
+    $ref: ./paths/ops.yaml#/~1api~1admin~1slack~1channels
+  /api/admin/alert-rules:
+    $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/projects/current:
+    $ref: ./paths/projects.yaml#/~1api~1admin~1projects~1current
+  /api/admin/projects/upsert:
+    $ref: ./paths/projects.yaml#/~1api~1admin~1projects~1upsert
+  /api/admin/projects/{id}:
+    $ref: ./paths/projects.yaml#/~1api~1admin~1projects~1{id}
+  /api/admin/i18n/profiles:
+    $ref: ./paths/i18n.yaml#/~1api~1admin~1i18n~1profiles
+  /api/admin/i18n/keys:
+    $ref: ./paths/i18n.yaml#/~1api~1admin~1i18n~1keys
+  /api/admin/i18n/keys/{id}:
+    $ref: ./paths/i18n.yaml#/~1api~1admin~1i18n~1keys~1{id}
+  /api/admin/i18n/drafts:
+    $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}/publish:
+    $ref: ./paths/i18n.yaml#/~1api~1admin~1i18n~1profiles~1{profileId}~1publish
+  /api/admin/i18n/set:
+    $ref: ./paths/i18n.yaml#/~1api~1admin~1i18n~1set
+  /api/admin/errors:
+    $ref: ./paths/errors.yaml#/~1api~1admin~1errors
+  /api/admin/errors/{id}:
+    $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}/series:
+    $ref: ./paths/errors.yaml#/~1api~1admin~1errors~1{id}~1series
+  /api/admin/connectors:
+    $ref: ./paths/connectors.yaml#/~1api~1admin~1connectors
+  /api/admin/connectors/{id}:
+    $ref: ./paths/connectors.yaml#/~1api~1admin~1connectors~1{id}
+  /api/admin/connectors/{id}/fire:
+    $ref: ./paths/connectors.yaml#/~1api~1admin~1connectors~1{id}~1fire
+  /api/admin/connectors/{id}/test:
+    $ref: ./paths/connectors.yaml#/~1api~1admin~1connectors~1{id}~1test
+  /api/admin/connectors/{id}/trigger:
+    $ref: ./paths/connectors.yaml#/~1api~1admin~1connectors~1{id}~1trigger
+  /api/admin/connectors/trigger:
+    $ref: ./paths/connectors.yaml#/~1api~1admin~1connectors~1trigger
+  /api/admin/keys:
+    $ref: ./paths/keys.yaml#/~1api~1admin~1keys
+  /api/admin/keys/{id}/revoke:
+    $ref: ./paths/keys.yaml#/~1api~1admin~1keys~1{id}~1revoke
+  /api/admin/search:
+    $ref: ./paths/search.yaml#/~1api~1admin~1search
+components:
+  securitySchemes:
+    bearerSdkKey:
+      type: http
+      scheme: bearer
+      bearerFormat: sdk_admin_*
+      description: 'Pass an admin SDK key as `Authorization: Bearer sdk_admin_…`. Mint via `POST /api/admin/keys` with `type: "admin"`.'

package/spec/paths/alert-rules.yaml

@@ -0,0 +1,258 @@
+/api/admin/alert-rules:
+  get:
+    operationId: listAlertRules
+    summary: List alert rules
+    description: |-
+      Returns every alert rule in the project (not paginated). Each rule carries its bound `metricId`, the denormalised `metricName` (or `null` if the metric was removed), the comparator/threshold/window, severity, enabled flag, and delivery target.
+
+      **Use case:** Audit which metrics have alerting configured — for example to confirm an on-call threshold is set before a launch.
+    tags:
+      - Alerts
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - $ref: ../components/parameters.yaml#/Q
+    responses:
+      "200":
+        description: List alert rules
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/alert-rules.yaml#/ListAlertRulesResponse
+            example:
+              - id: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
+                name: Checkout error rate
+                metricId: met_01j6abc2d3e4f5g6h7i8j9k0l1
+                metricName: checkout_errors
+                comparator: gt
+                threshold: 50
+                windowHours: 24
+                severity: warn
+                enabled: true
+                notify: null
+                createdAt: 2026-04-12T10:14:08.000Z
+                updatedAt: 2026-04-12T10:14:08.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
+    x-cli:
+      name: list
+  post:
+    operationId: createAlertRule
+    summary: Create an alert rule
+    description: |-
+      Creates a metric-threshold alert rule. `name`, `metricId`, `comparator`, and `threshold` are required; `windowHours` defaults to `24`, `severity` to `warn`, and `enabled` to `true`.
+
+      Returns `404` if `metricId` does not resolve, and `400` for a metric with no scalar form over a window (e.g. retention metrics) — the cron can't evaluate those.
+
+      **Use cases**
+
+      - **Threshold alert** — warn when an error/latency metric crosses a value over a rolling window.
+      - **Routed alert** — set `notify` to page a specific Slack channel or on-call email instead of the project default.
+    tags:
+      - Alerts
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/alert-rules.yaml#/CreateAlertRuleRequest
+          examples:
+            minimal:
+              summary: Minimal — alert when a metric exceeds a threshold
+              description: Smallest valid body. Warns when the metric exceeds 50 over the default 24h window, with no per-rule delivery target.
+              value:
+                name: Checkout error rate
+                metricId: met_01j6abc2d3e4f5g6h7i8j9k0l1
+                comparator: gt
+                threshold: 50
+            targeted:
+              summary: Full — custom window, severity, and Slack/email target
+              description: A `danger` rule over a 1h window that posts to a Slack channel and emails on-call. The Slack channel must come from a connected connector.
+              value:
+                name: Checkout error spike
+                metricId: met_01j6abc2d3e4f5g6h7i8j9k0l1
+                comparator: gt
+                threshold: 100
+                windowHours: 1
+                severity: danger
+                notify:
+                  slackChannel:
+                    id: C0123ABCD
+                    name: incidents
+                  email: oncall@acme.com
+    responses:
+      "201":
+        description: Create an alert rule
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/alert-rules.yaml#/CreateAlertRuleResponse
+            example:
+              id: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
+        links:
+          UpdateAlertRule:
+            operationId: updateAlertRule
+            parameters: { id: $response.body#/id }
+          DeleteAlertRule:
+            operationId: deleteAlertRule
+            parameters: { id: $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
+      - ALREADY_EXISTS
+      - REFERENCED_NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: create
+/api/admin/alert-rules/{id}:
+  patch:
+    operationId: updateAlertRule
+    summary: Update an alert rule
+    description: |-
+      Partial update of a rule's tunable knobs. `metricId` is immutable — the metric also pins the aggregation, so a body carrying `metricId` is rejected with `409 IMMUTABLE_FIELD`; create a new rule bound to the other metric instead (rule deletion is dashboard-only).
+
+      Pass `"notify": null` to revert the rule's delivery target back to the project default.
+
+      **Use cases**
+
+      - **Tune sensitivity** — change `threshold`/`comparator`/`windowHours` as the metric's baseline shifts.
+      - **Pause without losing config** — `{ "enabled": false }` instead of deleting the rule.
+    tags:
+      - Alerts
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque alert-rule id (`ar_…`) or the rule's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/alert-rules.yaml#/UpdateAlertRuleRequest
+          examples:
+            raiseThreshold:
+              summary: Raise the threshold
+              description: Bump the alerting threshold without touching anything else.
+              value:
+                threshold: 100
+            disable:
+              summary: Disable the rule
+              description: Stop the cron from evaluating the rule.
+              value:
+                enabled: false
+            clearTarget:
+              summary: Revert to the project default target
+              description: Drop the per-rule Slack/email target and fall back to project defaults.
+              value:
+                notify: null
+    responses:
+      "200":
+        description: Update an alert rule
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/alert-rules.yaml#/UpdateAlertRuleResponse
+            example:
+              id: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
+      "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
+      - IMMUTABLE_FIELD
+      - VALIDATION
+    x-cli:
+      name: update
+      positional:
+        - id
+  delete:
+    operationId: deleteAlertRule
+    summary: Delete an alert rule
+    description: |-
+      Deletes the alert rule. The cron stops evaluating it immediately. Use this (then create a new rule) to repoint alerting at a different metric, since `metricId` is immutable.
+
+      **Use case:** Remove an alert rule that is no longer needed, or as the first half of repointing a rule at a different metric.
+    tags:
+      - Alerts
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque alert-rule id (`ar_…`) or the rule's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Delete an alert rule
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/alert-rules.yaml#/DeleteAlertRuleResponse
+            example:
+              ok: true
+      "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: archive
+      positional:
+        - id