@sponson/adapters 0.0.0-stage → 0.5.0

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 }

package/recipes/railway.yaml

@@ -0,0 +1,130 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Railway public GraphQL API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: railway
+title: Railway
+category: deploy
+verified_on: "2026-10-11"
+docs:
+  - title: Public API (endpoint, tokens, errors)
+    url: https://docs.railway.com/reference/public-api
+  - title: Manage Variables with the Public API
+    url: https://docs.railway.com/guides/manage-variables
+  - title: Environments (PR environments)
+    url: https://docs.railway.com/reference/environments
+  - title: CLI (RAILWAY_TOKEN and RAILWAY_API_TOKEN)
+    url: https://docs.railway.com/guides/cli
+  - title: railwayapp/cli GraphQL schema
+    url: https://github.com/railwayapp/cli/blob/master/src/gql/schema.json
+api:
+  base_url: https://backboard.railway.com/graphql/v2
+  base_url_env: RAILWAY_API_URL
+  auth: { bearer_env: RAILWAY_API_TOKEN }
+detect:
+  env: ["RAILWAY_*"]
+  files: [railway.json, railway.toml]
+  starter:
+    - op: variable
+  where:
+    project_id: "Railway → your project → Settings → Project ID, or `railway status --json`"
+    environment_id: "the pull request environment Railway created: its Settings, or `railway environment`"
+assumptions:
+  - id: RY1
+    verified: true
+    text: "The public API is one GraphQL endpoint, `https://backboard.railway.com/graphql/v2`; account, workspace and OAuth tokens are sent as `Authorization: Bearer <token>`, project tokens in `Project-Access-Token` instead (a project token therefore needs a hand-written block with `auth: { header: Project-Access-Token, value_env: RAILWAY_TOKEN }`)."
+    source: https://docs.railway.com/reference/public-api
+  - id: RY2
+    verified: true
+    text: "The Railway CLI reads an account or workspace token from `RAILWAY_API_TOKEN` and a project token from `RAILWAY_TOKEN`, so the bearer credential of this recipe is `RAILWAY_API_TOKEN`."
+    source: https://docs.railway.com/guides/cli
+  - id: RY3
+    verified: true
+    text: "Failures may be HTTP 200 with an `errors` array (a denied query among them); 400 is a parse or validation failure, 429 a rate limit with `Retry-After`. Queries are safe to retry; a mutation only when no answer arrived."
+    source: https://docs.railway.com/reference/public-api
+  - id: RY4
+    verified: true
+    text: "`variables(projectId, environmentId, serviceId?, unrendered?)` answers the variables of a service in an environment (without `serviceId`, the environment's shared variables) as a map of name to value; `unrendered: true` answers references such as `${{Postgres.DATABASE_URL}}` as written instead of resolved, so a value is compared as it was set."
+    source: https://docs.railway.com/guides/manage-variables
+  - id: RY5
+    verified: true
+    text: "`variableUpsert(input: { projectId, environmentId, serviceId?, name, value, skipDeploys? })` creates or replaces one variable (without `serviceId`, a shared variable); by default it triggers a redeploy of the service (`skipDeploys` defaults to false)."
+    source: https://docs.railway.com/guides/manage-variables
+  - id: RY6
+    verified: true
+    text: "`variableDelete(input: { projectId, environmentId, serviceId?, name })` deletes one variable."
+    source: https://docs.railway.com/guides/manage-variables
+  - id: RY7
+    verified: true
+    text: "Railway creates a PR environment when a pull request is opened (with PR environments enabled) and deletes it, with its variables, when the pull request is merged or closed. The recipe takes the environment's id as a param: the plan copies it from the dashboard, `railway status`, or a line that outputs it; the recipe does not look environments up by name (their naming is not documented)."
+    source: https://docs.railway.com/reference/environments
+  - id: RY8
+    verified: false
+    text: "Deleting a variable whose environment Railway already removed (the pull request closed) is an error saying the environment was not found, which the adapter reads as already gone; deleting a variable that does not exist answers `true`."
+  - id: RY9
+    verified: false
+    text: "Sponson does not wait for the redeploy a write triggers (RY5): a step that needs the running service to see the value waits on Railway's deployment status itself. A reference value written as `${{…}}` is not supported in a plan, where `${…}` is Sponson's own interpolation."
+ops:
+  variable:
+    kind: resource
+    title: Variable of a service in an environment
+    summary: "One variable of a service (or, without `service_id`, a shared variable) in a Railway environment, typically the PR environment Railway created. Upserted with `variableUpsert`, read unrendered from `variables`, removed with `variableDelete`. A console edit of the value is drift. Railway redeploys the service after each write unless `skip_deploys` is set; Sponson does not wait for that deploy (RY9)."
+    covers: [railway-variables]
+    params:
+      project_id:
+        type: string
+        required: true
+        description: The project's id.
+        example: prj-railway-demo
+      environment_id:
+        type: string
+        required: true
+        description: The environment's id (for a PR environment, the one Railway created for the pull request; RY7).
+        example: env-pr-42
+      service_id:
+        type: string
+        description: The service's id; without it, the variable is shared by the environment's services.
+        example: svc-web
+      name:
+        type: string
+        required: true
+        pattern: "^[A-Za-z_][A-Za-z0-9_]*$"
+        description: The variable's name.
+        example: API_URL
+      value:
+        type: string
+        required: true
+        description: The variable's value (may be a `{ secret }` reference).
+        example: "https://api-${ctx.scope}.example.app"
+      skip_deploys:
+        type: boolean
+        description: Do not redeploy the service after a write (Railway's default is to redeploy).
+    http:
+      read:
+        graphql:
+          query: "query variables($projectId: String!, $environmentId: String!, $serviceId: String, $unrendered: Boolean) { variables(projectId: $projectId, environmentId: $environmentId, serviceId: $serviceId, unrendered: $unrendered) }"
+          variables: { projectId: { param: project_id }, environmentId: { param: environment_id }, serviceId: { param: service_id }, unrendered: true }
+          data_path: { join: ["/variables/", { param: name }] }
+      create:
+        graphql:
+          query: "mutation variableUpsert($input: VariableUpsertInput!) { variableUpsert(input: $input) }"
+          variables: { input: { projectId: { param: project_id }, environmentId: { param: environment_id }, serviceId: { param: service_id }, name: { param: name }, value: { param: value }, skipDeploys: { param: skip_deploys } } }
+          idempotent: true
+      update:
+        graphql:
+          query: "mutation variableUpsert($input: VariableUpsertInput!) { variableUpsert(input: $input) }"
+          variables: { input: { projectId: { param: project_id }, environmentId: { param: environment_id }, serviceId: { param: service_id }, name: { param: name }, value: { param: value }, skipDeploys: { param: skip_deploys } } }
+          idempotent: true
+      delete:
+        graphql:
+          query: "mutation variableDelete($input: VariableDeleteInput!) { variableDelete(input: $input) }"
+          variables: { input: { projectId: { param: project_id }, environmentId: { param: environment_id }, serviceId: { param: service_id }, name: { param: name } } }
+      fields:
+        value: { param: value }
+    sim:
+      provider: railway
+      seed: { environments: { env-pr-42: { projectId: prj-railway-demo, name: pr-42 } } }
+      present: /variables/env-pr-42~1svc-web/API_URL
+      drift:
+        changed: { vars.env-pr-42.svc-web.API_URL: "https://somewhere-else.example" }
+        missing: { vars.env-pr-42.svc-web.API_URL: delete }
+    live:
+      params: { project_id: SPONSON_LIVE_RAILWAY_PROJECT_ID, environment_id: SPONSON_LIVE_RAILWAY_ENVIRONMENT_ID, service_id: SPONSON_LIVE_RAILWAY_SERVICE_ID }

package/recipes/render.yaml

@@ -0,0 +1,103 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Render API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: render
+title: Render
+category: deploy
+verified_on: "2026-10-11"
+docs:
+  - title: Authentication
+    url: https://api-docs.render.com/reference/authentication
+  - title: Retrieve environment variable
+    url: https://api-docs.render.com/reference/retrieve-env-var
+  - title: Add or update environment variable
+    url: https://api-docs.render.com/reference/update-env-var
+  - title: Delete environment variable
+    url: https://api-docs.render.com/reference/delete-env-var
+  - title: Update environment variables (replace all; deploy behaviour)
+    url: https://api-docs.render.com/reference/update-env-vars-for-service
+  - title: Service previews
+    url: https://render.com/docs/service-previews
+  - title: Render CLI (RENDER_API_KEY)
+    url: https://render.com/docs/cli
+api:
+  base_url: https://api.render.com/v1
+  base_url_env: RENDER_API_URL
+  auth: { bearer_env: RENDER_API_KEY }
+detect:
+  env: ["RENDER_*"]
+  files: [render.yaml]
+  starter:
+    - op: env_var
+  where:
+    service_id: "Render Dashboard → the preview service: the `srv-…` id in its URL"
+assumptions:
+  - id: RE1
+    verified: true
+    text: "Requests authenticate with an API key as `Authorization: Bearer`; the Render CLI reads it from `RENDER_API_KEY`."
+    source: https://api-docs.render.com/reference/authentication
+  - id: RE2
+    verified: true
+    text: "`GET /services/{serviceId}/env-vars/{envVarKey}` answers the variable bare, `{ key, value }`, and 404 when it does not exist."
+    source: https://api-docs.render.com/reference/retrieve-env-var
+  - id: RE3
+    verified: true
+    text: "`PUT /services/{serviceId}/env-vars/{envVarKey}` with `{ value }` adds the variable or replaces its value (200, `{ key, value }`): a create whose answer was lost is the same request again, and the variable's name is its identity."
+    source: https://api-docs.render.com/reference/update-env-var
+  - id: RE4
+    verified: true
+    text: "`DELETE /services/{serviceId}/env-vars/{envVarKey}` removes the variable (204)."
+    source: https://api-docs.render.com/reference/delete-env-var
+  - id: RE5
+    verified: false
+    text: "Deleting a variable that is already gone answers 404 (documented only as \"Unable to find the requested resource\"), which destroy treats as done."
+    source: https://api-docs.render.com/reference/delete-env-var
+  - id: RE6
+    verified: true
+    text: "Changing environment variables through the API does not deploy the service, whatever its autoDeploy setting (stated for the replace-all endpoint); a running preview sees a new value only after its next deploy."
+    source: https://api-docs.render.com/reference/update-env-vars-for-service
+  - id: RE7
+    verified: false
+    text: "The single-variable PUT does not deploy either (its page is silent; assumed like the replace-all endpoint)."
+  - id: RE8
+    verified: true
+    text: "Render creates service previews and preview environments itself (per pull request, from the service's Previews setting or `render.yaml`); a preview copies the base service's variables once, when it is created. No API looks up the preview of pull request N, so the line takes the service's id."
+    source: https://render.com/docs/service-previews
+  - id: RE9
+    verified: false
+    text: "`GET` returns the value in plain text for every variable, including ones generated with `generateValue`, so the value can be compared for drift."
+    source: https://api-docs.render.com/reference/retrieve-env-var
+ops:
+  env_var:
+    kind: resource
+    title: Service environment variable
+    summary: "One environment variable on a Render service, such as a preview service's `API_URL`, written by name (`PUT` adds or replaces it). A console edit of its value is drift; destroy deletes it. The service's id is a param: Render creates preview services itself, and writing a variable does not deploy (RE6)."
+    covers: [render-env]
+    params:
+      service_id:
+        type: string
+        required: true
+        pattern: "^[a-z]{3}-[a-z0-9]+$"
+        description: The service's id (`srv-…`, in the service's dashboard URL and settings).
+        example: srv-d0a1b2c3d4e5f6g7h8i9
+      key:
+        type: string
+        required: true
+        pattern: "^[A-Za-z_][A-Za-z0-9_]*$"
+        description: The variable's name.
+        example: API_URL
+      value:
+        type: string
+        required: true
+        description: "The variable's value: a literal, `{ from }` or `{ secret }`."
+        example: "https://api-${ctx.scope}.example.com"
+    http:
+      read: { path: "/services/{service_id}/env-vars/{key}" }
+      create: { method: PUT, path: "/services/{service_id}/env-vars/{key}" }
+      update: { method: PUT }
+      id_path: /key
+      fields:
+        value: { param: value }
+    sim:
+      collection: "/services/{service_id}/env-vars"
+    live:
+      params: { service_id: SPONSON_LIVE_RENDER_SERVICE_ID }