Create conversation

Create a new AI-powered conversation.

Impersonation:

• When using impersonation, the conversation is created as the impersonated user

POST /projects/{project_id}/playground-conversations

Create conversation

Python

import requests

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

payload = {
    "agent_settings": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Analysis Session",
    "type": "playground",
    "tags": ["analysis", "review"],
    "conversation_instructions": "Focus on financial data extraction"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

201

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "type": "<string>",
  "created_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "chat_history": [
    {
      "role": "user",
      "content": "<string>",
      "type": "message",
      "query_id": 123,
      "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "used_tokens_input": 123,
      "used_tokens_output": 123,
      "timestamp": "2023-11-07T05:31:56Z",
      "tool_type": "<string>",
      "input_parameters": {},
      "results": [
        "<unknown>"
      ]
    }
  ],
  "agent_settings": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_settings_name": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "message_count": 123,
  "tool_call_count": 123,
  "tokens": {
    "input": 123,
    "output": 123,
    "total": 123
  },
  "tags": [
    "<string>"
  ],
  "conversation_instructions": "<string>",
  "is_shared": false,
  "can_send_messages": true,
  "is_archived": false,
  "archived_at": "2023-11-07T05:31:56Z"
}

Authorizations

BearerAuthTokenAuth

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

Body

application/json

agent_settings · string<uuid> · required

ID of the agent settings to use

name · string

Conversation name (auto-generated if not provided)

Example:

"Analysis Session"

type · string · default: playground

Conversation type

tags · string[]

Tags for organizing conversations

Example:

["analysis", "review"]

conversation_instructions · string

Custom instructions for this conversation

Example:

"Focus on financial data extraction"

Response

201

application/json

Conversation created successfully

id · string<uuid>

name · string

type · string

created_by · string<uuid>

ID of the user who created the conversation

chat_history · object[]

Show child attributes

agent_settings · string<uuid>

agent_settings_name · string

created_at · string<date-time>

updated_at · string<date-time>

message_count · integer

tool_call_count · integer

tokens · object

Show child attributes

tags · string[]

conversation_instructions · string | null

is_shared · boolean · default: false

Whether the conversation is shared with all workspace members

can_send_messages · boolean

Whether the current user can send messages to this conversation. For shared conversations, only the creator and admins can send messages.

is_archived · boolean · default: false

Whether the conversation has been soft-archived

archived_at · string<date-time> | null

Timestamp when the conversation was archived, null if not archived