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
{
"sessionId": "sess-9001",
"conversationOwnerId": "003AB000000XYZ",
"ownerType": "individual",
"participants": [
{
"id": "003AB000000XYZ",
"type": "individual",
"role": "owner",
"startTime": "2026-01-01T00:00:00Z"
}
],
"variable": {}
}
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
{
"statusCode": "created",
"conversationId": "conv-2025-001",
"sessionId": "sess-9001"
}
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. |