> ## 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.

# 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 starting a runtime Session.

## Headers

| Header            | Required | Description                                   |
| ----------------- | -------- | --------------------------------------------- |
| `Authorization`   | Yes      | `Bearer <PAT>`                                |
| `Content-Type`    | Yes      | `application/json`                            |
| `Idempotency-Key` | No       | Optional idempotency key for unsafe requests. |

## Body parameters

| Parameter                       | Type    | Required                     | Description                                                                               |
| ------------------------------- | ------- | ---------------------------- | ----------------------------------------------------------------------------------------- |
| `identity_id`                   | string  | Yes                          | Forward Identity ID.                                                                      |
| `template_id`                   | string  | Yes                          | Forward Template ID.                                                                      |
| `title`                         | string  | No                           | Session title.                                                                            |
| `incremental_streaming_enabled` | boolean | No                           | Enables assistant incremental streaming events. Defaults to `false`.                      |
| `metadata`                      | object  | No                           | Custom metadata.                                                                          |
| `config`                        | object  | No                           | Per-session configuration override. Only allowlisted fields are accepted.                 |
| `config.environment_variables`  | object  | No                           | Session environment variables as key-value pairs.                                         |
| `resources`                     | array   | No                           | Session-level resources, currently file mounts.                                           |
| `resources[].type`              | string  | Yes when `resources` is used | Resource type. Currently `file`.                                                          |
| `resources[].file_id`           | string  | Yes when `resources` is used | File ID from the Files API.                                                               |
| `resources[].mount_path`        | string  | No                           | Mount path inside the agent container. If omitted, Forward derives one from the filename. |

## 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       | Always `session`.                                                |
| `identity_id`                   | string       | Forward Identity ID.                                             |
| `template`                      | object       | Template summary.                                                |
| `source_type`                   | string       | Session source. Direct API creation uses `api`.                  |
| `status`                        | string       | `idle`, `running`, `rescheduling`, `canceling`, or `terminated`. |
| `incremental_streaming_enabled` | boolean      | Whether incremental streaming is enabled for this session.       |
| `archived_at`                   | string\|null | Archive timestamp.                                               |
| `created_at`                    | string       | Creation timestamp.                                              |
| `updated_at`                    | string       | Update timestamp.                                                |

## Errors

| HTTP | Type                    | Code                     | Trigger                                |
| ---- | ----------------------- | ------------------------ | -------------------------------------- |
| 400  | `invalid_request_error` | `invalid_request_body`   | Invalid request body.                  |
| 403  | `permission_error`      | `template_access_denied` | Identity cannot use the Template.      |
| 404  | `not_found_error`       | `identity_not_found`     | Identity does not exist or is deleted. |
| 404  | `not_found_error`       | `template_not_found`     | Template does not exist.               |
| 409  | `conflict_error`        | `identity_disabled`      | Identity is disabled.                  |
| 422  | `invalid_request_error` | `runtime_config_invalid` | Effective 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`.

## Related

<CardGroup cols={2}>
  <Card title="Send session events" icon="paper-plane" href="/cloud-agents/api/forward/sessions/send-events" />

  <Card title="Stream session events" icon="radio" href="/cloud-agents/api/forward/sessions/stream-events" />
</CardGroup>