Skip to main content
POST /api/v1/forward/sessions Creates a session by compiling the Template baseline with the Identity Config override, then starting a runtime Session.

​
Headers

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

​
Body parameters

ParameterTypeRequiredDescription
identity_idstringYesForward Identity ID.
template_idstringYesForward Template ID.
titlestringNoSession title.
incremental_streaming_enabledbooleanNoEnables assistant incremental streaming events. Defaults to false.
metadataobjectNoCustom metadata.
configobjectNoPer-session configuration override. Only allowlisted fields are accepted.
config.environment_variablesobjectNoSession environment variables as key-value pairs.
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.

​
Example request

curl -s -X POST 'https://api.qoder.com/api/v1/forward/sessions' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": "idn_xxx",
    "template_id": "tmpl_support",
    "title": "Customer support session",
    "incremental_streaming_enabled": true,
    "metadata": {
      "source": "web",
      "biz_id": "ticket_123"
    },
    "config": {
      "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",
  "incremental_streaming_enabled": true,
  "metadata": {
    "source": "web",
    "biz_id": "ticket_123"
  },
  "config": {
    "environment_variables": {
      "API_KEY": "sk-xxx"
    }
  },
  "stats": {
    "active_seconds": 0,
    "duration_seconds": 0
  },
  "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.
incremental_streaming_enabledbooleanWhether incremental streaming is enabled for this session.
archived_atstring|nullArchive timestamp.
created_atstringCreation timestamp.
updated_atstringUpdate timestamp.

​
Errors

HTTPTypeCodeTrigger
400invalid_request_errorinvalid_request_bodyInvalid request body.
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.
422invalid_request_errorruntime_config_invalidEffective runtime config is invalid.

​
Notes

  • source_type is assigned by Forward and is not accepted in the create request.
  • incremental_streaming_enabled is persisted on the Session and cannot be changed later.
  • Uploaded files must already exist in the Files API before being passed in resources.

Send session events

Stream session events