Forward API reference.
Description
Updates an Environment's configuration and display information with POST.
Path
POST /api/v1/forward/environments/{id}
Request headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <PAT or SAT> |
Content-Type | Yes | application/json |
x-qoder-beta | Conditional | Required when the updated config.storage.buckets is nonempty; set to oss-bucket-2026-09-23. |
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Environment ID. |
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
identity_id | string | No | Optional; used only for Identity-owned resources. PAT callers can pass it explicitly; omitting it uses the administrator scope. For SAT, issue an Identity-scoped token and do not explicitly pass this parameter, or the request returns HTTP 400. See Identity ownership. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | New name. |
description | string | No | New description. |
config | Environment config | No | Replaces the saved configuration in full. It must not be null; an explicit null returns 400. See schemas for field details. |
metadata | object | No | Environment metadata to merge. It must not be null; an explicit null returns 400. |
config.storage.buckets supports up to 7 buckets. credential is a write-only field, retained by bucket name: omitting credentials or returning the masked values unchanged preserves the saved credentials. Changing name, changing credential.type, or passing null requires complete credentials.
Deleting a bucket or passing "buckets": [] affects only Sessions created afterward. Existing Sessions use the snapshot taken at creation. See Environment storage for full details.
Example request
Example response
HTTP 200 OK
Response fields
The response is an Environment object.
Errors
| HTTP | Type | Trigger |
|---|---|---|
| 400 | invalid_request_error | The request body, path parameters, or query parameters are invalid. Also returned if SAT explicitly includes identity_id. |
| 400 | invalid_request_error | config.storage.buckets is invalid (including more than 7 buckets), the x-qoder-beta header is missing, or the trial mount is denied when saving. |
| 400 | invalid_request_error | If the reserved key created_by is supplied, message is metadata key "created_by" is reserved, identifying the invalid field. |
| 401 | authentication_error | The authentication token is missing or invalid. |
| 403 | permission_error | Owner mismatch for a PAT without identity_id or an Admin SAT, or other insufficient permissions. |
| 404 | not_found_error | The resource does not exist or is not visible. identity_id is invalid, disabled, or does not belong to the caller, or the target resource does not belong to the current Identity scope. |
| 503 | feature_not_available | The account is not eligible for the oss_bucket Beta. |
| 503 | api_error | OSS / STS is temporarily unavailable when saving. Retry the request. |
| 500/502/503 | api_error | Forward or a dependent service failed. |