@sponson/adapters 0.4.0 → 0.6.0

package/recipes/cockroachdb.yaml

@@ -0,0 +1,132 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# CockroachDB Cloud API recipes (service account API key, bearer). Format and checklist: docs/adr/0020-recipes.md,
+# CONTRIBUTING.md "Adding a recipe".
+provider: cockroachdb
+title: CockroachDB Cloud
+category: databases
+verified_on: "2026-10-11"
+docs:
+  - title: Cloud API OpenAPI document (version 2026-09-15)
+    url: https://cockroachlabs.cloud/assets/docs/api/latest/openapi.json
+  - title: Use the CockroachDB Cloud API
+    url: https://docs.cockroachlabs.com/docs/cockroachcloud/cloud-api
+api:
+  base_url: https://cockroachlabs.cloud/api/v1
+  base_url_env: COCKROACH_API_URL
+  auth: { bearer_env: COCKROACH_API_KEY }
+  headers: { Cc-Version: "2024-09-16" }
+detect:
+  env: ["COCKROACH_*"]
+  db_hosts: [.cockroachlabs.cloud]
+  starter:
+    - op: database
+      values: { name: "app_${ctx.scope}" }
+  where:
+    cluster_id: "CockroachDB Cloud Console → your cluster (the UUID in its URL), or `ccloud cluster list`"
+assumptions:
+  - id: CR1
+    verified: true
+    text: "The Cloud API authenticates with a service account's secret key as `Authorization: Bearer`; the key has the service account's roles."
+    source: https://docs.cockroachlabs.com/docs/cockroachcloud/cloud-api
+  - id: CR2
+    verified: true
+    text: "`Cc-Version` pins the API version (`YYYY-MM-DD`); without it the latest version answers, which may change under a client. The guide documents `2024-09-16`."
+    source: https://docs.cockroachlabs.com/docs/cockroachcloud/cloud-api
+  - id: CR3
+    verified: true
+    text: "`POST /clusters/{cluster_id}/databases` with `{ name }` creates a database and answers `{ name, table_count }`; `GET` on the same path lists `{ databases: [{ name, table_count }], pagination: { next_page } }`, paged with `pagination.page`; `DELETE /clusters/{cluster_id}/databases/{name}` deletes one. There is no GET of a single database."
+    source: https://cockroachlabs.cloud/assets/docs/api/latest/openapi.json
+  - id: CR4
+    verified: true
+    text: "`POST /clusters/{cluster_id}/sql-users` with `{ name, password }` (both required) creates a SQL user; `GET` on the same path lists `{ users: [{ name }], pagination: { next_page } }`; `DELETE /clusters/{cluster_id}/sql-users/{name}` deletes one. The password cannot be read back; `PUT …/sql-users/{name}/password` changes it."
+    source: https://cockroachlabs.cloud/assets/docs/api/latest/openapi.json
+  - id: CR5
+    verified: true
+    text: "A SQL user created through the API gets the SQL `admin` role by default, which the guide advises against for anything but administration."
+    source: https://docs.cockroachlabs.com/docs/cockroachcloud/cloud-api
+  - id: CR6
+    verified: true
+    text: "Creating or deleting databases and SQL users needs a cluster-level role of the service account (Cluster Admin, Cluster Operator or Cluster Data Accessor for databases; Cluster Admin for SQL users)."
+    source: https://cockroachlabs.cloud/assets/docs/api/latest/openapi.json
+  - id: CR7
+    verified: false
+    text: "`COCKROACH_API_KEY` is the variable the CockroachDB Terraform provider and `ccloud` read the key from."
+  - id: CR8
+    verified: false
+    text: "A second create of an existing database or SQL user is refused with 409 (ALREADY_EXISTS), and deleting one that is gone answers 404."
+  - id: CR9
+    verified: false
+    text: "Deleting a database drops it with its tables (CASCADE); the API offers no way to refuse when it holds data."
+  - id: CR10
+    verified: false
+    text: "The API takes database and user names that need quoting in SQL (`app_pr-42`, from a scope with `-`) and quotes them itself."
+ops:
+  database:
+    kind: resource
+    title: Database in a cluster
+    summary: "A database per scope in a shared CockroachDB Cloud cluster, such as `app_pr_42`, instead of a cluster per preview. Located by its name in the cluster's list; only its existence is compared (the API exposes nothing else to set); destroy drops it with its data (CR9)."
+    covers: [cockroachdb-database]
+    params:
+      cluster_id:
+        type: string
+        required: true
+        description: The cluster's id (a UUID, shown in the Cloud Console's URL).
+        example: 9e3f1a52-63d1-4a4c-9b8f-2c8b7a0e5d11
+      name:
+        type: string
+        required: true
+        pattern: "^[A-Za-z_][A-Za-z0-9_.-]{0,62}$"
+        description: "The database's name; its identity. A name with `-` (a scope such as `pr-42`) needs quoting in SQL (CR10)."
+        example: "app_${ctx.scope}"
+    http:
+      find:
+        path: "/clusters/{cluster_id}/databases"
+        list_path: /databases
+        match: { name: { param: name } }
+        next: /pagination/next_page
+        cursor_param: pagination.page
+      create: { path: "/clusters/{cluster_id}/databases" }
+      delete: { path: "/clusters/{cluster_id}/databases/{id}" }
+      id_path: /name
+    sim:
+      id_from: name
+    live:
+      params: { cluster_id: SPONSON_LIVE_COCKROACH_CLUSTER_ID }
+  sql_user:
+    kind: resource
+    title: SQL user in a cluster
+    summary: "A SQL user per scope in a shared CockroachDB Cloud cluster, such as `app_pr_42`, with its password as an input (`{ secret: … }`, or a sensitive output of another line), sent on create only and never compared. It gets the SQL `admin` role (CR5): grant narrower privileges in SQL if previews must not administer the cluster. Located by its name; destroy deletes the user."
+    covers: []
+    params:
+      cluster_id:
+        type: string
+        required: true
+        description: The cluster's id (a UUID, shown in the Cloud Console's URL).
+        example: 9e3f1a52-63d1-4a4c-9b8f-2c8b7a0e5d11
+      name:
+        type: string
+        required: true
+        pattern: "^[A-Za-z_][A-Za-z0-9_.-]{0,62}$"
+        description: The user's name; its identity.
+        example: "app_${ctx.scope}"
+      password:
+        type: string
+        required: true
+        description: "The user's password, as a reference (`{ secret: env://… }`, or `{ from: <line>.<output> }` of a sensitive output); sent on create only (CR4)."
+        example: { secret: "env://PREVIEW_DB_PASSWORD" }
+    http:
+      find:
+        path: "/clusters/{cluster_id}/sql-users"
+        list_path: /users
+        match: { name: { param: name } }
+        next: /pagination/next_page
+        cursor_param: pagination.page
+      create:
+        path: "/clusters/{cluster_id}/sql-users"
+        body: { password: { param: password } }
+      delete: { path: "/clusters/{cluster_id}/sql-users/{id}" }
+      id_path: /name
+    sim:
+      id_from: name
+    live:
+      params: { cluster_id: SPONSON_LIVE_COCKROACH_CLUSTER_ID }

package/recipes/configcat.yaml

@@ -0,0 +1,123 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# ConfigCat Public Management API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: configcat
+title: ConfigCat
+category: flags
+verified_on: "2026-10-11"
+docs:
+  - title: Public Management API
+    url: https://api.configcat.com/docs/
+  - title: OpenAPI spec (get value v2, replace value v2, targeting rule models)
+    url: https://api.configcat.com/docs/v1/swagger.json
+  - title: Terraform provider (credential variable names)
+    url: https://github.com/configcat/terraform-provider-configcat/blob/main/docs/index.md
+api:
+  base_url: https://api.configcat.com
+  base_url_env: CONFIGCAT_API_URL
+  auth: { basic: { user_env: CONFIGCAT_BASIC_AUTH_USERNAME, password_env: CONFIGCAT_BASIC_AUTH_PASSWORD } }
+detect:
+  deps: [configcat-js, configcat-js-ssr, configcat-js-full, configcat-node, configcat-react]
+  env: ["CONFIGCAT_*"]
+  starter:
+    - op: targeting_rule
+      values: { match: "${ctx.scope}" }
+  where:
+    environment_id: "ConfigCat Dashboard → your product → Environments → the preview environment's ID"
+    setting_id: "ConfigCat Public Management API `GET /v1/configs/{configId}/settings`: the flag's `settingId`"
+assumptions:
+  - id: CC1
+    verified: true
+    text: "The API is at `https://api.configcat.com`, authenticated with Basic auth from Public API credentials (the Terraform provider's `CONFIGCAT_BASIC_AUTH_USERNAME` / `CONFIGCAT_BASIC_AUTH_PASSWORD`)."
+    source: https://api.configcat.com/docs/v1/swagger.json
+  - id: CC2
+    verified: true
+    text: "`GET /v2/environments/{environmentId}/settings/{settingId}/value` answers the setting's value in the environment bare: `defaultValue`, `targetingRules`, `percentageEvaluationAttribute` and read-only fields."
+    source: https://api.configcat.com/docs/v1/swagger.json
+  - id: CC3
+    verified: true
+    text: "`PUT` on the same path replaces the value: only `defaultValue`, `targetingRules` and `percentageEvaluationAttribute` can be set, and one not sent is reset. So those three are sent, as read, with the rule list changed (`parent.send`)."
+    source: https://api.configcat.com/docs/v1/swagger.json
+  - id: CC4
+    verified: true
+    text: "A targeting rule is `{ conditions: [{ userCondition: { comparisonAttribute, comparator, comparisonValue: { stringValue, doubleValue, listValue: [{ value, hint }] } } }], value | percentageOptions }`; rules have no id and are evaluated in order. `isOneOf` and `sensitiveIsOneOf` compare a user attribute with a list."
+    source: https://api.configcat.com/docs/v1/swagger.json
+  - id: CC5
+    verified: true
+    text: "Answers carry every member of a value (`boolValue`, `stringValue`, `intValue`, `doubleValue`, `predefinedVariationId`) and of a comparison value, the unused ones null; the rule is written with the same nulls so that it reads back equal."
+    source: https://api.configcat.com/docs/v1/swagger.json
+  - id: CC6
+    verified: false
+    text: "A condition is read back with `segmentCondition` and `prerequisiteFlagCondition` null and each list value's `hint` null, exactly as written; otherwise every plan shows the rule as changed."
+  - id: CC7
+    verified: false
+    text: "In a product with \"Config changes require a reason\" or approvals turned on, the PUT without `reason` / `bypassApproval` is refused (the query parameters are not sent); the apply then fails."
+    source: https://api.configcat.com/docs/v1/swagger.json
+ops:
+  targeting_rule:
+    kind: list_item
+    title: Feature flag targeting rule
+    summary: "A targeting rule on a boolean feature flag in one environment that serves a value to the preview, such as `IF Preview IS ONE OF [pr-42] THEN true`. Added after the flag's other rules (evaluated in order: an earlier matching rule wins); the default value and the other rules are written back as read. Identified by the matched value; a console edit of its condition or served value is drift. Destroy removes the rule."
+    covers: [configcat-rule]
+    params:
+      environment_id:
+        type: string
+        required: true
+        description: The environment's id (a UUID).
+        example: 08d8becf-d4d9-4c66-8b48-6ac74cd95fba
+      setting_id:
+        type: string
+        required: true
+        pattern: "^[0-9]+$"
+        description: The feature flag's numeric setting id.
+        example: "12345"
+      attribute:
+        type: string
+        required: true
+        description: The user attribute the rule compares (a custom attribute such as `Preview`, or `Identifier`, `Email`).
+        example: Preview
+      comparator:
+        type: string
+        default: isOneOf
+        enum: [isOneOf, sensitiveIsOneOf]
+        description: "`isOneOf`, or `sensitiveIsOneOf` (hashed in the config JSON)."
+      match:
+        type: string
+        required: true
+        description: The attribute value that is the preview; it identifies the rule.
+        example: "${ctx.scope}"
+      serve:
+        type: boolean
+        default: true
+        description: The value the flag serves to the preview.
+    http:
+      parent:
+        path: "/v2/environments/{environment_id}/settings/{setting_id}/value"
+        method: PUT
+        send: [defaultValue, percentageEvaluationAttribute]
+      list_path: /targetingRules
+      key_field: /conditions/0/userCondition/comparisonValue/listValue/0/value
+      item:
+        conditions:
+          - userCondition:
+              comparisonAttribute: { param: attribute }
+              comparator: { param: comparator }
+              comparisonValue:
+                stringValue: null
+                doubleValue: null
+                listValue: [{ value: { param: match }, hint: null }]
+            segmentCondition: null
+            prerequisiteFlagCondition: null
+        value:
+          boolValue: { param: serve }
+          stringValue: null
+          intValue: null
+          doubleValue: null
+          predefinedVariationId: null
+    sim:
+      objects:
+        "/v2/environments/{environment_id}/settings/{setting_id}/value":
+          defaultValue: { boolValue: false, stringValue: null, intValue: null, doubleValue: null, predefinedVariationId: null }
+          targetingRules: []
+          percentageEvaluationAttribute: null
+    live:
+      params: { environment_id: SPONSON_LIVE_CONFIGCAT_ENVIRONMENT_ID, setting_id: SPONSON_LIVE_CONFIGCAT_SETTING_ID }

package/recipes/datadog.yaml

@@ -0,0 +1,136 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Datadog API recipes: every request carries the API key and the application key. Format and checklist:
+# docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: datadog
+title: Datadog
+category: observability
+verified_on: "2026-10-11"
+docs:
+  - title: Synthetics API reference
+    url: https://docs.datadoghq.com/api/latest/synthetics/
+  - title: API authentication (keys, sites)
+    url: https://docs.datadoghq.com/api/latest/authentication/
+  - title: Datadog API v1 OpenAPI document (datadog-api-client)
+    url: https://github.com/DataDog/datadog-api-client-typescript/blob/master/.generator/schemas/v1/openapi.yaml
+api:
+  base_url: https://api.datadoghq.com/api/v1
+  base_url_env: DATADOG_API_URL
+  auth:
+    headers:
+      - { header: DD-API-KEY, value_env: DD_API_KEY }
+      - { header: DD-APPLICATION-KEY, value_env: DD_APP_KEY }
+detect:
+  deps: [dd-trace, "@datadog/"]
+  env: ["DD_*", "DATADOG_*"]
+  starter:
+    - op: synthetic_api_test
+      preview_url: url
+      values: { name: "preview ${ctx.scope}", locations: ["aws:us-east-2"] }
+assumptions:
+  - id: DD1
+    verified: true
+    text: "Requests carry the API key in `DD-API-KEY` and the application key in `DD-APPLICATION-KEY`; Datadog's clients read them from `DD_API_KEY` and `DD_APP_KEY`. Reading needs the application key too."
+    source: https://github.com/DataDog/datadog-api-client-typescript/blob/master/.generator/schemas/v1/openapi.yaml
+  - id: DD2
+    verified: true
+    text: "Each Datadog site has its own API host (`https://api.datadoghq.eu`, `https://api.us3.datadoghq.com`, …): outside US1, set `base_url` in the provider block."
+    source: https://docs.datadoghq.com/api/latest/authentication/
+  - id: DD3
+    verified: true
+    text: "`POST /synthetics/tests/api` creates an API test from `name`, `type` (`api`), `config` (`request` with `method` and `url`, `assertions`), `locations`, `options` and `message` (all required), with `subtype` (`http`), `status` (`live` or `paused`) and `tags`, answering it with its `public_id`."
+    source: https://github.com/DataDog/datadog-api-client-typescript/blob/master/.generator/schemas/v1/openapi.yaml
+  - id: DD4
+    verified: true
+    text: "`GET /synthetics/tests/api/{public_id}` answers one API test; `PUT` on the same path replaces its configuration with a whole test definition."
+    source: https://github.com/DataDog/datadog-api-client-typescript/blob/master/.generator/schemas/v1/openapi.yaml
+  - id: DD5
+    verified: true
+    text: "`GET /synthetics/tests` lists every test as `{ tests: [...] }` (`page_size` and `page_number` are optional); `POST /synthetics/tests/delete` with `{ public_ids: [...] }` deletes tests."
+    source: https://github.com/DataDog/datadog-api-client-typescript/blob/master/.generator/schemas/v1/openapi.yaml
+  - id: DD6
+    verified: false
+    text: "Without `page_size` the list answers every test of the organisation, and a test name identifies one test (two with one name make `find` refuse with PARAM_INVALID)."
+  - id: DD7
+    verified: false
+    text: "The fields compared (`config.request`, `config.assertions`, `locations`, `options.tick_every`, `message`, `status`, `tags`) are answered as they were sent, in order."
+  - id: DD8
+    verified: false
+    text: "Deleting a test that is already gone answers 404 (destroy treats it as done)."
+  - id: DD9
+    verified: false
+    text: "Deployment events (`datadog-ci deployment mark`, the DORA deployments API) are not a recipe: they are listed with a POST over a time window and cannot be deleted, so a later run could not find the one it made."
+ops:
+  synthetic_api_test:
+    kind: resource
+    title: Synthetic API test against a preview
+    summary: "A Synthetic HTTP test per scope that checks the preview's URL from Datadog's locations, such as `preview pr-42` asserting status 200, with its own monitor. Located by its name; a console edit of its request, assertions, locations, frequency, message, status or tags is drift; destroy deletes the test (and its monitor)."
+    covers: [datadog-marker]
+    params:
+      name:
+        type: string
+        required: true
+        description: The test's name; its identity (DD6).
+        example: "preview ${ctx.scope}"
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: The URL to request (the preview's URL, or a health path on it).
+        example: "https://${ctx.scope}.preview.example.app/api/health"
+      method:
+        type: string
+        default: GET
+        enum: [GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS]
+        description: The HTTP method.
+      assertions:
+        type: list
+        default: [{ type: statusCode, operator: is, target: 200 }]
+        description: "The assertions, each `{ type, operator, target }` (`statusCode`, `responseTime`, `body`, `header`)."
+      locations:
+        type: list
+        required: true
+        description: "The managed locations to run from, such as `aws:us-east-2` or `aws:eu-central-1`."
+        example: ["aws:us-east-2"]
+      tick_every:
+        type: integer
+        default: 300
+        description: How often the test runs, in seconds.
+      message:
+        type: string
+        default: Preview check managed by Sponson
+        description: The notification message of the test's monitor.
+      status:
+        type: string
+        default: live
+        enum: [live, paused]
+        description: "`paused` keeps the test without running it."
+      tags:
+        type: list
+        default: ["managed-by:sponson"]
+        description: The test's tags.
+    http:
+      find:
+        path: /synthetics/tests
+        list_path: /tests
+        match: { name: { param: name } }
+      read: { path: "/synthetics/tests/api/{id}" }
+      create:
+        path: /synthetics/tests/api
+        body: { type: api, subtype: http }
+      update:
+        method: PUT
+        body: { type: api, subtype: http }
+      delete:
+        method: POST
+        path: /synthetics/tests/delete
+        body: { public_ids: ["{id}"] }
+      id_path: /public_id
+      fields:
+        /config/request/method: { param: method }
+        /config/request/url: { param: url }
+        /config/assertions: { param: assertions }
+        locations: { param: locations }
+        /options/tick_every: { param: tick_every }
+        message: { param: message }
+        status: { param: status }
+        tags: { param: tags }

package/recipes/firebase.yaml

@@ -0,0 +1,84 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Firebase Authentication (Identity Toolkit admin API) recipes. Format and checklist: docs/adr/0020-recipes.md,
+# CONTRIBUTING.md "Adding a recipe".
+provider: firebase
+title: Firebase Authentication
+category: auth
+verified_on: "2026-10-11"
+docs:
+  - title: Identity Toolkit API v2, projects.getConfig
+    url: https://docs.cloud.google.com/identity-platform/docs/reference/rest/v2/projects/getConfig
+  - title: Identity Toolkit API v2, projects.updateConfig
+    url: https://docs.cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig
+  - title: Identity Toolkit API v2, Config
+    url: https://docs.cloud.google.com/identity-platform/docs/reference/rest/v2/Config
+  - title: Authenticate for using REST
+    url: https://docs.cloud.google.com/docs/authentication/rest
+api:
+  base_url: https://identitytoolkit.googleapis.com/admin/v2
+  base_url_env: FIREBASE_API_URL
+  auth: { command: [gcloud, auth, print-access-token] }
+detect:
+  deps: [firebase, firebase-admin]
+  env: ["FIREBASE_*"]
+  files: [firebase.json, .firebaserc]
+  starter:
+    - op: authorized_domain
+  where:
+    project: "`projects.default` in .firebaserc, or `firebase projects:list`"
+    domain: "the preview's host name without `https://` (Firebase takes a domain, so a `{ from }` URL cannot be used)"
+assumptions:
+  - id: FB1
+    verified: true
+    text: "`GET https://identitytoolkit.googleapis.com/admin/v2/projects/{project}/config` answers the project's Auth `Config`."
+    source: https://docs.cloud.google.com/identity-platform/docs/reference/rest/v2/projects/getConfig
+  - id: FB2
+    verified: true
+    text: "`PATCH …/admin/v2/projects/{project}/config?updateMask=authorizedDomains` updates the config with a `Config` body; fields set in the body but not named in `updateMask` are ignored, so the write changes the authorized domains only. It needs one of the `identitytoolkit`, `firebase` or `cloud-platform` OAuth scopes."
+    source: https://docs.cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig
+  - id: FB3
+    verified: true
+    text: "`authorizedDomains` is a list of strings, the domains authorized for OAuth redirects; the masked field is replaced by the list sent, so the recipe sends the whole list read just before with one domain added or removed."
+    source: https://docs.cloud.google.com/identity-platform/docs/reference/rest/v2/Config
+  - id: FB4
+    verified: true
+    text: "`gcloud auth print-access-token` prints an access token for the signed-in credentials, used as `Authorization: Bearer`. With user credentials some APIs also need the quota project in `x-goog-user-project`: add `headers: { x-goog-user-project: <project> }` to the `providers.http.firebase` block (not needed with a service account; a block's headers are part of its identity)."
+    source: https://docs.cloud.google.com/docs/authentication/rest
+  - id: FB5
+    verified: false
+    text: "The config has no precondition the update honours (no etag in `Config`): the line locks the project's config (`lockOn`) against other Sponson runs; a console edit made between the read and the write can still be lost."
+  - id: FB6
+    verified: false
+    text: "An authorized domain is a host name without scheme, port or path, and is read back exactly as written."
+  - id: FB7
+    verified: false
+    text: "The same admin v2 config holds the authorized domains of a Firebase Authentication project with or without the Identity Platform upgrade."
+ops:
+  authorized_domain:
+    kind: list_item
+    title: Authorized domain
+    summary: "One domain in Firebase Authentication's authorized domains (Authentication, Settings, Authorized domains), which OAuth sign-in redirects and email links require, such as the preview deployment's host. Read-modify-write of the list with `updateMask=authorizedDomains` under a lock on the project's config; removed on destroy; every other domain (localhost, the Firebase hosting domains) is left as it is."
+    covers: [firebase-auth-domains]
+    params:
+      project:
+        type: string
+        required: true
+        description: The Google Cloud / Firebase project id.
+        example: demo-project
+      domain:
+        type: string
+        required: true
+        pattern: "^[A-Za-z0-9.-]+$"
+        description: "The domain, a host name without scheme or path (`pr-42.preview.example.app`, `my-app-git-feat-x.vercel.app`)."
+        example: "${ctx.scope}.preview.example.app"
+    http:
+      parent:
+        path: "/projects/{project}/config?updateMask=authorizedDomains"
+        read_path: "/projects/{project}/config"
+      list_path: /authorizedDomains
+      item: { param: domain }
+    sim:
+      objects:
+        "/projects/{project}/config": { name: projects/demo-project/config, authorizedDomains: [localhost, demo-project.firebaseapp.com, demo-project.web.app] }
+    live:
+      params: { project: SPONSON_LIVE_FIREBASE_PROJECT }

package/recipes/flagsmith.yaml

@@ -0,0 +1,98 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Flagsmith Admin (management) API recipes, authenticated by an organisation API key. Format and checklist:
+# docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: flagsmith
+title: Flagsmith
+category: flags
+verified_on: "2026-10-11"
+docs:
+  - title: Admin API authentication
+    url: https://docs.flagsmith.com/integrating-with-flagsmith/flagsmith-api-overview/admin-api/authentication
+  - title: Admin API overview
+    url: https://docs.flagsmith.com/integrating-with-flagsmith/flagsmith-api-overview/admin-api
+  - title: Flagsmith API OpenAPI document
+    url: https://api.flagsmith.com/api/v1/swagger.json
+api:
+  base_url: https://api.flagsmith.com/api/v1
+  base_url_env: FLAGSMITH_API_URL
+  auth: { header: Authorization, value_env: FLAGSMITH_MASTER_API_KEY, prefix: "Api-Key " }
+detect:
+  deps: [flagsmith, flagsmith-nodejs, react-native-flagsmith]
+  env: ["FLAGSMITH_*"]
+  starter:
+    - op: environment
+      values: { name: "preview-${ctx.scope}" }
+  where:
+    project_id: "Flagsmith → your project: the number in its URL (`/project/<id>/…`)"
+assumptions:
+  - id: FS1
+    verified: true
+    text: "The Admin API authenticates with an organisation API key as `Authorization: Api-Key <key>`; Bearer is only for short-lived OIDC-exchanged tokens."
+    source: https://docs.flagsmith.com/integrating-with-flagsmith/flagsmith-api-overview/admin-api/authentication
+  - id: FS2
+    verified: true
+    text: "`POST /environments/` creates an environment from `name` and `project` (both required) and optional `description`, answering it (201) with its integer `id` and its `api_key`, the client-side environment key SDKs use."
+    source: https://api.flagsmith.com/api/v1/swagger.json
+  - id: FS3
+    verified: true
+    text: "`GET /environments/?project=<id>` lists a project's environments as `{ count, next, previous, results: [...] }`."
+    source: https://api.flagsmith.com/api/v1/swagger.json
+  - id: FS4
+    verified: true
+    text: "`GET`, `PATCH` and `DELETE /environments/{api_key}/` read, update and delete one environment (DELETE answers 204)."
+    source: https://api.flagsmith.com/api/v1/swagger.json
+  - id: FS5
+    verified: false
+    text: "A project has fewer environments than one page of the list holds, so `find` sees them all (`next` is a URL, which the http adapter does not follow)."
+  - id: FS6
+    verified: false
+    text: "A new environment starts with every feature of the project at its default state, and environment names are unique in a project in practice (two with one name make `find` refuse with PARAM_INVALID)."
+  - id: FS7
+    verified: false
+    text: "`description` is answered as sent; `FLAGSMITH_MASTER_API_KEY` is the variable Flagsmith's Terraform provider reads the key from."
+  - id: FS8
+    verified: false
+    text: "Identity and segment overrides are not recipes: Edge projects (Flagsmith SaaS's default) address identities by UUID through `edge-identities`, and a segment override is two objects (a feature segment, then a feature state) created in order."
+  - id: FS9
+    verified: false
+    text: "The create takes the project id as a string of digits (`\"1234\"`) as well as a number, as Django REST Framework's primary-key fields do."
+ops:
+  environment:
+    kind: resource
+    title: Environment per preview
+    summary: "A Flagsmith environment per scope in a project, such as `preview-pr-42`, starting from the project's default flag states; its client-side environment key is the output `api_key` for the preview's SDK configuration. Located by name in the project; a console edit of its description is drift; destroy deletes the environment with its flag states and identities."
+    covers: [flagsmith-override]
+    params:
+      project_id:
+        type: string
+        required: true
+        pattern: "^[0-9]+$"
+        description: The project's id, digits as a string (FS9).
+        example: "1234"
+      name:
+        type: string
+        required: true
+        description: The environment's name; its identity in the project (FS6).
+        example: "preview-${ctx.scope}"
+      description:
+        type: string
+        default: Preview environment managed by Sponson
+        description: The environment's description.
+    http:
+      find:
+        path: "/environments/?project={project_id}"
+        list_path: /results
+        match: { name: { param: name } }
+      read: { path: "/environments/{id}/" }
+      create:
+        path: /environments/
+        body: { project: { param: project_id } }
+      update: { method: PATCH }
+      id_path: /api_key
+      fields:
+        description: { param: description }
+      outputs:
+        api_key: /api_key
+        environment_id: /id
+    live:
+      params: { project_id: SPONSON_LIVE_FLAGSMITH_PROJECT_ID }