Create a session

POST /api/v1/forward/sessions Creates a session by compiling the Template baseline with the Identity Config override, then applying the configuration for this Session and starting a runtime Session.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT or SAT>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Optional idempotency key for unsafe requests.

Body parameters

Parameter	Type	Required	Description
`identity_id`	string	Yes	Forward Identity ID.
`template_id`	string	Yes	Forward Template ID.
`title`	string	No	Session title.
`metadata`	object	No	Custom metadata.
`config`	object	No	Per-session configuration override. Allows `environment_variables` and `model`; must be a non-null object. Omission and `{}` are valid.
`config.environment_variables`	`object<string, string>` (recommended)	No	Session environment variables. For new integrations, pass every value as a string. They are merged on top of the compiled Template + Identity Config result; Session-level values override base-layer values with the same key.
`config.model`	string \| object	No	Session-level model override. See config.model. If omitted, inherits the effective Template and Identity Config model.
`resources`	array	No	Session-level resources, currently file mounts.
`resources[].type`	string	Yes when `resources` is used	Resource type. Currently `file`.
`resources[].file_id`	string	Yes when `resources` is used	File ID from the Files API.
`resources[].mount_path`	string	No	Mount path inside the agent container. If omitted, Forward derives one from the filename.

Merge semantics for config.environment_variables:

Forward first compiles the Template environment_variables baseline and the Identity Config override layer to produce the base environment variables.
Key-value pairs supplied in the request are added to the base environment variables. New keys are added, while Session-level values override base-layer values with the same key.
Variables omitted from the request remain in the compiled Template + Identity Config result.
You may omit the field or pass an empty object {}. Use strings for values.
An explicit null for the field, a non-object type (except the legacy string format), or a nested object or array value returns HTTP 400 invalid_request_body.

config.model

config.model accepts a non-empty model ID string (for example, "ultimate") or an object containing a model ID and optional tuning parameters, using the same format as Template / Identity Config. See List models for available models and supported options.

Object field	Type	Required	Description
id	string	Yes	Non-empty model ID from the `id` returned by List models.
effort	string	No	Reasoning effort: `none`, `low`, `medium`, `high`, `xhigh`, or `max`. Supported levels are defined by the model's `efforts`; if omitted, the model default is used.
speed	string	No	Inference speed: `standard` or `high`; defaults to `standard`. Supported speeds are defined by the model's `speed` array.
context_window	integer	No	Context window in tokens. Must be a positive integer selected from the model's `available_context_windows`; if omitted, the model default window is used.

The available model and option combinations depend on the capabilities returned by List models and runtime validation.

Omit config.model: inherit the effective Template / Identity Config model.
Pass a string or object: override the entire model for this Session. Omitted tuning parameters use the selected model's defaults.
Pass null or {}: returns HTTP 400. To inherit the model when creating a Session, omit this field. A model object must contain a non-empty id.

template.model is the template summary. See config.model in the response for the Session model override.

Example request

curl -s -X POST 'https://api.qoder.com.cn/api/v1/forward/sessions' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "identity_id": "idn_xxx",
  "template_id": "tmpl_support",
  "title": "Customer support session",
  "metadata": {
    "source": "web",
    "biz_id": "ticket_123"
  },
  "config": {
    "model": {
      "id": "ultimate",
      "effort": "high",
      "context_window": 200000
    },
    "environment_variables": {
      "API_KEY": "sk-xxx",
      "REGION": "cn-hangzhou"
    }
  },
  "resources": [
    {
      "type": "file",
      "file_id": "file_019e6a18dc09abcd",
      "mount_path": "/data/input.py"
    }
  ]
}'

Example response

HTTP 200 OK

{
  "id": "sess_xxx",
  "type": "session",
  "identity_id": "idn_xxx",
  "template": {
    "id": "tmpl_support",
    "type": "template",
    "name": "Support assistant",
    "model": "ultimate",
    "version": 3
  },
  "source_type": "api",
  "status": "idle",
  "title": "Customer support session",
  "metadata": {
    "source": "web"
  },
  "config": {
    "model": {
      "id": "ultimate",
      "effort": "high",
      "context_window": 200000
    },
    "environment_variables": {
      "API_KEY": "sk-xxx"
    }
  },
  "stats": {
    "active_seconds": 0,
    "duration_seconds": 0
  },
  "usage": {
    "total_credits": 0
  },
  "outcome_evaluations": [],
  "archived_at": null,
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T10:00:00Z"
}

Response fields

Field	Type	Description
`id`	string	Session ID.
`type`	string	Always `session`.
`identity_id`	string	Forward Identity ID.
`template`	object	Template summary.
`source_type`	string	Session source. Direct API creation uses `api`.
`status`	string	`idle`, `running`, `rescheduling`, `canceling`, or `terminated`.
`archived_at`	string\|null	Archive timestamp.
`created_at`	string	Creation timestamp.
`updated_at`	string	Update timestamp.
`config.model`	string \| object	The saved Session model override retains its string or object form; omitted when no override is set.

Errors

HTTP	Type	Code	Trigger
400	`invalid_request_error`	`invalid_request_body`	Invalid request body, including invalid `config.environment_variables`.
400	`invalid_request_error`	`invalid_request`	Invalid `config.model` (including `null`, `{}`, an empty ID, or invalid types or parameters), or unsupported configuration fields.
403	`permission_error`	`template_access_denied`	Identity cannot use the Template.
404	`not_found_error`	`identity_not_found`	Identity does not exist or is deleted.
404	`not_found_error`	`template_not_found`	Template does not exist.
409	`conflict_error`	`identity_disabled`	Identity is disabled.
401	`authentication_error`	-	The PAT or SAT is invalid or expired.

Notes

source_type is assigned by Forward and is not accepted in the create request.
incremental_streaming_enabled is a legacy streaming toggle retained for backward compatibility. It is not recommended for new integrations and cannot be changed after creation. New integrations that need streaming output should use event_deltas[] when subscribing to the Session Event Stream. If this field is set to true, event_deltas[] does not take effect.
Uploaded files must already exist in the Files API before being passed in resources.
For compatibility with existing calls only, non-string scalar values are normalized to strings (null becomes an empty string). Legacy APP_ID=demo-app;DEBUG=true or newline-separated string input is still supported. For new integrations, use an object with string values.

Create a session

Headers

Body parameters

config.model

Example request

Example response

Response fields

Errors

Notes

Send session events

Stream session events

​Headers

​Body parameters

​config.model

​Example request

​Example response

​Response fields

​Errors

​Notes

​Related

Send session events

Stream session events

Headers

Body parameters

config.model

Example request

Example response

Response fields

Errors

Notes

Related