---
title: "Start Session Endpoint"
method: POST
path: "/projects/{project_id}/start-session"
---

# Start Session Endpoint

`POST /projects/{project_id}/start-session`

## Request

- Base URL: `https://usemeridian.us` (the document declares no server; this is the origin it was published from)
- URL: `https://usemeridian.us/projects/{project_id}/start-session`
- Auth: none declared

v0.4.4 — one call to start a coordinated session.

Registers the caller, fetches goal + ambient tasks, fetches the last 10
tasks, lists active sessions, and reports whether a handoff file already
exists on disk. Replaces 4 separate MCP calls at session cold-start.

89a06e40 (PROFILE-6 verification follow-up) — this route returns
``_start_session_composite``'s payload directly, bypassing the MCP
``start_session`` tool's ``handle_start_session`` handler
(``meridian/mcp/handlers/project_tools.py``) entirely, so it does not
automatically inherit that handler's ``profile_binding`` enrichment
block. The block below mirrors it for this REST surface (both the
fresh-session and continue-mode payload shapes) so a REST caller gets
the same sibling field an MCP caller does.

## Path parameters

- `project_id` string, required

## Request body

- StartSessionRequest: Body for POST /projects/{id}/start-session (v0.4.4).
  - `session_name` string, required
  - `human_id` string, nullable: Optional human owner of this session.
  - `client` string, nullable: Client app identifier: claude-code, claude-desktop, cursor, other.
  - `role` string, nullable: Optional session role. Use 'executor' to inject executor_config.
  - `source` string, nullable: G8.34 — Optional hint about why start_session was called: 'startup' (fresh client boot), 'resume' (cleared chat / continued work), 'clear' (user wiped context), or 'compact' (context window ran out, fresh process). SessionStart hooks forward this so the server can return a continuation block instead of a full reset.

## Response `200`

Successful Response

- object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/usemeridian/apis/meridian.md) · [All operations](https://skmtc.dev/usemeridian/apis/meridian/llms.txt) · [OpenAPI document](https://skmtc.dev/usemeridian/apis/meridian/revisions/f37a894bd374?raw)