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

# Create Session

> Create a new session with optional initial variables for conversation continuity.

<Warning>
  **Deprecated.** This endpoint is deprecated and will be **sunset on 2026-07-11**. It still works until then. Migrate to the V1 path -- see the [migration guide](/en/migrations/2026-06-outbound-api-v1) for the old -> new path table.
</Warning>

Create a new session that can be used to maintain conversation context across multiple API calls.

## Base URL

```
https://api.pathors.com
```

## Create Session

```bash theme={null}
POST https://api.pathors.com/project/{projectId}/session
```

### Path Parameters

<ParamField path="projectId" type="string" required>
  The ID of your project
</ParamField>

### Request Headers

<ParamField header="Authorization" type="string" required>
  Bearer token authentication using your Project API Key (starts with `sk_`). Format: `Bearer {your-api-key}`
</ParamField>

### Request Body

<ParamField body="session_id" type="string" required>
  A unique identifier for the session. This can be any string you choose to identify the conversation session.
</ParamField>

<ParamField body="variables" type="object">
  Optional initial session variables that can be used within the pathway. These variables can be referenced in your pathway configuration.
</ParamField>

<ParamField body="provider" type="string">
  Optional provider specification for the session (e.g., "api", "web")
</ParamField>

### Response

<ResponseField name="sessionId" type="string">
  The created session ID (same as the one provided in the request)
</ResponseField>

<ResponseField name="pathwayId" type="string">
  The pathway ID for this project
</ResponseField>

## Example

### Request

```bash theme={null}
curl -X POST https://api.pathors.com/project/{projectId}/session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "session_id": "user-123-session-456",
    "variables": {
      "userName": "John Doe",
      "userRole": "admin",
      "customData": "value"
    },
    "provider": "api"
  }'
```

### Response

```json theme={null}
{
  "sessionId": "user-123-session-456",
  "pathwayId": "project-id-xxx"
}
```

## Usage Notes

* **Session ID**: Choose a unique identifier for each conversation. This could be a UUID, user ID + timestamp, or any other unique string.
* **Variables**: Session variables can be used within your pathway logic. They persist throughout the session and can be referenced in conversation flows.
* **Reusability**: Once created, the session can be used in multiple completion requests by including the `session_id` parameter or `X-Session-ID` header.

## Error Responses

| Status Code | Description                    |
| ----------- | ------------------------------ |
| 400         | Missing or invalid session\_id |
| 401         | Invalid authentication         |
| 500         | Internal server error          |

Example error responses:

**400 Bad Request:**

```json theme={null}
{
  "error": "session_id is required"
}
```

**401 Unauthorized:**

```json theme={null}
{
  "error": {
    "message": "Invalid authentication"
  }
}
```

## Related APIs

* [End Session](/api-reference/session/end-session) - End an existing session when the conversation is complete