Send message (async)

import requests

url = "https://eu.app.clarifeye.ai/api/v1/projects/{project_id}/playground-conversations/{conversation_id}/send_message/"

payload = {
    "message": "What information do you have about product pricing?",
    "newly_attached_document_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    message: 'What information do you have about product pricing?',
    newly_attached_document_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a']
  })
};

fetch('https://eu.app.clarifeye.ai/api/v1/projects/{project_id}/playground-conversations/{conversation_id}/send_message/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://eu.app.clarifeye.ai/api/v1/projects/{project_id}/playground-conversations/{conversation_id}/send_message/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "What information do you have about product pricing?",
  "newly_attached_document_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "turn_error": "<string>",
  "turn_events": [
    {
      "type_streaming": "<string>",
      "payload": {}
    }
  ],
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "error": "User not found"
}

{
  "error": "Authentication credentials were not provided."
}

{
  "error": "You do not have permission to perform this action."
}

{
  "error": "Not found."
}

Conversations

Send message (async)

Enqueue a chat turn and return 202 Accepted. The turn runs in a background Celery task; poll the poll endpoint for progress and the final result. This replaces the former SSE send_message_stream endpoint.

Use this endpoint for both initial and follow-up messages — conversation context is automatically preserved.

Access Control:

For shared conversations, only the creator or admins can send messages
Other project members can view shared conversations but cannot send messages

Impersonation:

When using impersonation, the message is sent as the impersonated user

POST

projects

{project_id}

playground-conversations

{conversation_id}

send_message

Send message (async)

import requests

url = "https://eu.app.clarifeye.ai/api/v1/projects/{project_id}/playground-conversations/{conversation_id}/send_message/"

payload = {
    "message": "What information do you have about product pricing?",
    "newly_attached_document_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    message: 'What information do you have about product pricing?',
    newly_attached_document_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a']
  })
};

fetch('https://eu.app.clarifeye.ai/api/v1/projects/{project_id}/playground-conversations/{conversation_id}/send_message/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://eu.app.clarifeye.ai/api/v1/projects/{project_id}/playground-conversations/{conversation_id}/send_message/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "What information do you have about product pricing?",
  "newly_attached_document_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "turn_error": "<string>",
  "turn_events": [
    {
      "type_streaming": "<string>",
      "payload": {}
    }
  ],
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "error": "User not found"
}

{
  "error": "Authentication credentials were not provided."
}

{
  "error": "You do not have permission to perform this action."
}

{
  "error": "Not found."
}

Authorizations

Authorization

string

header

required

Use Authorization: Bearer

Headers

X-Impersonate-Email

string<email>

Email of the user to impersonate. Requires CAN_IMPERSONATE_OTHER_USERS permission. If the target user is not found or does not have access to the project, the request proceeds as the authenticated user. Contact Clarifeye to enable this permission.

Path Parameters

project_id

string<uuid>

required

UUID of the project

conversation_id

string<uuid>

required

UUID of the conversation

Body

application/json

Either message or a non-empty newly_attached_document_ids must be provided. An attachments-only send (empty message + ids) is accepted: the server synthesizes a short "(I've attached …)" message from the ids.

message

string

The user message to send (may be empty when files are attached)

Example:

"What information do you have about product pricing?"

newly_attached_document_ids

string<uuid>[]

Ids of LocalDocuments attached on the composer for this turn. The files already reach the agent via context files; these are also used to render clickable file chips on the user's message in the conversation history.

Response

Turn accepted and enqueued; poll for progress

In-flight turn state returned by the async send_message (202) and poll endpoints for playground and Work-with-Clara conversations.

string<uuid>

turn_status

enum<string>

Lifecycle of the current chat turn

Available options:

idle,

running,

failed

turn_error

string

Failure detail when turn_status is failed (empty otherwise)

turn_events

object[]

Accumulated message-level events for the current turn. Each item mirrors a former SSE frame: {type_streaming, payload} where type_streaming is one of streaming_in_progress, streaming_error, streaming_completed, or quick_replies_ready (Clara only).

Show child attributes

updated_at

string<date-time>

Last activity timestamp; doubles as the turn staleness heartbeat

Permanently delete conversation Poll turn status

Concepts

Endpoints

Send message (async)

Authorizations

Headers

Path Parameters

Body

Response