Sign in

v46

latestOpenAPI 3.0.0MITraw.githubusercontent.com2026-08-0311978417.1 KB
Conversations

Create a new conversation

Create a new conversation in the workspace identified by {wId}.

post/api/v1/w/{wId}/assistant/conversations

Path parameters

wIdstring required

ID of the workspace

Request body

titlestring

The title of the conversation

skipToolsValidationboolean

Whether to skip the tools validation of the agent messages triggered by this user message (optional, defaults to false)

blockingboolean

Whether to wait for the agent to generate the initial message. If true the query will wait for the agent's answer. If false (default), the API will return a conversation ID directly and you will need to use streaming events to get the messages.

spaceIdstring

The sId of the space (project) in which to create the conversation (optional). If not provided, the conversation is created outside projects

Example request

{
  "message": {
    "content": "This is my message",
    "mentions": [
      {
        "configurationId": "7f3a9c2b1e"
      }
    ],
    "context": {
      "username": "johndoe123",
      "timezone": "America/New_York",
      "fullName": "John Doe",
      "email": "john.doe@example.com",
      "profilePictureUrl": "https://example.com/profiles/johndoe123.jpg",
      "agenticMessageData": {
        "originMessageId": "2b8e4f6a0c"
      }
    },
    "modelSelection": {
      "providerId": "anthropic",
      "modelId": "claude-sonnet-4-20250514",
      "reasoningEffort": "medium"
    }
  },
  "contentFragments": [
    {
      "title": "My content fragment",
      "content": "This is my content fragment extracted text",
      "contentType": "text/plain",
      "url": "https://example.com/content",
      "fileId": "fil_123456",
      "path": "conversation/report.csv",
      "processedPath": "conversation/voice.processed.txt",
      "nodeId": "node_123456",
      "nodeDataSourceViewId": "dsv_123456",
      "context": {
        "username": "johndoe123",
        "timezone": "America/New_York",
        "fullName": "John Doe",
        "email": "john.doe@example.com",
        "profilePictureUrl": "https://example.com/profiles/johndoe123.jpg",
        "agenticMessageData": {
          "originMessageId": "2b8e4f6a0c"
        }
      }
    }
  ],
  "title": "My conversation",
  "blocking": true,
  "spaceId": "space_abc123"
}

Response

Conversation created successfully.

Example response

{
  "conversation": {
    "id": 67890,
    "created": 1625097600,
    "sId": "3d8f6a2c1b",
    "owner": {
      "id": 67890,
      "sId": "dQFf9l5FQY",
      "name": "My Awesome Workspace",
      "role": "admin",
      "segmentation": "enterprise",
      "flags": [
        "advanced_analytics",
        "beta_features"
      ],
      "ssoEnforced": true,
      "whiteListedProviders": [
        "google",
        "github"
      ],
      "defaultEmbeddingProvider": "openai"
    },
    "title": "Customer Inquiry #1234",
    "visibility": "private",
    "content": [
      [
        {
          "id": 1,
          "sId": "9e7d5c3a1f",
          "type": "human",
          "visibility": "visible",
          "version": 1,
          "created": 1625097700,
          "user": {
            "sId": "0ec9852c2f",
            "id": 12345,
            "createdAt": 1625097600,
            "username": "johndoe",
            "email": "john.doe@example.com",
            "firstName": "John",
            "lastName": "Doe",
            "fullName": "John Doe",
            "provider": "google",
            "image": "https://example.com/profile/johndoe.jpg"
          },
          "mentions": [
            {
              "configurationId": "7f3a9c2b1e"
            }
          ],
          "content": "Hello, I need help with my order.",
          "context": {
            "username": "johndoe123",
            "timezone": "America/New_York",
            "fullName": "John Doe",
            "email": "john.doe@example.com",
            "profilePictureUrl": "https://example.com/profiles/johndoe123.jpg",
            "agenticMessageData": {
              "originMessageId": "2b8e4f6a0c"
            }
          },
          "agentMessageId": 1,
          "parentMessageId": "2b8e4f6a0c",
          "status": "completed",
          "chainOfThought": "The user is asking about their order. I should first greet them and then ask for their order number.",
          "rawContents": [
            {
              "step": 1,
              "content": "Hello! I'd be happy to help you with your order. Could you please provide your order number?"
            }
          ],
          "configuration": {
            "id": 12345,
            "sId": "7f3a9c2b1e",
            "version": 2,
            "versionCreatedAt": "2023-06-15T14:30:00Z",
            "versionAuthorId": "0ec9852c2f",
            "name": "Customer Support Agent",
            "description": "An AI agent designed to handle customer support inquiries",
            "instructions": "Always greet the customer politely and try to resolve their issue efficiently.",
            "pictureUrl": "https://example.com/agent-images/support-agent.png",
            "status": "active",
            "scope": "workspace",
            "userFavorite": true,
            "model": {
              "providerId": "openai",
              "modelId": "gpt-4",
              "temperature": 0.7
            },
            "actions": [],
            "maxStepsPerRun": 10,
            "templateId": "b4e2f1a9c7"
          }
        }
      ]
    ]
  }
}