Create Session

Create a new session within a conversation. Provide a session ID, owner information, and at least one initial participant.

URI: /api/v1/agentic/conversations/{conversationId}/sessions

Format: application/json

HTTP Method: POST

Authentication: Bearer JWT

Path Parameters

Parameter	Required	Description
conversationId	Yes	Conversation identifier.

Request Headers

Header	Required	Description
Authorization	Yes	Bearer JWT token.
agent_id	Yes	Registered agent API name.

Request Body Schema

Field	Type	Required	Description
sessionId	String	Yes	Caller-supplied unique identifier for this session.
conversationOwnerId	String	Yes	Individual or User ID. Must align with parent conversation.
ownerType	String	Yes	Type of owner. Values: `individual`, `employee`.
participants	Array	Yes	Initial participant set. Minimum 1 participant required.
participants[].id	String	Yes	Participant identifier.
participants[].type	String	Yes	Participant type. Values: `individual`, `employee`, `agent`, or free-form string.
participants[].role	String	Yes	Participant role. Values: `owner`, `participant`.
participants[].startTime	String (ISO 8601)	No	Join time.
participants[].endTime	String (ISO 8601)	No	Leave time. Null indicates active participation.
participants[].orgId	String	No	Organization ID for cross-org handoffs.
variable	Map	No	Arbitrary metadata.

Example Request

1{
2  "sessionId": "sess-9001",
3  "conversationOwnerId": "003AB000000XYZ",
4  "ownerType": "individual",
5  "participants": [
6    {
7      "id": "003AB000000XYZ",
8      "type": "individual",
9      "role": "owner",
10      "startTime": "2026-01-01T00:00:00Z"
11    }
12  ],
13  "variable": {}
14}

Response Body Schema

Field	Type	Description
statusCode	String	Operation status. Value: `created`.
conversationId	String	Parent conversation identifier.
sessionId	String	The created session identifier.

Example Response

Status: 201 Created

1{
2  "statusCode": "created",
3  "conversationId": "conv-2025-001",
4  "sessionId": "sess-9001"
5}

Error Codes

Status Code	Description
400	Bad Request. Invalid request format or missing required fields.
401	Unauthorized. Invalid or missing JWT token.
404	Not Found. Conversation does not exist.
500	Internal Server Error.

DID THIS ARTICLE SOLVE YOUR ISSUE?
Let us know so we can improve!