Skip to main content
Sessions

Create a session

Creates a Forward session by binding an Identity to a Template.

Request headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT>
Content-TypeYesapplication/json
Idempotency-KeyNoIdempotency key for requests with side effects.

Request body

ParameterTypeRequiredDescription
identity_idstringYesForward Identity ID.
template_idstringYesForward Template ID.
titlestringNoSession title.
incremental_streaming_enabledbooleanNoEnables incremental streaming for assistant 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 supports file mounts only.
resources[].typestringYes when resources is usedResource type. Currently only file is supported.
resources[].file_idstringYes when resources is usedFile ID from the Files API.
resources[].mount_pathstringNoMount path inside the agent container. If omitted, Forward derives the path from the filename.

Example request

curl -s -X POST 'https://api.qoder.com.cn/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

Field

Type

Description

id

string

Session ID.

type

string

Always session.

identity_id

string

Forward Identity ID.

template

object

Template summary.

source_type

string

How the session was created. Direct API creation returns api.

status

string

idle, running, rescheduling, canceling, or terminated.

incremental_streaming_enabled

boolean

Whether incremental streaming is enabled.

archived_at

string|null

Archive timestamp.

created_at

string

Creation timestamp.

updated_at

string

Update timestamp.

Errors

HTTPTypeCodeTrigger
400invalid_request_errorinvalid_request_bodyThe request body is invalid.
403permission_errortemplate_access_deniedIdentity does not have access to the specified 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_invalidThe effective runtime configuration is invalid.
401authentication_errorauthentication_requiredThe PAT is invalid or expired.

Notes

  • source_type is assigned by Forward and cannot be set in the request.
  • incremental_streaming_enabled is set at session creation and cannot be changed afterward.
  • Files must be uploaded through the Files API before you reference them in resources.
Guides
Tutorials
API Reference