Skip to main content
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.

import os, requests

followup = requests.post(
    f"https://api.blocks.team/rest/v1/sessions/{session_id}/messages",
    headers={
        "Authorization": f"ApiKey {os.environ['BLOCKS_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"message": "Cool — now tell me one about cuttlefish."},
).json()

# Poll followup["_links"]["final_message"]["href"] to receive the assistant's reply.

curl -X POST "https://api.blocks.team/rest/v1/sessions/$SESSION_ID/messages" \
  -H "Authorization: ApiKey $BLOCKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Cool — now tell me one about cuttlefish."}'

import java.net.URI;
import java.net.http.*;

HttpResponse<String> res = HttpClient.newHttpClient().send(
    HttpRequest.newBuilder(URI.create(
        "https://api.blocks.team/rest/v1/sessions/" + sessionId + "/messages"))
        .header("Authorization", "ApiKey " + System.getenv("BLOCKS_API_KEY"))
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(
            "{\"message\":\"Cool — now tell me one about cuttlefish.\"}"))
        .build(),
    HttpResponse.BodyHandlers.ofString());

require "net/http"
require "json"

followup = JSON.parse(Net::HTTP.post(
  URI("https://api.blocks.team/rest/v1/sessions/#{session_id}/messages"),
  JSON.generate({ message: "Cool — now tell me one about cuttlefish." }),
  {
    "Authorization" => "ApiKey #{ENV['BLOCKS_API_KEY']}",
    "Content-Type" => "application/json",
  },
).body)

body, _ := json.Marshal(map[string]string{
    "message": "Cool — now tell me one about cuttlefish.",
})
req, _ := http.NewRequest("POST",
    "https://api.blocks.team/rest/v1/sessions/"+sessionID+"/messages",
    bytes.NewReader(body))
req.Header.Set("Authorization", "ApiKey "+os.Getenv("BLOCKS_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

​
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.