メインコンテンツへスキップ
POST /api/v1/forward/sessions Template のベースラインと Identity Config のオーバーライドをコンパイルしてから、ランタイム Session を起動することでセッションを作成します。

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT>
Content-TypeYesapplication/json
Idempotency-KeyNo安全でないリクエスト向けの任意の冪等性キー。

​
Body parameters

ParameterTypeRequiredDescription
identity_idstringYesForward Identity ID。
template_idstringYesForward Template ID。
titlestringNoセッションのタイトル。
incremental_streaming_enabledbooleanNoアシスタントの増分ストリーミングイベントを有効にします。既定値は false。
metadataobjectNoカスタムメタデータ。
configobjectNoセッションごとの構成オーバーライド。許可リストに含まれるフィールドのみ受け付けられます。
config.environment_variablesobjectNoキーと値のペアで指定するセッション環境変数。
resourcesarrayNoセッションレベルのリソース。現在はファイルマウント。
resources[].typestringYes when resources is usedリソースの種類。現在は file。
resources[].file_idstringYes when resources is usedFiles API のファイル ID。
resources[].mount_pathstringNoエージェントコンテナ内のマウントパス。省略した場合、Forward がファイル名から導出します。

​
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。
typestring常に session。
identity_idstringForward Identity ID。
templateobjectTemplate の概要。
source_typestringセッションのソース。直接 API で作成した場合は api。
statusstringidle、running、rescheduling、canceling、または terminated。
incremental_streaming_enabledbooleanこのセッションで増分ストリーミングが有効かどうか。
archived_atstring|nullアーカイブのタイムスタンプ。
created_atstring作成日時のタイムスタンプ。
updated_atstring更新日時のタイムスタンプ。

​
Errors

HTTPTypeCodeTrigger
400invalid_request_errorinvalid_request_bodyリクエストボディが無効。
403permission_errortemplate_access_deniedIdentity が Template を使用できない。
404not_found_erroridentity_not_foundIdentity が存在しないか削除済み。
404not_found_errortemplate_not_foundTemplate が存在しない。
409conflict_erroridentity_disabledIdentity が無効化されている。
422invalid_request_errorruntime_config_invalid実効ランタイム構成が無効。

​
Notes

  • source_type は Forward が割り当てるもので、作成リクエストでは受け付けられません。
  • incremental_streaming_enabled は Session に永続化され、後から変更できません。
  • アップロードするファイルは、resources で渡す前に Files API 上に存在している必要があります。

セッションイベントの送信

セッションイベントのストリーミング