> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# セッションの作成

> Identity と Template から Forward セッションを作成します。

`POST /api/v1/forward/sessions`

Template のベースラインと Identity Config のオーバーライドをコンパイルしてから、ランタイム Session を起動することでセッションを作成します。

## Headers

| Header            | Required | Description            |
| ----------------- | -------- | ---------------------- |
| `Authorization`   | Yes      | `Bearer <PAT>`         |
| `Content-Type`    | Yes      | `application/json`     |
| `Idempotency-Key` | No       | 安全でないリクエスト向けの任意の冪等性キー。 |

## Body parameters

| Parameter                       | Type    | Required                     | Description                                      |
| ------------------------------- | ------- | ---------------------------- | ------------------------------------------------ |
| `identity_id`                   | string  | Yes                          | Forward Identity ID。                             |
| `template_id`                   | string  | Yes                          | Forward Template ID。                             |
| `title`                         | string  | No                           | セッションのタイトル。                                      |
| `incremental_streaming_enabled` | boolean | No                           | アシスタントの増分ストリーミングイベントを有効にします。既定値は `false`。        |
| `metadata`                      | object  | No                           | カスタムメタデータ。                                       |
| `config`                        | object  | No                           | セッションごとの構成オーバーライド。許可リストに含まれるフィールドのみ受け付けられます。     |
| `config.environment_variables`  | object  | No                           | キーと値のペアで指定するセッション環境変数。                           |
| `resources`                     | array   | No                           | セッションレベルのリソース。現在はファイルマウント。                       |
| `resources[].type`              | string  | Yes when `resources` is used | リソースの種類。現在は `file`。                              |
| `resources[].file_id`           | string  | Yes when `resources` is used | Files API のファイル ID。                              |
| `resources[].mount_path`        | string  | No                           | エージェントコンテナ内のマウントパス。省略した場合、Forward がファイル名から導出します。 |

## Example request

```bash theme={null}
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**

```json theme={null}
{
  "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       | 常に `session`。                                                 |
| `identity_id`                   | string       | Forward Identity ID。                                          |
| `template`                      | object       | Template の概要。                                                 |
| `source_type`                   | string       | セッションのソース。直接 API で作成した場合は `api`。                              |
| `status`                        | string       | `idle`、`running`、`rescheduling`、`canceling`、または `terminated`。 |
| `incremental_streaming_enabled` | boolean      | このセッションで増分ストリーミングが有効かどうか。                                     |
| `archived_at`                   | string\|null | アーカイブのタイムスタンプ。                                                |
| `created_at`                    | string       | 作成日時のタイムスタンプ。                                                 |
| `updated_at`                    | string       | 更新日時のタイムスタンプ。                                                 |

## Errors

| HTTP | Type                    | Code                     | Trigger                      |
| ---- | ----------------------- | ------------------------ | ---------------------------- |
| 400  | `invalid_request_error` | `invalid_request_body`   | リクエストボディが無効。                 |
| 403  | `permission_error`      | `template_access_denied` | Identity が Template を使用できない。 |
| 404  | `not_found_error`       | `identity_not_found`     | Identity が存在しないか削除済み。        |
| 404  | `not_found_error`       | `template_not_found`     | Template が存在しない。             |
| 409  | `conflict_error`        | `identity_disabled`      | Identity が無効化されている。          |
| 422  | `invalid_request_error` | `runtime_config_invalid` | 実効ランタイム構成が無効。                |

## Notes

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

## Related

<CardGroup cols={2}>
  <Card title="セッションイベントの送信" icon="paper-plane" href="/cloud-agents/api/forward/sessions/send-events" />

  <Card title="セッションイベントのストリーミング" icon="radio" href="/cloud-agents/api/forward/sessions/stream-events" />
</CardGroup>