Create a Forward session from an Identity and Template.
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. |
auto_title | boolean | No | Whether the system automatically generates the session title. Defaults to false. When set to true, title is empty in the create response. After the first user.message is sent, the system sets a temporary title and generates the final title asynchronously. Do not pass title (including "" and null) in this case, or the API returns HTTP 400. |
metadata | object | No | Custom metadata. |
budget | object | null | No | Cumulative Credit limit over the Session lifecycle. Omit or pass null for no limit. See Session budget for the object format. |
budget.type | string | Required when budget is an object | Always limit. |
budget.max_credit_cost | string | Required when budget is an object | Positive decimal amount string in the range 0.01–999999999999.99, with at most two decimal places, for example "100.00". |
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. |
config.environment_variables:
- Forward first compiles the Template
environment_variablesbaseline 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
nullfor the field, a non-object type (except the legacy string format), or a nested object or array value returns HTTP 400invalid_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. |
- 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
nullor{}: returns HTTP 400. To inherit the model when creating a Session, omit this field. A model object must contain a non-emptyid.
template.model is the template summary. See config.model in the response for the Session model override.
Example request
title):
Example response
HTTP 200 OK
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. |
budget | object | Optional budget limit confirmed by the runtime; omitted when no limit is set. See Session budget for the format. |
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. |
| 400 | invalid_request_error | invalid_request | title was passed while auto_title was set to true. |
| 400 | invalid_request_error | - | Invalid budget type, amount, or 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. |
error.code or error.param. For invalid input types, error.message may include decoding details; clients should not depend on the internal type names in it.
Notes
source_typeis assigned by Forward and is not accepted in the create request.- The title generated by
auto_titleis saved to the Session’stitleand can be viewed by getting or listing Sessions. If you settitleby updating the Session before generation, the system does not overwrite it. incremental_streaming_enabledis 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 useevent_deltas[]when subscribing to the Session Event Stream. If this field is set totrue,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 (
nullbecomes an empty string). LegacyAPP_ID=demo-app;DEBUG=trueor newline-separated string input is still supported. For new integrations, use an object with string values.