Skip to main content

Update an Environment

Forward API reference.

Description

Updates an Environment's configuration and display information with POST.

Path

POST /api/v1/forward/environments/{id}

Request headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT or SAT>
Content-TypeYesapplication/json
x-qoder-betaConditionalRequired when the updated config.storage.buckets is nonempty; set to oss-bucket-2026-09-23.

Path parameters

ParameterTypeRequiredDescription
idstringYesEnvironment ID.

Query parameters

ParameterTypeRequiredDescription
identity_idstringNoOptional; 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

FieldTypeRequiredDescription
namestringNoNew name.
descriptionstringNoNew description.
configEnvironment configNoReplaces the saved configuration in full. It must not be null; an explicit null returns 400. See schemas for field details.
metadataobjectNoEnvironment 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

curl -X POST "https://api.qoder.com/api/v1/forward/environments/env_xxx" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"dev-env-updated"}'

Example response

HTTP 200 OK
{
  "id": "env_xxx",
  "type": "environment",
  "name": "dev-env",
  "description": "Development environment",
  "config": {"type": "cloud"},
  "metadata": {"source": "console"},
  "created_at": "2026-07-23T10:00:00Z",
  "updated_at": "2026-07-23T10:00:00Z",
  "identity_id": null
}

Response fields

The response is an Environment object.

Errors

HTTPTypeTrigger
400invalid_request_errorThe request body, path parameters, or query parameters are invalid. Also returned if SAT explicitly includes identity_id.
400invalid_request_errorconfig.storage.buckets is invalid (including more than 7 buckets), the x-qoder-beta header is missing, or the trial mount is denied when saving.
400invalid_request_errorIf the reserved key created_by is supplied, message is metadata key "created_by" is reserved, identifying the invalid field.
401authentication_errorThe authentication token is missing or invalid.
403permission_errorOwner mismatch for a PAT without identity_id or an Admin SAT, or other insufficient permissions.
404not_found_errorThe 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.
503feature_not_availableThe account is not eligible for the oss_bucket Beta.
503api_errorOSS / STS is temporarily unavailable when saving. Retry the request.
500/502/503api_errorForward or a dependent service failed.