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
Creates a new session for the authenticated workspace, posts the initial user message, and dispatches it to the agent. The response includes a pre-built _links.final_message.href URL — poll it to receive the assistant’s reply.

​
Request

const res = await fetch("https://api.blocks.team/rest/v1/sessions", {
  method: "POST",
  headers: {
    Authorization: `ApiKey ${process.env.BLOCKS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_name: "claude",
    message: "Say hello and tell me a one-sentence fun fact about octopuses.",
  }),
});
const session = await res.json();

​
Body

Exactly one of agent_id, agent_name, or profile must be provided. Sending none returns 400 VALIDATION.
​
message
string
required
The first user message in the session.
​
agent_name
string
Name of a built-in core agent. One of claude, codex, gemini, opencode, cursor, kimi. Returns 400 VALIDATION if the name is unknown.
​
agent_id
string (uuid)
ID of a specific agent in your workspace. Use this to target a custom agent.
​
profile
object
Reference to a profile or an inline profile to apply to this session.
​
is_private
boolean
default:"false"
When true, the session is hidden from other workspace members.
​
artifact_ids
string[] (uuid[])
Existing artifacts to attach to the initial message.

​
Response

{
  "id": "a196cec6-49cb-4c48-8e4c-2707fb5d6709",
  "title": "Octopus fun fact",
  "pull_requests": [],
  "source_url": null,
  "is_archived": false,
  "is_private": false,
  "created_at": "2026-04-30T18:21:00.000Z",
  "updated_at": "2026-04-30T18:21:00.000Z",
  "thread_id": "71562cd0-1f63-41b2-8382-10f2fdb1ac8b",
  "session_html_url": "https://blocks.team/app/sessions/a196cec6-49cb-4c48-8e4c-2707fb5d6709",
  "_links": {
    "self": { "href": "https://api.blocks.team/rest/v1/sessions/a196cec6-49cb-4c48-8e4c-2707fb5d6709" },
    "messages": { "href": "https://api.blocks.team/rest/v1/sessions/a196cec6-49cb-4c48-8e4c-2707fb5d6709/messages" },
    "thread": { "href": "https://api.blocks.team/rest/v1/sessions/a196cec6-49cb-4c48-8e4c-2707fb5d6709/threads/71562cd0-1f63-41b2-8382-10f2fdb1ac8b/messages" },
    "final_message": { "href": "https://api.blocks.team/rest/v1/sessions/a196cec6-49cb-4c48-8e4c-2707fb5d6709/threads/71562cd0-1f63-41b2-8382-10f2fdb1ac8b/messages?type=final_message&role=assistant" }
  }
}
​
id
string (uuid)
Unique identifier for the session.
​
title
string
Auto-generated title for the session.
​
pull_requests
string[]
IDs of pull requests opened by the agent in this session.
​
source_url
string | null
External URL the session was started from, if any (e.g. a Slack message).
​
is_archived
boolean
Whether the session has been archived.
​
is_private
boolean
Whether the session is hidden from other workspace members.
​
created_at
string (ISO 8601)
When the session was created.
​
updated_at
string (ISO 8601)
When the session was last updated.
​
thread_id
string (uuid) | null
The ID of the first thread on the session. Used to build the polling URL for the assistant’s reply.
​
session_html_url
string
Web URL where the session can be viewed in the Blocks dashboard.
​
_links
object
HATEOAS links for the session.

​
Errors

StatusCodeReason
400VALIDATIONNone of agent_id, agent_name, or profile was provided.
400VALIDATIONagent_name is not one of the supported core agents.