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.

The Sessions API lets you start a conversation with a Blocks agent and stream its responses over plain HTTP. Every endpoint lives under /rest/v1, accepts and returns JSON, and authenticates with a workspace-scoped API key.
Base URLhttps://api.blocks.team
Auth headerAuthorization: ApiKey <YOUR_API_KEY>
Rate limit100 requests / minute / API key
Get an API key from the dashboard. Set it as BLOCKS_API_KEY before running the snippets below.

​
1. Create a session and poll for the first reply

  1. Create a session — POST /rest/v1/sessions. The response includes _links.final_message.href, a pre-built URL for polling the assistant’s reply.
  2. Poll the URL — GET it until items is non-empty.
const BASE_URL = "https://api.blocks.team";
const headers = {
  Authorization: `ApiKey ${process.env.BLOCKS_API_KEY}`,
  "Content-Type": "application/json",
};

// 1. Create a session.
const session = await fetch(`${BASE_URL}/rest/v1/sessions`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    agent_name: "claude",
    message: "Say hello and tell me a one-sentence fun fact about octopuses.",
  }),
}).then((r) => r.json());

// 2. Poll for the assistant's final message.
while (true) {
  const page = await fetch(session._links.final_message.href, { headers }).then((r) => r.json());
  if (page.items.length > 0) {
    console.log(page.items[0].message);
    break;
  }
  await new Promise((r) => setTimeout(r, 5000));
}

​
2. Send a follow-up

  1. Send a follow-up — POST /rest/v1/sessions/{session_id}/messages. The response returns its own _links.final_message.href, the same shortcut as create.
  2. Poll the new thread’s URL — same pattern as above.
Follow-ups can be sent at any time — including while the agent is still working — and will interrupt the in-flight turn.
The snippets below assume session, headers, and BASE_URL are still in scope from the previous step. 
// 3. Send a follow-up.
const followup = await fetch(`${BASE_URL}/rest/v1/sessions/${session.id}/messages`, {
  method: "POST",
  headers,
  body: JSON.stringify({ message: "Cool — now tell me one about cuttlefish." }),
}).then((r) => r.json());

// 4. Poll the follow-up's thread.
while (true) {
  const page = await fetch(followup._links.final_message.href, { headers }).then((r) => r.json());
  if (page.items.length > 0) {
    console.log(page.items[0].message);
    break;
  }
  await new Promise((r) => setTimeout(r, 5000));
}

​
Next steps

Create Session

Full request and response schema for POST /rest/v1/sessions.

Get Session Messages

List, filter, and poll messages on a session or a single thread.

Send Messages

Post follow-ups — they interrupt an in-flight session.

Get Session

Look up a single session by ID.