Create a new conversation entity. Provide a unique conversation ID, ownership information, and optional metadata.
URI: /api/v1/agentic/conversations
Format: application/json
HTTP Method: POST
Authentication: Bearer JWT
Prerequisites
- Register the agent in Data 360.
- Obtain a valid JWT token with the required permissions.
- Configure a data space for Agentic Memory.
Request Headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer JWT token. |
| agent_id | Yes | Registered agent API name. |
| Content-Type | Yes | application/json. |
Request Body Schema
| Field | Type | Required | Description |
|---|---|---|---|
| conversationId | String | Yes | Caller-supplied unique identifier for this conversation. |
| conversationOwnerId | String | Yes | Individual or User ID of the conversation owner. |
| ownerType | String | Yes | Type of owner. Values: individual, employee. |
| name | String | No | Human-readable name for the conversation. |
| channel | Object | No | Communication channel information. Contains type (web, chat, voice, sms, email, other) and id. |
| variable | Map | No | Arbitrary string key-value metadata. |
Example Request
{
"conversationId": "conv-2025-001",
"conversationOwnerId": "003AB000000XYZ",
"ownerType": "individual",
"name": "Support — onboarding",
"channel": { "type": "chat", "id": "slack-C0123" }
}
Response Body Schema
| Field | Type | Description |
|---|---|---|
| statusCode | String | Operation status. Value: created. |
| conversationId | String | The created conversation identifier. |
Example Response
Status: 201 Created
{
"statusCode": "created",
"conversationId": "conv-2025-001"
}
Error Codes
| Status Code | Description |
|---|---|
| 400 | Bad Request. Invalid request format or missing required fields. |
| 401 | Unauthorized. Invalid or missing JWT token. |
| 500 | Internal Server Error. |