Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blocks.team/llms.txt

Use this file to discover all available pages before exploring further.

Two endpoints share the same paginated response shape and query parameters. Use the first to list every message in a session; use the second to scope to a single thread (for example, to poll the latest follow-up’s reply). 
GET /rest/v1/sessions/{session_id}/messages
GET /rest/v1/sessions/{session_id}/threads/{thread_id}/messages
Results are sorted by created_at (newest first by default). Soft-deleted messages are excluded.

​
Request

// All messages on the session.
const url = `https://api.blocks.team/rest/v1/sessions/${sessionId}/messages?type=final_message&role=assistant`;

// Or scope to a specific thread:
// const url = `https://api.blocks.team/rest/v1/sessions/${sessionId}/threads/${threadId}/messages?type=final_message&role=assistant`;

const page = await fetch(url, {
  headers: { Authorization: `ApiKey ${process.env.BLOCKS_API_KEY}` },
}).then((r) => r.json());

​
Path parameters

​
session_id
string (uuid)
required
The session ID. Required for both URL forms.
​
thread_id
string (uuid)
required
The thread ID. Required only on the threaded URL form. The thread must belong to session_id.

​
Query parameters

​
type
string[]
default:"[\"message\", \"final_message\"]"
Repeat to combine. Allowed values: message, final_message, tool_call. Pass type=final_message to fetch only completed assistant replies.
​
role
string
default:"assistant"
Filter by sender. One of user, assistant.
​
thread_id
string (uuid)
Filter to a single thread without using the threaded URL form. Ignored on the threaded URL.
​
gts
number
Cursor for incremental polling, in epoch seconds. Returns only messages whose ts is strictly greater than this value. Use _links.new_messages.href from the previous page to get a pre-built URL with this cursor already set.
​
page
number
default:"1"
1-indexed page number. Minimum 1.
​
limit
number
default:"50"
Page size. Minimum 1, maximum 100.
​
direction
string
default:"desc"
Sort direction. One of asc, desc.

​
Response

{
  "items": [
    {
      "id": "5e1b…",
      "chat_id": "a196cec6-49cb-4c48-8e4c-2707fb5d6709",
      "chat_thread_id": "71562cd0-1f63-41b2-8382-10f2fdb1ac8b",
      "task_id": "0e7d…",
      "role": "assistant",
      "type": "final_message",
      "message": "Hi! Octopuses have three hearts — two pump blood to the gills and one to the rest of the body.",
      "ts": 1746038518,
      "created_at": "2026-04-30T18:21:42.000Z",
      "updated_at": "2026-04-30T18:21:42.000Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 50, "total_pages": 1 },
  "_links": {
    "self": { "href": "https://api.blocks.team/rest/v1/sessions/a196cec6-…/messages?type=final_message&role=assistant" },
    "new_messages": { "href": "https://api.blocks.team/rest/v1/sessions/a196cec6-…/messages?type=final_message&role=assistant&gts=1746038518" }
  }
}
​
items
object[]
Page of messages.
​
meta
object
Pagination metadata.
​
_links
object
HATEOAS links for the page.

​
Polling tips

  • For the assistant’s first reply, use the _links.final_message.href returned from Create Session — it already has the right filters applied.
  • For incremental polling, use _links.new_messages.href from the previous response. It encodes the gts cursor so each poll only returns new messages.

​
Errors

StatusCodeReason
404NOT_FOUNDSession (or thread) does not exist or belongs to a different workspace.