Skip to main content
POST
Create Session
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 for the old -> new path table.
Create a new session that can be used to maintain conversation context across multiple API calls.

Base URL

Create Session

Path Parameters

string
required
The ID of your project

Request Headers

string
required
Bearer token authentication using your Project API Key (starts with sk_). Format: Bearer {your-api-key}

Request Body

string
required
A unique identifier for the session. This can be any string you choose to identify the conversation session.
object
Optional initial session variables that can be used within the pathway. These variables can be referenced in your pathway configuration.
string
Optional provider specification for the session (e.g., “api”, “web”)

Response

string
The created session ID (same as the one provided in the request)
string
The pathway ID for this project

Example

Request

Response

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

Example error responses: 400 Bad Request:
401 Unauthorized:
  • End Session - End an existing session when the conversation is complete