Skip to main content

Create a session

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

HeaderRequiredDescription
AuthorizationYesBearer <PAT or SAT>
Content-TypeYesapplication/json
Idempotency-KeyNoOptional idempotency key for unsafe requests.

Body parameters

ParameterTypeRequiredDescription
identity_idstringYesForward Identity ID.
template_idstringYesForward Template ID.
titlestringNoSession title.
auto_titlebooleanNoWhether 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.
metadataobjectNoCustom metadata.
budgetobject | nullNoCumulative Credit limit over the Session lifecycle. Omit or pass null for no limit. See Session budget for the object format.
budget.typestringRequired when budget is an objectAlways limit.
budget.max_credit_coststringRequired when budget is an objectPositive decimal amount string in the range 0.01–999999999999.99, with at most two decimal places, for example "100.00".
configobjectNoPer-session configuration override. Allows environment_variables and model; must be a non-null object. Omission and {} are valid.
config.environment_variablesobject<string, string> (recommended)NoSession 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.modelstring | objectNoSession-level model override. See config.model. If omitted, inherits the effective Template and Identity Config model.
resourcesarrayNoSession-level resources, currently file mounts.
resources[].typestringYes when resources is usedResource type. Currently file.
resources[].file_idstringYes when resources is usedFile ID from the Files API.
resources[].mount_pathstringNoMount 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 fieldTypeRequiredDescription
idstringYesNon-empty model ID from the id returned by List models.
effortstringNoReasoning effort: none, low, medium, high, xhigh, or max. Supported levels are defined by the model's efforts; if omitted, the model default is used.
speedstringNoInference speed: standard or high; defaults to standard. Supported speeds are defined by the model's speed array.
context_windowintegerNoContext 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/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",
  "budget": {
    "type": "limit",
    "max_credit_cost": "100.00"
  },
  "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"
    }
  ]
}'
Automatically generate a title (mutually exclusive with title):
curl -s -X POST 'https://api.qoder.com/api/v1/forward/sessions' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "identity_id": "idn_xxx",
  "template_id": "tmpl_support",
  "auto_title": true
}'

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
  },
  "budget": {
    "type": "limit",
    "max_credit_cost": "100.00"
  },
  "outcome_evaluations": [],
  "archived_at": null,
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T10:00:00Z"
}

Response fields

FieldTypeDescription
idstringSession ID.
typestringAlways session.
identity_idstringForward Identity ID.
templateobjectTemplate summary.
source_typestringSession source. Direct API creation uses api.
statusstringidle, running, rescheduling, canceling, or terminated.
budgetobjectOptional budget limit confirmed by the runtime; omitted when no limit is set. See Session budget for the format.
archived_atstring|nullArchive timestamp.
created_atstringCreation timestamp.
updated_atstringUpdate timestamp.
config.modelstring | objectThe saved Session model override retains its string or object form; omitted when no override is set.

Errors

HTTPTypeCodeTrigger
400invalid_request_errorinvalid_request_bodyInvalid request body, including invalid config.environment_variables.
400invalid_request_errorinvalid_requestInvalid config.model (including null, {}, an empty ID, or invalid types or parameters), or unsupported configuration fields.
400invalid_request_errorinvalid_requesttitle was passed while auto_title was set to true.
400invalid_request_error-Invalid budget type, amount, or fields.
403permission_errortemplate_access_deniedIdentity cannot use the Template.
404not_found_erroridentity_not_foundIdentity does not exist or is deleted.
404not_found_errortemplate_not_foundTemplate does not exist.
409conflict_erroridentity_disabledIdentity is disabled.
401authentication_error-The PAT or SAT is invalid or expired.
Budget validation errors do not include 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_type is assigned by Forward and is not accepted in the create request.
  • The title generated by auto_title is saved to the Session’s title and can be viewed by getting or listing Sessions. If you set title by updating the Session before generation, the system does not overwrite it.
  • 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.