Threads API (Conversational AI)

The Threads API allows your external applications to orchestrate Chat Sessions with the Kortexa AI system.

List Threads

GET /v1/threads

Returns a list of recent chat conversations. Can be filtered by status (OPEN, CLOSED, ARCHIVED).

Create a Thread

POST /v1/threads

Initializes a new, empty chat session bound strictly to your B2B workspace.

Request Body

{
  "title": "Support Ticket #991"
}

Example Response

{
  "data": {
    "id": "thr_xyz987",
    "title": "Support Ticket #991",
    "status": "OPEN",
    "createdAt": "2024-03-05T14:22:00Z"
  }
}

Get Thread & Messages

GET /v1/threads/:id

Retrieves the thread details along with its chronological array of messages.

Send a Message

POST /v1/threads/:id/messages

Adds a new user message to the thread and synchronously returns the AI Assistant's response.

Request Body

{
  "content": "Please summarize the main liability clauses."
}

Example Response

The response includes both your injected message and the AI's generated response in a single transaction payload.

{
  "data": {
    "userMessage": {
      "id": "msg_user123",
      "role": "user",
      "content": "Please summarize the main liability clauses.",
      "createdAt": "2024-03-05T14:25:00Z"
    },
    "aiResponse": {
      "id": "msg_ai456",
      "role": "assistant",
      "content": "I received your message... This is a programmatic response.",
      "createdAt": "2024-03-05T14:25:02Z"
    }
  }
}

Note: For long-running generations, consider using the Async Streaming API (Beta).