@sponson/adapters 0.4.0 → 0.6.0

package/recipes/posthog.yaml

@@ -0,0 +1,127 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# PostHog private API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: posthog
+title: PostHog
+category: flags
+verified_on: "2026-10-11"
+docs:
+  - title: Private API (hosts, personal API keys)
+    url: https://posthog.com/docs/api
+  - title: Feature flags API
+    url: https://posthog.com/docs/api/feature-flags
+  - title: OpenAPI schema (FeatureFlag, PersonalAPIKeyAuth)
+    url: https://us.posthog.com/api/schema/?format=json
+  - title: Feature flag serializer (filters validation and merge)
+    url: https://github.com/PostHog/posthog/blob/master/products/feature_flags/backend/api/feature_flag.py
+  - title: Feature flag filters schema (condition groups)
+    url: https://github.com/PostHog/posthog/blob/master/products/feature_flags/backend/api/filters_schema.py
+api:
+  base_url: https://us.posthog.com
+  base_url_env: POSTHOG_API_URL
+  auth: { bearer_env: POSTHOG_PERSONAL_API_KEY }
+detect:
+  deps: [posthog-js, posthog-node, posthog-react-native]
+  env: ["POSTHOG_*"]
+  starter:
+    - op: release_condition
+      values: { property: $host }
+  where:
+    project_id: "PostHog → Settings → Project → Project ID"
+    flag_id: "PostHog → Feature flags → your flag: the number in its URL"
+    value: "the preview's host name (with `property: $host`)"
+assumptions:
+  - id: PH1
+    verified: true
+    text: "The private API is at `https://us.posthog.com` (US cloud) or `https://eu.posthog.com` (EU cloud; set `base_url`), authenticated with a personal API key as `Authorization: Bearer`, with the `feature_flag:read` and `feature_flag:write` scopes."
+    source: https://posthog.com/docs/api
+  - id: PH2
+    verified: true
+    text: "`GET /api/projects/{project_id}/feature_flags/{id}/` (trailing slash) answers the flag bare, with its release conditions in `filters.groups`; `PATCH` on the same path updates it and answers it bare."
+    source: https://us.posthog.com/api/schema/?format=json
+  - id: PH3
+    verified: true
+    text: "A condition group is `{ properties: [{ key, type, operator, value }], rollout_percentage, variant }`; `exact` takes a list of values. Groups have no id, so the group is identified by the first value of its first property (the preview host)."
+    source: https://github.com/PostHog/posthog/blob/master/products/feature_flags/backend/api/filters_schema.py
+  - id: PH4
+    verified: true
+    text: "A PATCH of `filters` merges top-level keys into the stored filters (`{**stored_filters, **filters}`): sending `{ filters: { groups } }` replaces the groups and keeps `multivariate`, `payloads` and the rest. This is in the serializer's source, not the docs."
+    source: https://github.com/PostHog/posthog/blob/master/products/feature_flags/backend/api/feature_flag.py
+  - id: PH5
+    verified: false
+    text: "Self-hosted or older PostHog versions merge `filters` the same way (the merge arrived with 2026's validation work). On a version that replaces `filters` whole, every write would drop the flag's variants and payloads: check before pointing the recipe at one."
+  - id: PH6
+    verified: false
+    text: "A group is read back as written (the serializer drops unknown keys and adds none to the declared ones), so the compared `properties`, `rollout_percentage` and `variant` do not show as changed on every plan."
+  - id: PH7
+    verified: true
+    text: "A flag under an approval policy answers a PATCH with 409 (`approval_required` or `change_request_pending`); the apply then fails with PROVIDER_CONFLICT rather than waiting for the approval."
+    source: https://github.com/PostHog/posthog/blob/master/products/approvals/backend/decorators.py
+ops:
+  release_condition:
+    kind: list_item
+    title: Flag release condition
+    summary: "A release condition (condition group) on an existing feature flag that matches the preview, such as `$host exact [pr-42.preview.example.com]` at 100%. Groups are OR'd; the flag's other groups, variants and payloads are left as they are. A console edit of its properties, rollout or variant is drift. Destroy removes the group (with the last group gone, the flag matches no one)."
+    covers: [posthog-release-condition]
+    params:
+      project_id:
+        type: string
+        required: true
+        pattern: "^[0-9]+$"
+        description: The project's numeric id (Project settings).
+        example: "12345"
+      flag_id:
+        type: string
+        required: true
+        pattern: "^[0-9]+$"
+        description: The flag's numeric id (in the flag's URL), not its key.
+        example: "678"
+      property:
+        type: string
+        required: true
+        description: The property the condition tests. It must be known when the flag is evaluated (a person property, or one passed with the evaluation).
+        example: $host
+      property_type:
+        type: string
+        default: person
+        enum: [person, group]
+        description: Whether `property` is a person or a group property.
+      operator:
+        type: string
+        default: exact
+        enum: [exact, is_not, icontains, regex]
+        description: How the property is compared with `value`.
+      value:
+        type: string
+        required: true
+        description: The value that matches the preview (such as its host); it identifies the condition on the flag.
+        example: "${ctx.scope}.preview.example.com"
+      rollout_percentage:
+        type: integer
+        default: 100
+        description: The share of matching users the flag is on for (0–100).
+      variant:
+        type: string
+        description: For a multivariate flag, the variant the condition serves.
+    http:
+      parent: { path: "/api/projects/{project_id}/feature_flags/{flag_id}/", method: PATCH }
+      list_path: /filters/groups
+      key_field: /properties/0/value/0
+      item:
+        properties:
+          - key: { param: property }
+            type: { param: property_type }
+            operator: { param: operator }
+            value: [{ param: value }]
+        rollout_percentage: { param: rollout_percentage }
+        variant: { param: variant }
+    sim:
+      objects:
+        "/api/projects/{project_id}/feature_flags/{flag_id}":
+          id: 678
+          key: new-checkout
+          filters:
+            groups: [{ properties: [], rollout_percentage: 0 }]
+            multivariate: null
+            payloads: {}
+    live:
+      params: { project_id: SPONSON_LIVE_POSTHOG_PROJECT_ID, flag_id: SPONSON_LIVE_POSTHOG_FLAG_ID }

package/recipes/postmark.yaml

@@ -0,0 +1,105 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Postmark Account API recipes (account token). The Server API, which takes a server's own token, is
+# postmark_server.yaml. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: postmark
+title: Postmark (Account API)
+category: email
+verified_on: "2026-10-11"
+docs:
+  - title: Servers API
+    url: https://postmarkapp.com/developer/api/servers-api
+  - title: API overview (authentication)
+    url: https://postmarkapp.com/developer/api/overview
+api:
+  base_url: https://api.postmarkapp.com
+  base_url_env: POSTMARK_API_URL
+  auth: { header: X-Postmark-Account-Token, value_env: POSTMARK_ACCOUNT_TOKEN }
+detect:
+  deps: [postmark]
+  env: ["POSTMARK_*"]
+  starter:
+    - op: server
+      values: { name: "sponson-${ctx.env}-${ctx.scope}" }
+assumptions:
+  - id: PM1
+    verified: true
+    text: "The Servers API authenticates with the account token in `X-Postmark-Account-Token` (account owner only) and takes and answers JSON."
+    source: https://postmarkapp.com/developer/api/servers-api
+  - id: PM2
+    verified: true
+    text: "`POST /servers` creates a server from `Name` (required), `Color`, `DeliveryType` (`Live` or `Sandbox`, fixed after creation), `InboundHookUrl`, `TrackOpens`, `TrackLinks` and more, answering the server with its integer `ID`, its settings and `ApiTokens` (the server's tokens)."
+    source: https://postmarkapp.com/developer/api/servers-api
+  - id: PM3
+    verified: true
+    text: "`GET /servers?count=&offset=&name=` answers `{ TotalCount, Servers: [...] }`; `name` is a substring search (`MyServer` also matches `MyServer Production`), so the recipe matches the exact `Name` among the results."
+    source: https://postmarkapp.com/developer/api/servers-api
+  - id: PM4
+    verified: true
+    text: "`PUT /servers/{serverid}` changes the settings sent (everything but `DeliveryType`); `GET /servers/{serverid}` answers the server with its `ApiTokens`, so the server token stays readable."
+    source: https://postmarkapp.com/developer/api/servers-api
+  - id: PM5
+    verified: true
+    text: "`DELETE /servers/{serverid}` removes a server, but is not enabled for every account: where Postmark support has not enabled it, destroy fails and the line needs `destroy: keep`."
+    source: https://postmarkapp.com/developer/api/servers-api
+  - id: PM6
+    verified: false
+    text: "Server names are unique in the account (a second create with the same name is refused), and an account has fewer than 500 servers, so the first page of `count=500` holds the one `find` looks for."
+  - id: PM7
+    verified: false
+    text: "`Color`, `TrackOpens`, `TrackLinks` and `InboundHookUrl` are answered as sent (`InboundHookUrl` empty when unset), so they compare without drift."
+ops:
+  server:
+    kind: resource
+    title: Server
+    summary: "A Postmark server per environment, such as `sponson-preview-pr-42`, with its inbound webhook URL and tracking settings. Its token is a sensitive output for the app's environment (`{ from: <line>.server_token }`). Located by its name; a console edit of its color, tracking or inbound hook URL is drift. Its webhooks: `postmark_server.webhook` with `credential: { from: <this line>.server_token }`."
+    covers: [postmark-server-webhook]
+    params:
+      name:
+        type: string
+        required: true
+        description: The server's name, unique in the account (PM6); its identity.
+        example: "sponson-${ctx.env}-${ctx.scope}"
+      color:
+        type: string
+        default: Blue
+        enum: [Purple, Blue, Turquoise, Green, Red, Yellow, Grey, Orange]
+        description: The server's color in the Postmark dashboard.
+      delivery_type:
+        type: string
+        default: Sandbox
+        enum: [Live, Sandbox]
+        description: "`Sandbox` accepts mail without delivering it; fixed once the server exists (sent on create only)."
+      inbound_hook_url:
+        type: string
+        default: ""
+        description: The URL inbound mail is posted to (empty for none).
+        example: "https://${ctx.scope}.preview.example.com/api/postmark/inbound"
+      track_opens:
+        type: boolean
+        default: false
+        description: Track opens of outbound mail.
+      track_links:
+        type: string
+        default: None
+        enum: [None, HtmlAndText, HtmlOnly, TextOnly]
+        description: Track link clicks of outbound mail.
+    http:
+      find:
+        path: "/servers?count=500&offset=0&name={name}"
+        list_path: /Servers
+        match: { Name: { param: name } }
+      create:
+        path: /servers
+        body: { DeliveryType: { param: delivery_type } }
+      update: { method: PUT, path: "/servers/{id}" }
+      delete: { path: "/servers/{id}" }
+      id_path: /ID
+      fields:
+        Color: { param: color }
+        InboundHookUrl: { param: inbound_hook_url }
+        TrackOpens: { param: track_opens }
+        TrackLinks: { param: track_links }
+      outputs:
+        server_token: { path: /ApiTokens/0, sensitive: true }
+    sim:
+      numeric_ids: true

package/recipes/postmark_server.yaml

@@ -0,0 +1,93 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Postmark Server API recipes (one server's token). The Account API is postmark.yaml. Format and checklist:
+# docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: postmark_server
+title: Postmark (Server API)
+category: email
+verified_on: "2026-10-11"
+docs:
+  - title: Webhooks API
+    url: https://postmarkapp.com/developer/api/webhooks-api
+  - title: API overview (authentication)
+    url: https://postmarkapp.com/developer/api/overview
+api:
+  base_url: https://api.postmarkapp.com
+  base_url_env: POSTMARK_API_URL
+  auth: { header: X-Postmark-Server-Token, value_env: POSTMARK_SERVER_TOKEN }
+assumptions:
+  - id: PS1
+    verified: true
+    text: "The Webhooks API authenticates with a server's token in `X-Postmark-Server-Token`, so it manages the webhooks of that one server."
+    source: https://postmarkapp.com/developer/api/webhooks-api
+  - id: PS2
+    verified: true
+    text: "`POST /webhooks` creates a webhook from `Url` (required), `MessageStream` (default `outbound`), `HttpAuth`, `HttpHeaders` and `Triggers` (`Open { Enabled, PostFirstOpenOnly }`, `Click`, `Delivery`, `Bounce { Enabled, IncludeContent }`, `SpamComplaint { Enabled, IncludeContent }`, `SubscriptionChange`, each with `Enabled`), answering the webhook with its integer `ID`."
+    source: https://postmarkapp.com/developer/api/webhooks-api
+  - id: PS3
+    verified: true
+    text: "`GET /webhooks` (optionally `?MessageStream=`) answers `{ Webhooks: [...] }` with each webhook's `ID`, `Url`, `MessageStream` and `Triggers`."
+    source: https://postmarkapp.com/developer/api/webhooks-api
+  - id: PS4
+    verified: true
+    text: "`PUT /webhooks/{Id}` changes `Url`, `HttpAuth`, `HttpHeaders` and `Triggers` (not `MessageStream`), re-verifying the endpoint when the URL or the triggers change; `DELETE /webhooks/{Id}` removes it."
+    source: https://postmarkapp.com/developer/api/webhooks-api
+  - id: PS5
+    verified: true
+    text: "Postmark tests the endpoint when a webhook is created; `Verify: false` saves it without the test (a preview that is not deployed yet would fail it)."
+    source: https://postmarkapp.com/developer/api/webhooks-api
+  - id: PS6
+    verified: false
+    text: "A URL identifies one webhook of the server (two webhooks with the same URL, on different streams, make `find` refuse with PARAM_INVALID), and every trigger's `Enabled` is answered as a boolean even when it was not sent."
+  - id: PS7
+    verified: false
+    text: "`PostFirstOpenOnly` and `IncludeContent` are left at Postmark's defaults; only which events are delivered is compared."
+  - id: PS8
+    verified: false
+    text: "A server's webhooks belong to it: deleting the server (`DELETE /servers/{id}`, Account API) removes them, so a webhook line authenticated with the server's own token can leave its destroy to the server's line."
+ops:
+  webhook:
+    kind: resource
+    title: Webhook of a server
+    summary: "A webhook of one Postmark server delivering to an environment's URL, such as the preview's `/api/postmark` handler, with the events it enables. Located by its URL; a console edit of an event's `Enabled` is drift. The server is the one whose token is in `POSTMARK_SERVER_TOKEN` (a shared staging server), or, for a server the same plan creates per environment (`postmark.server`), the line says `credential: { from: <server line>.server_token }` and `destroy: keep`: deleting the server removes its webhooks (PS8)."
+    covers: [postmark-server-webhook]
+    params:
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: The URL events are posted to; its identity (PS6).
+        example: "https://${ctx.scope}.preview.example.com/api/postmark"
+      message_stream:
+        type: string
+        default: outbound
+        description: The message stream whose events are delivered (sent on create only).
+      verify:
+        type: boolean
+        default: false
+        description: Have Postmark test the URL when the webhook is created (PS5).
+      delivery: { type: boolean, default: true, description: Deliver `Delivery` events. }
+      bounce: { type: boolean, default: true, description: Deliver `Bounce` events. }
+      spam_complaint: { type: boolean, default: true, description: Deliver `SpamComplaint` events. }
+      open: { type: boolean, default: false, description: Deliver `Open` events. }
+      click: { type: boolean, default: false, description: Deliver `Click` events. }
+      subscription_change: { type: boolean, default: false, description: Deliver `SubscriptionChange` events. }
+    http:
+      find:
+        path: /webhooks
+        list_path: /Webhooks
+        match: { Url: { param: url } }
+      create:
+        path: /webhooks
+        body: { MessageStream: { param: message_stream }, Verify: { param: verify } }
+      update: { method: PUT, path: "/webhooks/{id}" }
+      delete: { path: "/webhooks/{id}" }
+      id_path: /ID
+      fields:
+        /Triggers/Delivery/Enabled: { param: delivery }
+        /Triggers/Bounce/Enabled: { param: bounce }
+        /Triggers/SpamComplaint/Enabled: { param: spam_complaint }
+        /Triggers/Open/Enabled: { param: open }
+        /Triggers/Click/Enabled: { param: click }
+        /Triggers/SubscriptionChange/Enabled: { param: subscription_change }
+    sim:
+      numeric_ids: true

package/recipes/prisma.yaml

@@ -0,0 +1,150 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Prisma Postgres Management API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: prisma
+title: Prisma Postgres
+category: databases
+verified_on: "2026-10-11"
+docs:
+  - title: Management API OpenAPI document
+    url: https://api.prisma.io/v1/doc
+  - title: Management API guide (base URL, service tokens)
+    url: https://www.prisma.io/docs/guides/management-api-basic
+  - title: Connecting to your database (connection strings)
+    url: https://www.prisma.io/docs/postgres/database/connecting-to-your-database
+api:
+  base_url: https://api.prisma.io/v1
+  base_url_env: PRISMA_API_URL
+  auth: { bearer_env: PRISMA_SERVICE_TOKEN }
+detect:
+  deps: ["@prisma/ppg"]
+  db_hosts: [.prisma.io, .prisma-data.net]
+  starter:
+    - op: database
+      values: { name: "app-${ctx.scope}" }
+  where:
+    project_id: "Prisma Console → your project → Settings → Project ID"
+assumptions:
+  - id: PP1
+    verified: true
+    text: "The Management API at `https://api.prisma.io/v1` authenticates with a workspace service token as `Authorization: Bearer`; Prisma's guide keeps it in `PRISMA_SERVICE_TOKEN`."
+    source: https://www.prisma.io/docs/guides/management-api-basic
+  - id: PP2
+    verified: true
+    text: "Answers are enveloped: one object as `{ data: {…} }`, a list as `{ data: [...], pagination: { nextCursor, hasMore } }`, paged with `?cursor=`."
+    source: https://api.prisma.io/v1/doc
+  - id: PP3
+    verified: true
+    text: "`POST /v1/projects/{projectId}/databases` with `{ name, region, source? }` creates a database (201); `source: { type: database, databaseId }` copies an existing one. It answers the database with `id`, `name`, `status` (`provisioning` or `ready`) and `connections[]`."
+    source: https://api.prisma.io/v1/doc
+  - id: PP4
+    verified: true
+    text: "`GET /v1/projects/{projectId}/databases` lists the project's databases with `id` and `name`; it has no name filter, so the list is searched page by page."
+    source: https://api.prisma.io/v1/doc
+  - id: PP5
+    verified: false
+    text: "Database names are not unique (the project-scoped create documents no 409), so two databases with one name make `find.match` ambiguous, which is refused with PARAM_INVALID rather than guessed. Sponson never creates a second one: it looks the name up before every create."
+    source: https://api.prisma.io/v1/doc
+  - id: PP6
+    verified: true
+    text: "`GET /v1/databases/{databaseId}` answers the database (404 when it does not exist); `DELETE` on the same path deletes it (204; 404 when gone; 403 for a project's default database)."
+    source: https://api.prisma.io/v1/doc
+  - id: PP7
+    verified: false
+    text: "The connection strings (`connections[0].endpoints.direct.connectionString`, and `.pooled` when there is a pooled endpoint) are in the create answer only: list and get answer the endpoints' host and port without them. So they are once-only outputs (ADR 0018), and a create whose answer was lost leaves dependents to be refused until the database is recreated. Inferred from the schemas; not stated in the docs."
+    source: https://api.prisma.io/v1/doc
+  - id: PP8
+    verified: false
+    text: "`connections[0]` is the database's default connection, present in every create answer."
+    source: https://api.prisma.io/v1/doc
+  - id: PP9
+    verified: false
+    text: "A database answered with `status: provisioning` accepts connections within seconds; nothing waits for `ready` (the API has no readiness the http adapter can poll), so a dependent deployment that starts at once may see connection errors for that long."
+    source: https://api.prisma.io/v1/doc
+  - id: PP10
+    verified: true
+    text: "Connection strings have the form `postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require` (direct) and `postgres://USER:PASSWORD@pooled.db.prisma.io:5432/?sslmode=require` (pooled)."
+    source: https://www.prisma.io/docs/postgres/database/connecting-to-your-database
+ops:
+  database:
+    kind: resource
+    title: Database
+    summary: "An empty Postgres database per scope in a Prisma Postgres project, such as `app-pr-42`. Its connection strings exist only in the create answer, so they are once-only outputs: reference them from the line that needs them (an env var) in the same plan. Located by name; only its existence is compared for drift; destroy deletes it and its data."
+    covers: [prisma-postgres-database]
+    params:
+      project_id:
+        type: string
+        required: true
+        description: The project's id.
+        example: proj_cm1a2b3c4d5e6f7g8h9
+      name:
+        type: string
+        required: true
+        description: The database's name.
+        example: "app-${ctx.scope}"
+      region:
+        type: string
+        default: us-east-1
+        enum: [us-east-1, us-west-1, eu-west-3, eu-central-1, ap-northeast-1, ap-southeast-1]
+        description: Where it runs.
+    http:
+      find:
+        path: "/projects/{project_id}/databases"
+        list_path: /data
+        next: /pagination/nextCursor
+        match: { name: { param: name } }
+      read: { path: "/databases/{id}" }
+      create:
+        path: "/projects/{project_id}/databases"
+        body: { region: { param: region } }
+      item_path: /data
+      outputs:
+        status: /status
+        direct_url: { path: /connections/0/endpoints/direct/connectionString, sensitive: true, once: true }
+        pooled_url: { path: /connections/0/endpoints/pooled/connectionString, sensitive: true, once: true }
+    live:
+      params: { project_id: SPONSON_LIVE_PRISMA_PROJECT_ID }
+  database_copy:
+    kind: resource
+    title: Database copied from another
+    summary: "A Postgres database per scope copied from an existing one (`source: { type: database }`), such as `app-pr-42` with the data of `app`. Otherwise like `prisma.database`: once-only connection strings, existence-only drift, destroy deletes the copy (never the source)."
+    covers: [prisma-postgres-database]
+    params:
+      project_id:
+        type: string
+        required: true
+        description: The project's id.
+        example: proj_cm1a2b3c4d5e6f7g8h9
+      name:
+        type: string
+        required: true
+        description: The new database's name.
+        example: "app-${ctx.scope}"
+      source_database_id:
+        type: string
+        required: true
+        description: The id of the database to copy.
+        example: db_cm9z8y7x6w5v4u3t2s1
+      region:
+        type: string
+        default: us-east-1
+        enum: [us-east-1, us-west-1, eu-west-3, eu-central-1, ap-northeast-1, ap-southeast-1]
+        description: Where it runs.
+    http:
+      find:
+        path: "/projects/{project_id}/databases"
+        list_path: /data
+        next: /pagination/nextCursor
+        match: { name: { param: name } }
+      read: { path: "/databases/{id}" }
+      create:
+        path: "/projects/{project_id}/databases"
+        body:
+          region: { param: region }
+          source: { type: database, databaseId: { param: source_database_id } }
+      item_path: /data
+      outputs:
+        status: /status
+        direct_url: { path: /connections/0/endpoints/direct/connectionString, sensitive: true, once: true }
+        pooled_url: { path: /connections/0/endpoints/pooled/connectionString, sensitive: true, once: true }
+    live:
+      params: { project_id: SPONSON_LIVE_PRISMA_PROJECT_ID, source_database_id: SPONSON_LIVE_PRISMA_DATABASE_ID }

package/recipes/qstash.yaml

@@ -0,0 +1,134 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Upstash QStash recipes (its own API and token; Upstash Redis is recipes/upstash.yaml).
+# Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: qstash
+title: Upstash QStash
+category: queues
+verified_on: "2026-10-11"
+docs:
+  - title: Authentication
+    url: https://upstash.com/docs/qstash/api/authentication
+  - title: Create a schedule
+    url: https://upstash.com/docs/qstash/api-reference/schedules/create-a-schedule
+  - title: Get a schedule
+    url: https://upstash.com/docs/qstash/api-reference/schedules/get-a-schedule
+  - title: Delete a schedule
+    url: https://upstash.com/docs/qstash/api-reference/schedules/delete-a-schedule
+  - title: API examples (raw destination URL in the path)
+    url: https://upstash.com/docs/qstash/overall/apiexamples
+  - title: Multi-region (base URLs, tokens)
+    url: https://upstash.com/docs/qstash/howto/multi-region
+api:
+  base_url: https://qstash.upstash.io
+  base_url_env: QSTASH_API_URL
+  auth: { bearer_env: QSTASH_TOKEN }
+detect:
+  deps: ["@upstash/qstash"]
+  env: ["QSTASH_*"]
+  starter:
+    - op: schedule
+      values: { schedule_id: "cron-${ctx.scope}" }
+  where:
+    destination: "the preview's endpoint the schedule calls: its URL plus the path (a `{ from }` reference cannot carry a path)"
+assumptions:
+  - id: QS1
+    verified: true
+    text: "Requests authenticate with the QStash token as `Authorization: Bearer`; the SDKs read it from `QSTASH_TOKEN`."
+    source: https://upstash.com/docs/qstash/api/authentication
+  - id: QS2
+    verified: true
+    text: "Each region (`qstash.upstash.io` = EU, `qstash-us-east-1.upstash.io`) has its own token and its own schedules; the default here is the EU URL, and a US account overrides `base_url` in its block."
+    source: https://upstash.com/docs/qstash/howto/multi-region
+  - id: QS3
+    verified: true
+    text: "`POST /v2/schedules/{destination}` creates a schedule: the cron in `Upstash-Cron`, the method used to call the destination in `Upstash-Method` (default POST), the request body as the message delivered on every run. It answers `{ scheduleId }`."
+    source: https://upstash.com/docs/qstash/api-reference/schedules/create-a-schedule
+  - id: QS4
+    verified: true
+    text: "With `Upstash-Schedule-Id`, a schedule with that id is updated with the new settings if it exists (an upsert): the id is the client's, the read path names it, and the same request is both create and update."
+    source: https://upstash.com/docs/qstash/api-reference/schedules/create-a-schedule
+  - id: QS5
+    verified: true
+    text: "The official example writes the destination URL in the path as it is (`/v2/schedules/https://example.com`), hence the `{+destination}` placeholder."
+    source: https://upstash.com/docs/qstash/overall/apiexamples
+  - id: QS6
+    verified: false
+    text: "A destination URL with a query string arrives intact with its `?` escaped as `%3F` (a raw `?` would end the path); not documented."
+  - id: QS7
+    verified: true
+    text: "`GET /v2/schedules/{scheduleId}` answers the schedule bare with `scheduleId`, `cron`, `destination`, `method` and `body`, and 404 when there is none; `DELETE` on the same path removes it."
+    source: https://upstash.com/docs/qstash/api-reference/schedules/get-a-schedule
+  - id: QS8
+    verified: false
+    text: "Deleting a schedule that is already gone answers 404 (only 200 is documented), which destroy treats as done."
+    source: https://upstash.com/docs/qstash/api-reference/schedules/delete-a-schedule
+  - id: QS9
+    verified: true
+    text: "Schedule ids are alphanumerics, hyphens, periods and underscores (400 otherwise); a cron may carry a `CRON_TZ=<zone>` prefix and runs at most once a minute."
+    source: https://upstash.com/docs/qstash/api-reference/schedules/create-a-schedule
+  - id: QS10
+    verified: false
+    text: "`GET` returns `cron`, `destination` and `method` exactly as they were sent (the cron string unnormalised), so comparing them is not drift on every plan."
+    source: https://upstash.com/docs/qstash/api-reference/schedules/get-a-schedule
+ops:
+  schedule:
+    kind: resource
+    title: Schedule
+    summary: "A cron schedule that calls a preview's URL, such as `/api/cron` of `pr-42`, under a schedule id per scope. Created and updated by the same upsert (QS4); a console edit of its cron, destination or method is drift; destroy deletes it. The message body is sent on create and update but not compared."
+    covers: [qstash-schedule]
+    params:
+      schedule_id:
+        type: string
+        required: true
+        pattern: "^[A-Za-z0-9._-]+$"
+        description: The schedule's id, chosen by the plan (one per scope).
+        example: "cron-${ctx.scope}"
+      destination:
+        type: string
+        required: true
+        pattern: "^https?://"
+        description: The URL the schedule calls.
+        example: "https://${ctx.scope}.preview.example.com/api/cron"
+      cron:
+        type: string
+        required: true
+        description: "The cron expression, optionally prefixed `CRON_TZ=<zone> `."
+        example: "*/15 * * * *"
+      method:
+        type: string
+        default: POST
+        enum: [GET, POST, PUT, PATCH, DELETE]
+        description: The HTTP method used to call the destination.
+      body:
+        type: map
+        description: The JSON message delivered on every run (sent, not compared).
+    http:
+      read: { path: "/v2/schedules/{schedule_id}" }
+      create:
+        path: "/v2/schedules/{+destination}"
+        headers:
+          Upstash-Schedule-Id: { param: schedule_id }
+          Upstash-Cron: { param: cron }
+          Upstash-Method: { param: method }
+        send_fields: false
+        body: { param: body }
+      update:
+        method: POST
+        path: "/v2/schedules/{+destination}"
+        headers:
+          Upstash-Schedule-Id: { param: schedule_id }
+          Upstash-Cron: { param: cron }
+          Upstash-Method: { param: method }
+        send_fields: false
+        body: { param: body }
+      id_path: /scheduleId
+      fields:
+        cron: { param: cron }
+        destination: { param: destination }
+        method: { param: method }
+    sim:
+      collection: /v2/schedules
+      header_fields: { upstash-schedule-id: scheduleId, upstash-cron: cron, upstash-method: method }
+      suffix_field: destination
+    live:
+      params: { destination: SPONSON_LIVE_QSTASH_DESTINATION }