Create an Environment

Description

Creates a runtime environment configuration for Agent Sessions.

Path

POST /api/v1/forward/environments

Request headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT or SAT>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Recommended for create requests. The same key and request can be retried safely.

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	Yes	Environment name. It must not be empty after trimming leading and trailing whitespace.
`description`	string	No	Description.
`config`	Environment config	No	Environment runtime configuration. Defaults to `{"type":"cloud"}` when omitted. When provided explicitly, it must not be `null` or an empty object. See schemas for field details.
`metadata`	object	No	Environment metadata. Defaults to `{}` when omitted and must not be `null` when provided explicitly.

The Environment config schema defines the config subfields (type, packages, and setup_script) and their constraints. A self_hosted Environment accepts only type and an optional setup_script; a cloud Environment can also declare packages.

Example request

curl -sS --fail-with-body \
  -X POST "https://api.qoder.com/api/v1/forward/environments" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dev-env",
    "description": "Development environment",
    "config": {
      "type": "cloud"
    },
    "metadata": {
      "source": "console"
    }
  }'

Request with packages and a setup script

curl -sS --fail-with-body \
  -X POST "https://api.qoder.com/api/v1/forward/environments" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-test-env-with-setup",
    "config": {
      "type": "cloud",
      "packages": {
        "npm": ["pnpm@9"]
      },
      "setup_script": "set -euo pipefail\n[ -d /workspace/.git ] || git clone https://github.com/me/repo /workspace\ncd /workspace && pnpm install --frozen-lockfile"
    }
  }'

Example response

HTTP 201 Created

{
  "id": "env_xxx",
  "type": "environment",
  "name": "dev-env",
  "description": "Development environment",
  "config": {
    "type": "cloud",
    "packages": {
      "type": "packages",
      "apt": [],
      "cargo": [],
      "gem": [],
      "go": [],
      "npm": [],
      "pip": []
    }
  },
  "metadata": {
    "source": "console"
  },
  "archived_at": null,
  "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. config is normalized to its complete shape. For a cloud Environment, config.packages includes empty arrays for every reserved key in Environment packages.

Errors

HTTP	Type	Trigger
400	`invalid_request_error`	`name` is missing or empty, the request body is not valid JSON, or `config` / `metadata` violates the constraints above. Also returned if SAT explicitly includes `identity_id`.
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`	`identity_id` is invalid, disabled, or does not belong to the caller, or the target resource does not belong to the current Identity scope.
409	`conflict_error`	The `Idempotency-Key` maps to a different request, or creation is in an intermediate state that requires manual recovery.
413	`invalid_request_error`	The request body exceeds the service limit.
429	`rate_limit_error`	The caller exceeded the API rate limit.
500/502/503	`api_error`	Forward or a dependent service failed.

​Description

​Path

​Request headers

​Query parameters

​Request body

​Example request

​Request with packages and a setup script

​Example response

​Response fields

​Errors