Create Session

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();

import os, requests

session = requests.post(
    "https://api.blocks.team/rest/v1/sessions",
    headers={
        "Authorization": f"ApiKey {os.environ['BLOCKS_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "agent_name": "claude",
        "message": "Say hello and tell me a one-sentence fun fact about octopuses.",
    },
).json()

curl -X POST https://api.blocks.team/rest/v1/sessions \
  -H "Authorization: ApiKey $BLOCKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "claude",
    "message": "Say hello and tell me a one-sentence fun fact about octopuses."
  }'

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"))
        .header("Authorization", "ApiKey " + System.getenv("BLOCKS_API_KEY"))
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(
            "{\"agent_name\":\"claude\",\"message\":\"Say hello and tell me a one-sentence fun fact about octopuses.\"}"))
        .build(),
    HttpResponse.BodyHandlers.ofString());

require "net/http"
require "json"

session = JSON.parse(Net::HTTP.post(
  URI("https://api.blocks.team/rest/v1/sessions"),
  JSON.generate({
    agent_name: "claude",
    message: "Say hello and tell me a one-sentence fun fact about octopuses.",
  }),
  {
    "Authorization" => "ApiKey #{ENV['BLOCKS_API_KEY']}",
    "Content-Type" => "application/json",
  },
).body)

body, _ := json.Marshal(map[string]string{
    "agent_name": "claude",
    "message":    "Say hello and tell me a one-sentence fun fact about octopuses.",
})
req, _ := http.NewRequest("POST", "https://api.blocks.team/rest/v1/sessions", 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)

Body

Exactly one of agent_id, agent_name, or profile must be provided. Sending none returns 400 VALIDATION.

string

required

The first user message in the session.

string

Name of a built-in core agent. One of claude, codex, gemini, opencode, cursor, kimi. Returns 400 VALIDATION if the name is unknown.

string (uuid)

ID of a specific agent in your workspace. Use this to target a custom agent.

object

Reference to a profile or an inline profile to apply to this session.

Show properties

string (uuid)

ID of an existing profile.

object

Runtime config overrides for the agent.

array

MCP servers to attach to the session.

string

How config_values are merged with the agent’s defaults.

boolean

default:"false"

When true, the session is hidden from other workspace members.

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" }
  }
}

string (uuid)

Unique identifier for the session.

string

Auto-generated title for the session.

string[]

IDs of pull requests opened by the agent in this session.

string | null

External URL the session was started from, if any (e.g. a Slack message).

boolean

Whether the session has been archived.

boolean

Whether the session is hidden from other workspace members.

string (ISO 8601)

When the session was created.

string (ISO 8601)

When the session was last updated.

string (uuid) | null

The ID of the first thread on the session. Used to build the polling URL for the assistant’s reply.

string

Web URL where the session can be viewed in the Blocks dashboard.

object

HATEOAS links for the session.

Show properties

object

Link to this session.

object

Link to the session’s messages list.

object | null

Link to the first thread’s messages.

object | null

Pre-built polling URL for the assistant’s final message — already filtered to type=final_message&role=assistant on the first thread.

Errors

Status	Code	Reason
`400`	`VALIDATION`	None of `agent_id`, `agent_name`, or `profile` was provided.
`400`	`VALIDATION`	`agent_name` is not one of the supported core agents.

Get Started

Agent Sessions

Use Cases

Request

Body

Response

Errors

​Request

​Body

​Response

​Errors

Request

Body

Response

Errors