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

# Create Session

> Start a new agent session and post the first user message.

```http theme={null}
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

<CodeGroup>
  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```

  ```bash cURL theme={null}
  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."
    }'
  ```

  ```java Java theme={null}
  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());
  ```

  ```ruby Ruby theme={null}
  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)
  ```

  ```go Go theme={null}
  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)
  ```
</CodeGroup>

### Body

<Note>
  Exactly one of `agent_id`, `agent_name`, or `profile` must be provided. Sending none returns `400 VALIDATION`.
</Note>

<ParamField body="message" type="string" required>
  The first user message in the session.
</ParamField>

<ParamField body="agent_name" type="string">
  Name of a built-in core agent. One of `claude`, `codex`, `gemini`, `opencode`, `cursor`, `kimi`. Returns `400 VALIDATION` if the name is unknown.
</ParamField>

<ParamField body="agent_id" type="string (uuid)">
  ID of a specific agent in your workspace. Use this to target a custom agent.
</ParamField>

<ParamField body="profile" type="object">
  Reference to a profile or an inline profile to apply to this session.

  <Expandable title="properties">
    <ParamField body="id" type="string (uuid)">
      ID of an existing profile.
    </ParamField>

    <ParamField body="config_values" type="object">
      Runtime config overrides for the agent.
    </ParamField>

    <ParamField body="mcp_servers" type="array">
      MCP servers to attach to the session.
    </ParamField>

    <ParamField body="config_merge_strategy" type="string">
      How `config_values` are merged with the agent's defaults.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="is_private" type="boolean" default="false">
  When `true`, the session is hidden from other workspace members.
</ParamField>

<ParamField body="artifact_ids" type="string[] (uuid[])">
  Existing artifacts to attach to the initial message.
</ParamField>

## Response

```json theme={null}
{
  "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" }
  }
}
```

<ResponseField name="id" type="string (uuid)">
  Unique identifier for the session.
</ResponseField>

<ResponseField name="title" type="string">
  Auto-generated title for the session.
</ResponseField>

<ResponseField name="pull_requests" type="string[]">
  IDs of pull requests opened by the agent in this session.
</ResponseField>

<ResponseField name="source_url" type="string | null">
  External URL the session was started from, if any (e.g. a Slack message).
</ResponseField>

<ResponseField name="is_archived" type="boolean">
  Whether the session has been archived.
</ResponseField>

<ResponseField name="is_private" type="boolean">
  Whether the session is hidden from other workspace members.
</ResponseField>

<ResponseField name="created_at" type="string (ISO 8601)">
  When the session was created.
</ResponseField>

<ResponseField name="updated_at" type="string (ISO 8601)">
  When the session was last updated.
</ResponseField>

<ResponseField name="thread_id" type="string (uuid) | null">
  The ID of the first thread on the session. Used to build the polling URL for the assistant's reply.
</ResponseField>

<ResponseField name="session_html_url" type="string">
  Web URL where the session can be viewed in the Blocks dashboard.
</ResponseField>

<ResponseField name="_links" type="object">
  HATEOAS links for the session.

  <Expandable title="properties">
    <ResponseField name="self" type="object">
      Link to this session.
    </ResponseField>

    <ResponseField name="messages" type="object">
      Link to the session's messages list.
    </ResponseField>

    <ResponseField name="thread" type="object | null">
      Link to the first thread's messages.
    </ResponseField>

    <ResponseField name="final_message" type="object | null">
      Pre-built polling URL for the assistant's final message — already filtered to `type=final_message&role=assistant` on the first thread.
    </ResponseField>
  </Expandable>
</ResponseField>

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