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.

POST /rest/v1/sessions/{session_id}/messages
Posts a follow-up user message to an existing session and starts a new agent turn. The response returns a fresh chat_thread_id — use it to build the polling URL for the assistant’s reply.
Follow-ups can be sent at any time, including while the agent is still working on a previous turn. They will interrupt the in-flight turn.

​
Request

const followup = await fetch(
  `https://api.blocks.team/rest/v1/sessions/${sessionId}/messages`,
  {
    method: "POST",
    headers: {
      Authorization: `ApiKey ${process.env.BLOCKS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message: "Cool — now tell me one about cuttlefish." }),
  },
).then((r) => r.json());

// Poll followup._links.final_message.href to receive the assistant's reply.

​
Path parameters

​
session_id
string (uuid)
required
The session to post the follow-up to.

​
Body

​
message
string
required
The follow-up user message.
​
artifact_ids
string[] (uuid[])
Existing artifacts to attach to this message.
​
profile
object
Profile reference or inline profile to apply to this turn. Same shape as in Create Session.

​
Response

{
  "id": "9c2f…",
  "chat_id": "a196cec6-49cb-4c48-8e4c-2707fb5d6709",
  "chat_thread_id": "b4e1…",
  "task_id": "1f8a…",
  "role": "user",
  "type": "message",
  "message": "Cool — now tell me one about cuttlefish.",
  "ts": null,
  "created_at": "2026-04-30T18:25:12.000Z",
  "updated_at": "2026-04-30T18:25:12.000Z",
  "_links": {
    "self": { "href": "https://api.blocks.team/rest/v1/sessions/a196cec6-…/messages" },
    "thread": { "href": "https://api.blocks.team/rest/v1/sessions/a196cec6-…/threads/b4e1…/messages" },
    "final_message": { "href": "https://api.blocks.team/rest/v1/sessions/a196cec6-…/threads/b4e1…/messages?type=final_message&role=assistant" }
  }
}
​
id
string (uuid)
Message ID for the user message you just posted.
​
chat_id
string (uuid)
The session this message belongs to.
​
chat_thread_id
string (uuid)
The new thread created for this turn. Prefer _links.final_message.href for polling — this field is exposed for cases where you need the thread ID directly.
​
task_id
string (uuid)
The task ID for the agent invocation triggered by this message.
​
role
string
Always user for this endpoint.
​
type
string
Always message for this endpoint.
​
message
string
Echo of the message body you posted.
​
ts
number | null
Provider-supplied timestamp (epoch seconds). Typically null for user messages.
​
created_at
string (ISO 8601)
When the message was created.
​
updated_at
string (ISO 8601)
When the message was last updated.
​
_links
object
HATEOAS links — mirror those returned by Create Session so you can reuse the same polling idiom for follow-ups.

​
Errors

StatusCodeReason
400BAD_REQUESTThe session has no prior messages, so no task_id can be resolved. Create the session via Create Session first.
404NOT_FOUNDSession does not exist or belongs to a different workspace.