@shipeasy/openapi 3.1.0 → 3.3.0

package/spec/components/schemas/connectors.yaml

@@ -204,7 +204,7 @@ CreateCursorTriggerRequest:
     opsKey:
       type: string
       minLength: 1
-      description: Restricted Shipeasy ops key, injected into the run as `SHIPEASY_CLI_TOKEN` via the launch envVars (secret). Encrypted; never returned.
+      description: Restricted Shipeasy ops key (secret). Sent as the Bearer for the Shipeasy MCP server handed to each run inline — never in the prompt text or the run env. Encrypted; never returned.
     enabled:
       type: boolean
       default: true
@@ -308,33 +308,82 @@ ClaudeTriggerConfig:
     - routineId
   additionalProperties: false
   description: Non-secret config for a Claude trigger.
+CursorTriggerRepo:
+  type: object
+  properties:
+    url:
+      type: string
+      format: uri
+      description: "Repo the cloud agent runs against, e.g. `https://github.com/owner/repo`."
+    startingRef:
+      type: string
+      minLength: 1
+      description: "Optional branch this repo's runs start from. Omit for the repo's default branch."
+  required:
+    - url
+  additionalProperties: false
+  description: One repo a trigger runs against, with the branch its runs start from.
 CursorTriggerConfig:
   type: object
   properties:
     repoUrl:
       type: string
       format: uri
-      description: Repo the cloud agent runs against, e.g. `https://github.com/owner/repo`. Idempotency key for the connector.
+      description: "**First** repo the cloud agent runs against, e.g. `https://github.com/owner/repo`. Idempotency key for the connector, and always a mirror of `repos[0].url` when `repos` is supplied."
     startingRef:
       type: string
       minLength: 1
-      description: Optional git ref the run starts from.
+      description: Optional git ref the run starts from. Mirrors `repos[0].startingRef`. Pinned onto the Cursor agent at creation, so changing it provisions a replacement agent.
+    repos:
+      type: array
+      minItems: 1
+      items:
+        $ref: "#/CursorTriggerRepo"
+      description: "Every repo this trigger runs against, each with its own starting branch — Cursor launches ONE agent across the whole set. Omit for a single-repo trigger, which is then described by `repoUrl`/`startingRef` alone; when supplied, the first entry must match them. Changing the set re-provisions the agent (its repos are pinned at creation)."
     projectId:
       type: string
       minLength: 1
       description: Shipeasy project id the run targets.
+    agentId:
+      type: string
+      minLength: 1
+      description: "Server-managed. The reusable Cursor cloud agent (`bc-…`) Shipeasy provisions once at connect and then starts every run on. A supplied value is ignored on create; if Cursor stops recognising the id (404), the next fire provisions a replacement and stores it here."
+    fireText:
+      type: string
+      minLength: 1
+      description: "Optional standing instruction prepended to every run's prompt — the trigger's base prompt. Lets two triggers on different repos steer their runs differently without changing the `/shipeasy-ops-work` task block."
   required:
     - repoUrl
     - projectId
   additionalProperties: false
   description: Non-secret config for a Cursor trigger.
+CopilotTriggerRepo:
+  type: object
+  properties:
+    owner:
+      type: string
+      minLength: 1
+      description: GitHub repo owner.
+    repo:
+      type: string
+      minLength: 1
+      description: GitHub repo name.
+    baseRef:
+      type: string
+      minLength: 1
+      description: "Optional base ref this repo's agent task branches from. Omit for the repo's default branch."
+  required:
+    - owner
+    - repo
+  additionalProperties: false
+  description: One repo a Copilot trigger runs against, with the base branch its tasks branch from.
 CopilotTriggerConfig:
   type: object
   properties:
     owner:
       type: string
       minLength: 1
-      description: GitHub repo owner. Together with `repo` forms the connector's idempotency key (`owner/repo`).
+      description: "**First** GitHub repo owner. Together with `repo` forms the connector's idempotency key (`owner/repo`), and both mirror `repos[0]` when `repos` is supplied."
     repo:
       type: string
       minLength: 1
@@ -342,11 +391,21 @@ CopilotTriggerConfig:
     baseRef:
       type: string
       minLength: 1
-      description: Optional base ref the agent branches from.
+      description: Optional base ref the agent branches from. Mirrors `repos[0].baseRef`.
+    repos:
+      type: array
+      minItems: 1
+      items:
+        $ref: "#/CopilotTriggerRepo"
+      description: "Every repo this trigger runs against, each with its own base branch. GitHub's agent-tasks API is per-repo, so ONE fire starts one task per entry. Omit for a single-repo trigger, which is then described by `owner`/`repo`/`baseRef` alone; when supplied, the first entry must match them."
     projectId:
       type: string
       minLength: 1
       description: Shipeasy project id the run targets.
+    fireText:
+      type: string
+      minLength: 1
+      description: "Optional standing instruction prepended to every run's prompt — the trigger's base prompt. Lets two triggers on different repos steer their runs differently without changing the `/shipeasy-ops-work` task block."
   required:
     - owner
     - repo
@@ -368,6 +427,10 @@ JulesTriggerConfig:
       type: string
       minLength: 1
       description: Shipeasy project id the run targets.
+    fireText:
+      type: string
+      minLength: 1
+      description: "Optional standing instruction prepended to every run's prompt — the trigger's base prompt. Lets two triggers on different repos steer their runs differently without changing the `/shipeasy-ops-work` task block."
   required:
     - source
     - projectId
@@ -452,7 +515,7 @@ UpdateCursorTriggerRequest:
     - provider
     - config
   additionalProperties: false
-  description: "Per-provider PATCH body for editing an existing `cursor_trigger` connector. `config` replaces the stored config wholesale; `name` and either credential are optional (a supplied credential rotates just that key)."
+  description: "Per-provider PATCH body for editing an existing `cursor_trigger` connector. `config` replaces the stored config wholesale, except for the server-managed keys: the provisioned `agentId` is carried over (and dropped, so a replacement agent is provisioned, when `repoUrl`/`startingRef` change), as is the last-run pointer. `name` and either credential are optional (a supplied credential rotates just that key)."
 UpdateCopilotTriggerRequest:
   type: object
   properties:

package/spec/components/schemas/events.yaml

@@ -33,7 +33,8 @@ ListEventsResponse:
               type: string
               minLength: 1
               maxLength: 64
-              description: Property key, e.g. `amount` or `plan`.
+              pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
+              description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
             type:
               type: string
               enum:
@@ -49,11 +50,14 @@ ListEventsResponse:
               default: ""
               description: Human-readable description of the property.
               type: string
+            pending:
+              description: "`true` when this property was DISCOVERED in live traffic rather than declared. Nothing is recorded for it yet — a property is written to Analytics Engine only once it owns a column, and a column is allocated when an admin declares the property (include it in a `PATCH .../events/{id}` body). Approval is a gate rather than a formality: columns are finite and permanently reserved, so auto-allocating them from customer payload keys would exhaust an event's schema irreversibly."
+              type: boolean
           required:
             - name
             - type
           additionalProperties: false
-          description: One typed property declared on a catalogued event.
+          description: One typed property on a catalogued event — declared by an admin, or discovered in traffic and awaiting declaration.
         description: Typed properties declared on the event.
       pending:
         type: integer
@@ -106,7 +110,8 @@ GetEventResponse:
             type: string
             minLength: 1
             maxLength: 64
-            description: Property key, e.g. `amount` or `plan`.
+            pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
+            description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
           type:
             type: string
             enum:
@@ -122,11 +127,14 @@ GetEventResponse:
             default: ""
             description: Human-readable description of the property.
             type: string
+          pending:
+            description: "`true` when this property was DISCOVERED in live traffic rather than declared. Nothing is recorded for it yet — a property is written to Analytics Engine only once it owns a column, and a column is allocated when an admin declares the property (include it in a `PATCH .../events/{id}` body). Approval is a gate rather than a formality: columns are finite and permanently reserved, so auto-allocating them from customer payload keys would exhaust an event's schema irreversibly."
+            type: boolean
         required:
           - name
           - type
         additionalProperties: false
-        description: One typed property declared on a catalogued event.
+        description: One typed property on a catalogued event — declared by an admin, or discovered in traffic and awaiting declaration.
       description: Typed properties declared on the event.
     pending:
       type: integer
@@ -150,8 +158,8 @@ CreateEventRequest:
   properties:
     name:
       type: string
-      pattern: ^[a-zA-Z0-9_][a-zA-Z0-9_\-.]{0,127}$
-      description: Event name. Starts with a letter, digit, or `_`; letters, digits, `_`, `-`, `.`; max 128 chars. Immutable after create — this is the handle metric queries reference.
+      pattern: ^[a-zA-Z0-9_][a-zA-Z0-9_\-.]{0,49}$
+      description: Event name. Starts with a letter, digit, or `_`; letters, digits, `_`, `-`, `.`; max 50 characters. The cap is the Analytics Engine index budget — 96 bytes total, less a 36-byte project UUID and a separator — and the API has always enforced 50 while this spec advertised 128. The charset is ASCII, so characters and bytes are the same count. Immutable after create — this is the handle metric queries reference.
     folder:
       $ref: ./common.yaml#/Folder
     description:
@@ -168,7 +176,8 @@ CreateEventRequest:
             type: string
             minLength: 1
             maxLength: 64
-            description: Property key, e.g. `amount` or `plan`.
+            pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
+            description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
           type:
             type: string
             enum:
@@ -225,7 +234,8 @@ UpdateEventRequest:
             type: string
             minLength: 1
             maxLength: 64
-            description: Property key, e.g. `amount` or `plan`.
+            pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
+            description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
           type:
             type: string
             enum:
@@ -276,7 +286,8 @@ ApproveEventRequest:
             type: string
             minLength: 1
             maxLength: 64
-            description: Property key, e.g. `amount` or `plan`.
+            pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
+            description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
           type:
             type: string
             enum:

package/spec/components/schemas/gates.yaml

@@ -980,3 +980,90 @@ ListGateActivityResponse:
       - createdAt
     additionalProperties: false
   description: Recent audit rows for one gate, newest first.
+GateWhitelistAttr:
+  type: string
+  enum:
+    - email
+    - user_id
+  description: Which identity attribute the whitelist matches on. `email` compares the caller's `email`; `user_id` compares the caller's `userID`. A whitelist matches on exactly one of the two at a time.
+GateWhitelist:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Resolved gate id.
+    name:
+      type: string
+      description: The gate's stable `name`.
+    attr:
+      $ref: "#/GateWhitelistAttr"
+    entries:
+      type: array
+      items:
+        type: string
+        minLength: 1
+      description: The whitelisted identities, in the order they are stored. Deduplicated case-sensitively; an empty array means the gate has no whitelist.
+  required:
+    - id
+    - name
+    - attr
+    - entries
+  additionalProperties: false
+  description: A gate's whitelist — the always-first allowlist that admits the listed identities before any targeting rule or rollout runs. Backed by the pinned `whitelist` entry at the head of the gate's `stack`, so it is the same list the dashboard's Whitelist block edits.
+SetGateWhitelistRequest:
+  type: object
+  properties:
+    attr:
+      anyOf:
+        - $ref: "#/GateWhitelistAttr"
+      description: Identity attribute to match on. Defaults to the whitelist's current attribute, or `email` when the gate has no whitelist yet.
+    entries:
+      type: array
+      items:
+        type: string
+        minLength: 1
+      description: The complete whitelist after the call. Pass `[]` to remove the whitelist from the gate entirely.
+  required:
+    - entries
+  additionalProperties: false
+  description: Body for `PUT /api/admin/gates/{id}/whitelist`. Replaces the whole list — idempotent, and the only call that can switch `attr` or clear the whitelist.
+AddToGateWhitelistRequest:
+  type: object
+  properties:
+    attr:
+      anyOf:
+        - $ref: "#/GateWhitelistAttr"
+      description: Identity attribute to match on. Only honoured when the gate has no whitelist yet (this call creates it); passing an attribute that disagrees with an existing whitelist is a 409 rather than a silent re-key of the entries already there.
+    entries:
+      type: array
+      minItems: 1
+      items:
+        type: string
+        minLength: 1
+      description: Identities to admit. Already-listed entries are skipped, so the call is idempotent.
+  required:
+    - entries
+  additionalProperties: false
+  description: Body for `POST /api/admin/gates/{id}/whitelist`. Adds entries to the whitelist, creating it if the gate doesn't have one.
+RemoveFromGateWhitelistRequest:
+  type: object
+  properties:
+    entries:
+      type: array
+      minItems: 1
+      items:
+        type: string
+        minLength: 1
+      description: Identities to stop admitting. Entries that aren't listed are skipped, so the call is idempotent.
+  required:
+    - entries
+  additionalProperties: false
+  description: "Body for `DELETE /api/admin/gates/{id}/whitelist`. Removes entries from the whitelist. Removing the last entry leaves an empty whitelist in place — use `PUT` with `entries: []` to drop the block itself."
+GetGateWhitelistResponse:
+  $ref: "#/GateWhitelist"
+SetGateWhitelistResponse:
+  $ref: "#/GateWhitelist"
+AddToGateWhitelistResponse:
+  $ref: "#/GateWhitelist"
+RemoveFromGateWhitelistResponse:
+  $ref: "#/GateWhitelist"

package/spec/components/schemas/keys.yaml

@@ -60,6 +60,11 @@ KeyRecord:
         - type: string
         - type: "null"
       description: Human label for the key. `null` for unnamed dashboard mints; programmatic mints auto-name themselves.
+    description:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Free-text note recording what the key is for (the service that holds it, the rotation owner, the ticket it was minted under). Display only — `null` unless someone set it via `PATCH /api/admin/keys/{id}`.
     scopes:
       anyOf:
         - type: array
@@ -81,9 +86,34 @@ KeyRecord:
     - expires_at
     - created_by_email
     - name
+    - description
     - scopes
     - last4
   additionalProperties: false
+UpdateKeyRequest:
+  type: object
+  description: |-
+    Body for `PATCH /api/admin/keys/{id}`. Only the key's **label** is editable — `name` and `description`.
+
+    Everything that gives a key its authority (`type`, `env`, `scopes`, `expires_at`) is fixed at mint: those are the isolation boundary the worker derives the read env and permissions from, so changing them would silently re-point a credential that is already deployed. Rotate instead — mint a replacement and revoke the old key.
+
+    Omitted fields are left untouched; send `null` to clear one.
+  properties:
+    name:
+      anyOf:
+        - type: string
+          minLength: 1
+          maxLength: 160
+        - type: "null"
+      description: New human label, or `null` to clear it. Same 160-char budget as create — provenance labels are composed, not typed.
+    description:
+      anyOf:
+        - type: string
+          minLength: 1
+          maxLength: 500
+        - type: "null"
+      description: New free-text note, or `null` to clear it.
+  additionalProperties: false
 CreateKeyRequest:
   type: object
   description: |-
@@ -102,8 +132,8 @@ CreateKeyRequest:
     name:
       type: string
       minLength: 1
-      maxLength: 80
-      description: Optional human label. Programmatic (API) mints that omit it get an auto-generated descriptive name; dashboard mints may leave it blank.
+      maxLength: 160
+      description: "Optional human label. Programmatic (API) mints that omit it get an auto-generated descriptive name; dashboard mints may leave it blank. The cap is generous because provenance labels are composed, not typed — `shipeasy setup` mints keys named with the stack, package, date, and operator that produced them, which does not fit in a one-line-input budget."
     scopes:
       type: array
       items:

package/spec/components/schemas/killswitches.yaml

@@ -343,3 +343,67 @@ SetKillswitchValueResponse:
     - version
     - published
   additionalProperties: false
+ToggleKillswitchRequest:
+  type: object
+  properties:
+    switchKey:
+      anyOf:
+        - type: string
+          maxLength: 64
+          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$
+        - type: "null"
+      description: Which target to flip. Omit (or `null`) to flip the killswitch's own flat `value`; name a switch key to flip that nested sub-switch instead, creating the entry if it doesn't exist yet.
+    value:
+      anyOf:
+        - type: boolean
+        - type: "null"
+      description: The value to publish. Omit (or `null`) to flip whatever is stored now — read-modify-write in one call. Pass an explicit `true`/`false` to make the call idempotent, so a retry can't undo the first attempt.
+    env:
+      anyOf:
+        - $ref: ./common.yaml#/Env
+      description: Environment to publish on. Defaults to `prod` — the environment an incident response means when it says "kill it".
+  additionalProperties: false
+  description: |-
+    Body for `POST /api/admin/killswitches/{id}/toggle`. Every field is optional, so the four useful calls read as one method with a widening argument list:
+
+    - `{}` — flip the flat value on prod.
+    - `{ "switchKey": "eu_region" }` — flip that sub-switch on prod.
+    - `{ "switchKey": "eu_region", "value": true }` — set that sub-switch on prod, idempotently.
+    - `{ "switchKey": "eu_region", "value": true, "env": "staging" }` — the same, on a chosen env.
+ToggleKillswitchResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Resolved killswitch id.
+    env:
+      $ref: ./common.yaml#/Env
+    switchKey:
+      anyOf:
+        - type: string
+          maxLength: 64
+          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$
+        - type: "null"
+      description: The sub-switch that was flipped, or `null` when the flat `value` was.
+    previous:
+      type: boolean
+      description: The value that was in effect before this call. Equal to `value` when an idempotent `value` matched what was already stored.
+    value:
+      type: boolean
+      description: The value now in effect on `env`.
+    version:
+      type: integer
+      minimum: -9007199254740991
+      maximum: 9007199254740991
+      description: Newly published version on `env`.
+    published:
+      $ref: ./common.yaml#/KillswitchValue
+  required:
+    - id
+    - env
+    - switchKey
+    - previous
+    - value
+    - version
+    - published
+  additionalProperties: false