Skip to main content
Thread messages are the individual turns in a conversation — user inputs, AI-generated responses, and system messages. You can list historical messages, fetch a specific message, or write messages directly (e.g. when replaying or constructing conversations programmatically). For triggering AI generation from a user message, see Threads — use POST /v1/threads/{thread_id}/user_message instead.

​
POST /v1/threads//messages

Create a message directly in a thread without triggering AI generation. Returns 201 on success. 
POST https://api-staging.knowledgestack.ai/v1/threads/{thread_id}/messages

​
Path parameters

ParameterTypeDescription
thread_idstring (UUID)The thread to create the message in.

​
Request body

​
role
string
required
The author role for this message. See MessageRole for values.
​
content
object
required
Message content object. Contains text (required) and optionally citations, is_error, and references.
​
message_id
string
Optional caller-supplied UUID for the message. Use this to make the create operation idempotent — submitting the same message_id twice returns the existing message without creating a duplicate.
​
details
object
Execution step data for assistant messages (e.g. tool call traces). Omit for user messages.

​
Example

curl -X POST https://api-staging.knowledgestack.ai/v1/threads/a1b2c3d4-e5f6-7890-abcd-ef1234567890/messages \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "USER",
    "content": {
      "text": "What is the cancellation window for annual plans?"
    }
  }'

​
GET /v1/threads//messages

List all messages in a thread, ordered by created_at descending (newest first). 
GET https://api-staging.knowledgestack.ai/v1/threads/{thread_id}/messages

​
Query parameters

ParameterTypeDefaultDescription
limitinteger20Items per page (1–100).
offsetinteger0Items to skip.
beforestring (datetime)—Cursor for keyset pagination. Returns only messages with created_at before this ISO 8601 timestamp.
with_detailsbooleantrueInclude execution step data in each message. Set to false to reduce payload size when you only need message text.
Returns a paginated response with a data array of ThreadMessageResponse objects. 
curl "https://api-staging.knowledgestack.ai/v1/threads/a1b2c3d4-e5f6-7890-abcd-ef1234567890/messages?limit=50&with_details=false" \
  -H "Authorization: Bearer <your-api-key>"

​
GET /v1/threads//messages/

Fetch a single message by ID. 
GET https://api-staging.knowledgestack.ai/v1/threads/{thread_id}/messages/{message_id}

​
Query parameters

ParameterTypeDefaultDescription
with_detailsbooleantrueInclude execution step data.
curl "https://api-staging.knowledgestack.ai/v1/threads/a1b2c3d4-e5f6-7890-abcd-ef1234567890/messages/d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a?with_details=false" \
  -H "Authorization: Bearer <your-api-key>"

​
ThreadMessageResponse

​
id
string
Message UUID.
​
thread_id
string
UUID of the thread this message belongs to (via parent_path_id).
​
path_part_id
string
UUID of the path part node for this message.
​
sequence
integer
Sequence number of this message within the thread (derived from path part name). Use this to display messages in conversation order.
​
role
string
Author role: USER, ASSISTANT, or SYSTEM. See MessageRole.
​
content
object
Message content. See EnrichedThreadMessageContent.
​
details
object | null
Execution step data for assistant messages, or null when not requested (with_details=false) or not applicable.
​
parent_path_id
string
UUID of the thread’s path part (the message’s parent in the hierarchy).
​
materialized_path
string
Full path from root to this message.
​
tenant_id
string
Tenant UUID.
​
created_at
string
ISO 8601 creation timestamp.
​
updated_at
string
ISO 8601 last-updated timestamp.

​
EnrichedThreadMessageContent

The content field on a ThreadMessageResponse uses the enriched content type, which resolves citation references at read time.
​
text
string
The message text.
​
is_error
boolean | null
true if the message represents a terminal assistant error.
​
citations
array | null
Array of EnrichedCitation objects. These are the source references the AI used when generating the response.
​
references
array | null
Resolved inline references attached to the message.

​
EnrichedCitation

Citations link the AI’s response back to specific passages in your knowledge base. Each citation points to a character span within a chunk.
​
chunk_id
string
UUID of the source chunk.
​
quote
string
The verbatim quoted text from the chunk.
​
start_char
integer
0-based character offset of the quote within the chunk’s content string.
​
length
integer
Character length of the quote.
​
document_id
string | null
UUID of the source document, if resolved.
​
document_version_id
string | null
UUID of the source document version, if resolved.
​
document_name
string | null
Human-readable name of the source document, if resolved.
​
version_number
integer | null
Version number of the source document, if resolved.
​
path_part_id
string | null
UUID of the path part for the chunk, if resolved.
​
materialized_path
string | null
Full path of the chunk in the hierarchy, if resolved.

​
MessageRole

ValueDescription
USERA message written by the end user.
ASSISTANTA message generated by the AI.
SYSTEMA system-level message (e.g. instructions or context injected by the platform).

​
Example response

{
  "id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",
  "path_part_id": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b",
  "sequence": 2,
  "role": "ASSISTANT",
  "content": {
    "text": "Annual subscriptions are eligible for a full refund within 30 days of purchase.",
    "is_error": null,
    "citations": [
      {
        "chunk_id": "7f3a1b9c-4e2d-4a8f-b6c1-d9e0f1234567",
        "quote": "Annual subscriptions are eligible for a full refund within 30 days",
        "start_char": 0,
        "length": 67,
        "document_id": "d1e2f3a4-b5c6-7d8e-9f0a-1b2c3d4e5f6a",
        "document_version_id": "e1f2a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
        "document_name": "Refund Policy",
        "version_number": 0,
        "path_part_id": "2c8d5e7f-1a3b-4c6d-9e0f-a1b2c3d4e5f6",
        "materialized_path": "/shared/policies/refunds/v0/chunk-1"
      }
    ],
    "references": null
  },
  "details": null,
  "parent_path_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "materialized_path": "/users/u1a2b3c4/threads/a1b2c3d4/2",
  "tenant_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "created_at": "2025-04-01T12:01:15Z",
  "updated_at": "2025-04-01T12:01:15Z"
}