Public API: Environments
A feature flag is a setting in your code that can be turned on, off, or changed without a new deploy. An environment is where one version of your flags runs, such as production or staging. Each environment has its own SDK key.
A datafile is the small JSON file the snippet or SDK downloads that lists every live flag for one environment. This API lets a service token manage a project's environments. You can list them, read one, create new ones, rename or recolour them, archive them, and publish a fresh datafile.
Environments is its own link in the project sidebar, next to Settings, not inside it. It only shows up for feature-flag projects. A web-experiments project has no Environments item and no environment rows at all: listing or creating one there is refused with 400. The single-environment endpoints below (get, update, delete, publish) return 404 instead, because there is nothing to find.
Every environment endpoint lives under a project and authenticates with a service token. Your token already names its organization, so the path carries only {projectId} (and {envId} for a single environment), never {orgId}. A project that is not in your token's org returns 404, so a wrong id and a project you cannot see look the same.
https://app.avsb.cloud/api/v1/projects/{projectId}/environmentsScopes
A scope is a named permission on your token. It decides exactly what that token can read or change.
| Operation | Scope |
|---|---|
| List / get environments | projects:read |
| Create / update / delete / publish | projects:write |
List environments
GET /api/v1/projects/{projectId}/environments: every active environment (archived ones are hidden), in sidebar order. Cursor-paginated (?limit= up to 100, default 20; ?cursor=, the opaque value from page.nextCursor). Requires projects:read.
curl "https://app.avsb.cloud/api/v1/projects/<projectId>/environments?limit=20" \ -H "Authorization: Bearer avsb_svc_..."const projectId = 'cm1a2b3c4d5e6f7g8h9i0j1k2'const url = `https://app.avsb.cloud/api/v1/projects/${projectId}/environments?limit=20`const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AVSB_SERVICE_TOKEN}` } })const { data, page } = await res.json()import os, requestsproject_id = "cm1a2b3c4d5e6f7g8h9i0j1k2"res = requests.get( f"https://app.avsb.cloud/api/v1/projects/{project_id}/environments", params={"limit": 20}, headers={"Authorization": f"Bearer {os.environ['AVSB_SERVICE_TOKEN']}"},)data, page = res.json()["data"], res.json()["page"]{ "data": [ { "id": "<envId>", "projectId": "<projectId>", "name": "Production", "key": "production", "sdkKey": "sdk_production_cm3x9k2l40001qrs7t8u9v0w", "color": "#6b7280", "sortOrder": 1, "archivedAt": null, "lastSdkSeenAt": null, "lastSdkType": null, "lastSdkVersion": null, "createdAt": "2026-06-18T00:00:00.000Z", "updatedAt": "2026-06-18T00:00:00.000Z" } ], "page": { "nextCursor": null, "hasMore": false }}Pass ?cursor=<page.nextCursor> to fetch the next page. An out-of-range limit, or a cursor this API never produced, is refused rather than clamped. See Conventions for that error shape.
Get an environment
GET /api/v1/projects/{projectId}/environments/{envId}: one environment by id, in the flat { data: <environment> } envelope shown under List environments above. Requires projects:read.
curl https://app.avsb.cloud/api/v1/projects/<projectId>/environments/<envId> \ -H "Authorization: Bearer avsb_svc_..."const projectId = 'cm1a2b3c4d5e6f7g8h9i0j1k2'const envId = 'clx2b3c4d5e6f7g8h9i0j1k2'const url = `https://app.avsb.cloud/api/v1/projects/${projectId}/environments/${envId}`const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AVSB_SERVICE_TOKEN}` } })const { data } = await res.json()import os, requestsproject_id = "cm1a2b3c4d5e6f7g8h9i0j1k2"env_id = "clx2b3c4d5e6f7g8h9i0j1k2"res = requests.get( f"https://app.avsb.cloud/api/v1/projects/{project_id}/environments/{env_id}", headers={"Authorization": f"Bearer {os.environ['AVSB_SERVICE_TOKEN']}"},)data = res.json()["data"]{ "error": { "code": "not_found", "message": "Environment not found", "docUrl": "https://docs.avsb.cloud/docs/developer-reference/public-api/conventions#not-found-errors", "requestId": "req_9f2c41ab7e0b4d1e8c35a6f0d2b91e77" }}An id from another org, or one that never existed, gets this same answer. Existence is never leaked across an org boundary.
Create an environment
POST /api/v1/projects/{projectId}/environments: name and key are the only required fields. Requires projects:write. key must start with a lowercase letter and hold only lowercase letters, digits, and underscores, up to 50 characters; it is fixed forever once set. Responds 201 with the created environment, including a freshly generated sdkKey.
curl -X POST https://app.avsb.cloud/api/v1/projects/<projectId>/environments \ -H "Authorization: Bearer avsb_svc_..." \ -H "Content-Type: application/json" \ -d '{ "name": "Staging", "key": "staging" }'const projectId = 'cm1a2b3c4d5e6f7g8h9i0j1k2'const res = await fetch(`https://app.avsb.cloud/api/v1/projects/${projectId}/environments`, { method: 'POST', headers: { Authorization: `Bearer ${process.env.AVSB_SERVICE_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Staging', key: 'staging' }),})const { data } = await res.json()import os, requestsproject_id = "cm1a2b3c4d5e6f7g8h9i0j1k2"res = requests.post( f"https://app.avsb.cloud/api/v1/projects/{project_id}/environments", headers={"Authorization": f"Bearer {os.environ['AVSB_SERVICE_TOKEN']}"}, json={"name": "Staging", "key": "staging"},)data = res.json()["data"]{ "data": { "id": "<envId>", "projectId": "<projectId>", "name": "Staging", "key": "staging", "sdkKey": "sdk_staging_cm4y0m3n50002wxyz5678ijkl", "color": "#6b7280", "sortOrder": 2, "archivedAt": null, "lastSdkSeenAt": null, "lastSdkType": null, "lastSdkVersion": null, "createdAt": "2026-06-18T00:00:00.000Z", "updatedAt": "2026-06-18T00:00:00.000Z" }}The new environment goes after every environment the project already has. Its datafile is published before the call returns, so an SDK given the new sdkKey can connect and report in straight away. Every flag in the project starts off in the new environment until you run it there.
color is optional and defaults to #6b7280. Send it to pick your own, alongside any other field you need; the shape is otherwise identical to the request above:
curl -X POST https://app.avsb.cloud/api/v1/projects/<projectId>/environments \ -H "Authorization: Bearer avsb_svc_..." \ -H "Content-Type: application/json" \ -d '{ "name": "Staging EU", "key": "staging_eu", "color": "#3b82f6" }'A duplicate key within the project is refused:
{ "error": { "code": "validation_failed", "message": "An environment with this key already exists in this project", "docUrl": "https://docs.avsb.cloud/docs/developer-reference/public-api/conventions#validation-errors", "requestId": "req_9f2c41ab7e0b4d1e8c35a6f0d2b91e77" }}Requires projects:write, and only works on a feature-flag project: see the callout near the top of this page for what happens otherwise.
Update an environment
PATCH /api/v1/projects/{projectId}/environments/{envId}: only name and color are mutable; key is fixed at creation. Send only the fields you are changing. Requires projects:write. Mutations support X-Avsb-If-Match (or If-Match) for optimistic concurrency (see Conventions).
curl -X PATCH https://app.avsb.cloud/api/v1/projects/<projectId>/environments/<envId> \ -H "Authorization: Bearer avsb_svc_..." \ -H "Content-Type: application/json" \ -d '{ "name": "Staging EU", "color": "#3b82f6" }'const projectId = 'cm1a2b3c4d5e6f7g8h9i0j1k2'const envId = 'clx2b3c4d5e6f7g8h9i0j1k2'const url = `https://app.avsb.cloud/api/v1/projects/${projectId}/environments/${envId}`const res = await fetch(url, { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.AVSB_SERVICE_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Staging EU', color: '#3b82f6' }),})const { data } = await res.json()import os, requestsproject_id = "cm1a2b3c4d5e6f7g8h9i0j1k2"env_id = "clx2b3c4d5e6f7g8h9i0j1k2"res = requests.patch( f"https://app.avsb.cloud/api/v1/projects/{project_id}/environments/{env_id}", headers={"Authorization": f"Bearer {os.environ['AVSB_SERVICE_TOKEN']}"}, json={"name": "Staging EU", "color": "#3b82f6"},)data = res.json()["data"]{ "data": { "id": "<envId>", "projectId": "<projectId>", "name": "Staging EU", "key": "staging", "sdkKey": "sdk_staging_cm4y0m3n50002wxyz5678ijkl", "color": "#3b82f6", "sortOrder": 2, "archivedAt": null, "lastSdkSeenAt": null, "lastSdkType": null, "lastSdkVersion": null, "createdAt": "2026-06-18T00:00:00.000Z", "updatedAt": "2026-06-19T08:30:00.000Z" }}An id from another org, or one that never existed, returns the same 404 shown under Get an environment above.
Delete an environment
DELETE /api/v1/projects/{projectId}/environments/{envId}: archives the environment (a soft delete) and returns just its id. Requires projects:write.
curl -X DELETE https://app.avsb.cloud/api/v1/projects/<projectId>/environments/<envId> \ -H "Authorization: Bearer avsb_svc_..."const projectId = 'cm1a2b3c4d5e6f7g8h9i0j1k2'const envId = 'clx2b3c4d5e6f7g8h9i0j1k2'const url = `https://app.avsb.cloud/api/v1/projects/${projectId}/environments/${envId}`const res = await fetch(url, { method: 'DELETE', headers: { Authorization: `Bearer ${process.env.AVSB_SERVICE_TOKEN}` },})const { data } = await res.json()import os, requestsproject_id = "cm1a2b3c4d5e6f7g8h9i0j1k2"env_id = "clx2b3c4d5e6f7g8h9i0j1k2"res = requests.delete( f"https://app.avsb.cloud/api/v1/projects/{project_id}/environments/{env_id}", headers={"Authorization": f"Bearer {os.environ['AVSB_SERVICE_TOKEN']}"},)data = res.json()["data"]{ "data": { "id": "<envId>" } }A project must keep at least two active environments, so deleting one that would drop the project below two is refused:
{ "error": { "code": "validation_failed", "message": "Cannot delete: project must have at least two environments", "docUrl": "https://docs.avsb.cloud/docs/developer-reference/public-api/conventions#validation-errors", "requestId": "req_9f2c41ab7e0b4d1e8c35a6f0d2b91e77" }}An environment that is already archived returns 410 with the same validation_failed code. That check comes first, so repeating a delete always gets the 410, however many environments are left.
Production and Development, the two environments every feature-flag project starts with, cannot be deleted, because the SDK keys in your code point at them. Deleting either returns 422 with details.reason set to environment_protected. Only environments you added can be deleted.
{ "error": { "code": "validation_failed", "message": "Production is one of the two environments every flag project starts with, so it cannot be deleted. Only environments you added can be.", "details": { "reason": "environment_protected" }, "docUrl": "https://docs.avsb.cloud/docs/developer-reference/public-api/conventions#validation-errors", "requestId": "req_9f2c41ab7e0b4d1e8c35a6f0d2b91e77" }}Publish an environment
POST /api/v1/projects/{projectId}/environments/{envId}/publish: regenerate that environment's datafile and clear its pending-changes marker. A webhook is an automatic HTTP request A vs B sends to your own server when something happens. Publishing here fires one, flag.published, once the new datafile is live. Requires projects:write. The call changes state rather than creating something, so it returns 200, not 201.
curl -X POST https://app.avsb.cloud/api/v1/projects/<projectId>/environments/<envId>/publish \ -H "Authorization: Bearer avsb_svc_..."const projectId = 'cm1a2b3c4d5e6f7g8h9i0j1k2'const envId = 'clx2b3c4d5e6f7g8h9i0j1k2'const url = `https://app.avsb.cloud/api/v1/projects/${projectId}/environments/${envId}/publish`const res = await fetch(url, { method: 'POST', headers: { Authorization: `Bearer ${process.env.AVSB_SERVICE_TOKEN}` },})const { data } = await res.json()import os, requestsproject_id = "cm1a2b3c4d5e6f7g8h9i0j1k2"env_id = "clx2b3c4d5e6f7g8h9i0j1k2"res = requests.post( f"https://app.avsb.cloud/api/v1/projects/{project_id}/environments/{env_id}/publish", headers={"Authorization": f"Bearer {os.environ['AVSB_SERVICE_TOKEN']}"},)data = res.json()["data"]{ "data": { "published": true, "environmentId": "<envId>" } }An id from another org, or one that never existed, returns the same 404 shown under Get an environment above.