List Messages

Page through a conversation’s messages, oldest first.

GET /api/v1/sessions/{session_id}/messages

cURL

curl "https://api.wordsmith.ai/api/v1/sessions/6d02931b-eaa1-4c77-b711-66038eb1bb2b/messages?limit=2" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

Response

{
  "items": [
    {
      "id": "bf21fa83-7b65-4818-9c96-aa0a36f310cd",
      "role": "user",
      "content": "Is the supplier's liability capped in the attached agreement?",
      "attachments": [
        {
          "id": "722c132d-703f-4a2e-ba13-d032f7b03025",
          "file_name": "Supply Agreement.docx",
          "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
          "content_length": 84213,
          "created_at": "2026-10-13T14:02:08Z"
        }
      ],
      "status": "completed",
      "created_at": "2026-10-13T14:02:11Z"
    },
    {
      "id": "a96a57ec-9d0d-465a-ae26-368624d265da",
      "role": "assistant",
      "content": "Yes, mostly. **Clause 11.2** caps each party's liability at the fees paid in the previous 12 months.\n\nTwo carve-outs sit outside the cap:\n\n- breach of confidentiality (clause 9)\n- the indemnity for third-party IP claims (clause 12)",
      "attachments": [],
      "status": "completed",
      "created_at": "2026-10-13T14:02:11Z"
    }
  ],
  "cursor": "eyJvZmZzZXQiOjJ9"
}

Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.

Returns a page of a session’s messages, oldest first. Each message is a user question or an assistant answer, with the files attached to it. A question lists the files the user attached; an answer lists the files the agent produced. Only files you can read are listed. Answers are Markdown. A finished answer with no text and no files, such as a step where the agent only used tools, is left out.

An answer that is still being written has status: "in_progress" and partial content. To wait for an answer to a question you asked, poll Get Question Status rather than this endpoint.

Authentication

Requires an API key, or an OAuth token with sessions:read.

Path parameters

session_id · string · required

The session id.

Query parameters

cursor · string

The cursor from the previous page. Omit it for the first page.

limit · integer · default: "50"

Messages per page, from 1 to 200.

Response

Returns 200 with {"items": [...], "cursor": "..."}. cursor is null on the last page.

id · string

The message id.

role · string

user or assistant.

content · string

The question, or the answer in Markdown.

attachments · File[]

The message’s files: id, file_name, content_type, content_length and created_at.

status · string

completed, in_progress or error. A question is always completed.

created_at · string

ISO 8601 UTC. A question and its answer share the time the question was asked.

cURL

curl "https://api.wordsmith.ai/api/v1/sessions/6d02931b-eaa1-4c77-b711-66038eb1bb2b/messages?limit=2" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

Response

{
  "items": [
    {
      "id": "bf21fa83-7b65-4818-9c96-aa0a36f310cd",
      "role": "user",
      "content": "Is the supplier's liability capped in the attached agreement?",
      "attachments": [
        {
          "id": "722c132d-703f-4a2e-ba13-d032f7b03025",
          "file_name": "Supply Agreement.docx",
          "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
          "content_length": 84213,
          "created_at": "2026-10-13T14:02:08Z"
        }
      ],
      "status": "completed",
      "created_at": "2026-10-13T14:02:11Z"
    },
    {
      "id": "a96a57ec-9d0d-465a-ae26-368624d265da",
      "role": "assistant",
      "content": "Yes, mostly. **Clause 11.2** caps each party's liability at the fees paid in the previous 12 months.\n\nTwo carve-outs sit outside the cap:\n\n- breach of confidentiality (clause 9)\n- the indemnity for third-party IP claims (clause 12)",
      "attachments": [],
      "status": "completed",
      "created_at": "2026-10-13T14:02:11Z"
    }
  ],
  "cursor": "eyJvZmZzZXQiOjJ9"
}

Errors

Status	error_code	When
400	bad_request	limit is outside 1–200, or cursor is not one this endpoint returned.
404	resource_not_found	No session with this id, or the caller cannot read it.