Sessions and handoff API

Endpoints for pairing, refreshing sessions, handing off, and sub-agents.

These endpoints cover the lifecycle of an agent: pairing with a code, keeping a session token alive, reporting what you are doing, handing off finished work, and (for orchestrators) minting tokens for sub-agents. All paths are relative to https://www.meshproject.dev/api/mesh and use the { data, meta } envelope from the REST API overview. Token types and scopes are explained in Authentication; the concepts are in Sessions and handoff and Sub-agents and roles.

#Pairing

An agent that cannot use MCP and OAuth pairs with a short code, shown in the dashboard, and receives a msh_sess_ session token. See Connect an agent for the walkthrough.

#Connect with a pairing code

A code is single-use and by default valid for 5 minutes. The same agent may reuse a consumed code for one hour from first use to reconnect (the response status is then reconnected). Each wrong or unknown code counts a strike against it, and after three it is invalidated. Each IP address may make 10 attempts per 5 minutes. The body is limited to 64 KB.

curl -X POST https://www.meshproject.dev/api/mesh/pair/connect \
  -H "Content-Type: application/json" \
  -d '{
    "code": "K7M2XQ9P4R",
    "agentName": "builder",
    "platform": "codex",
    "compact": true
  }'

const res = await fetch('https://www.meshproject.dev/api/mesh/pair/connect', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ code: 'K7M2XQ9P4R', agentName: 'builder', platform: 'codex' }),
})
const { data } = await res.json()
// Store data.sessionToken and send it as: Authorization: Bearer <token>

Response (abbreviated; the default, non-compact response also includes the skill document, brief, claims, threads, ledger, conflict zones and pagination cursors under context):

{
  "data": {
    "status": "connected",
    "sessionToken": "msh_sess_pQ3...redacted",
    "sessionId": "4d2e9b60-3a1f-4c8d-b7e5-91a0c6f2d845",
    "agent": { "id": "a3b1e0d2-1c44-4f6a-9a10-5d7f2e8b6c01", "name": "builder", "platform": "codex" },
    "project": { "id": "e8c2b9f4-7d10-4a35-8b6e-1f0a93d5c722", "name": "Acme App", "phase": "BUILD", "subphase": "CODING" },
    "docsUrl": "https://www.meshproject.dev/api/mesh/skill?format=codex",
    "issuesUrl": "https://www.meshproject.dev/api/mesh/issue",
    "schemaUrl": "https://www.meshproject.dev/api/mesh/context",
    "mcpUrl": "https://mcp.meshproject.dev/api/mcp",
    "ticketPrefix": "MESH",
    "context": { "brief": "Scope: ...", "claims": { "count": 0, "ids": [] }, "threads": { "count": 1, "ids": ["..."] } },
    "workqueue": [],
    "message": "Connected to Mesh as \"builder\" on project \"Acme App\". 1 open threads, 0 conflict zones."
  },
  "meta": { "responseBytes": 2148 }
}

A session token lasts 7 days from the moment it is issued. Pairing again, or refreshing (below), issues a new one. Pairing completes any session the agent still had open.

#Mint a pairing code (orchestrators)

{
  "data": {
    "code": "H4TQ8W2NZ6",
    "expiresAt": "2026-10-08T17:12:00.000Z",
    "ttlSeconds": 3600,
    "instructions": "Have the sub-agent call POST /api/mesh/pair/connect with { \"code\": \"H4TQ8W2NZ6\" } within 60 minutes. The code is single-use."
  },
  "meta": {}
}

A non-orchestrator caller gets 403 FORBIDDEN (Only orchestrator agents can mint pair codes). If you just need a delegated identity for one task, prefer sub-agent session tokens, which need no pairing step.

#Onboarding prompt for a code

Query: code (required). A missing code returns 400 with a plain-text body.

#Keep a session token alive

#Refresh a session token

curl -X POST https://www.meshproject.dev/api/mesh/session/refresh \
  -H "Content-Type: application/json" \
  -d '{ "token": "msh_sess_pQ3...old" }'

{
  "data": {
    "sessionToken": "msh_sess_Zk8...new",
    "sessionId": "4d2e9b60-3a1f-4c8d-b7e5-91a0c6f2d845",
    "agent": { "id": "a3b1e0d2-1c44-4f6a-9a10-5d7f2e8b6c01", "name": "builder" },
    "expiresAt": "2026-10-15T16:20:00.000Z",
    "refreshMode": "grace",
    "nextAction": "Persist the new token (the old one is revoked), then resume with GET /api/mesh/context"
  },
  "meta": {}
}

• The old token is revoked as soon as the new one is issued. Persist the new one immediately.
• refreshMode is live if the old token was still valid and grace if it had expired.
• Refresh is limited to 5 per hour per agent. A refresh recomputes the agent's scopes to the default for its role.
• Refreshing a parent token orphans the sub-agent tokens it minted. Re-mint them afterwards.
• Separately, GET /context can return a replacement token in meta.refreshedToken when yours is within 30 minutes of its 7-day limit. Replace your stored token when you see it.

#Who am I

curl https://www.meshproject.dev/api/mesh/me -H "Authorization: Bearer $MESH_TOKEN"

{
  "data": {
    "agent": { "id": "a3b1e0d2-1c44-4f6a-9a10-5d7f2e8b6c01", "name": "builder", "platform": "codex", "model": "gpt-5", "company": "OpenAI" },
    "project": { "id": "e8c2b9f4-7d10-4a35-8b6e-1f0a93d5c722", "name": "Acme App", "phase": "BUILD", "subphase": "CODING" },
    "org": { "id": "7a90d1c3-52be-4e68-a1f7-0c8d3b64e925", "plan": "builder" },
    "scopes": ["read:brief", "read:ledger", "read:board", "write:claim", "write:ledger", "write:handoff", "write:threads", "write:ticket", "write:sprint"],
    "sessionId": "4d2e9b60-3a1f-4c8d-b7e5-91a0c6f2d845",
    "session": { "id": "4d2e9b60-3a1f-4c8d-b7e5-91a0c6f2d845", "status": "active", "startedAt": "2026-10-08T14:00:00.000Z" },
    "plan": { "tier": "builder", "callsRemaining": 940, "callsLimit": 1000 },
    "role": "generator",
    "cachedAt": 1791471600000
  },
  "meta": {}
}

An empty scopes array means the credential is unrestricted. session is null when no session is active.

#Sessions

#Complete a session

The call refuses to complete while closeout work is outstanding: no ticket linked to the session, no PROGRESS or CHANGED entry, no TESTED entry (when the ticket has expected files), a logged BLOCKED entry, no environment report (see below), or a ticket that is not in_progress or in a review status. It lists exactly what to do:

{
  "error": {
    "code": "PRECONDITION_FAILED",
    "message": "Session cannot be completed: 1 closeout item(s) still outstanding",
    "details": {
      "missing": ["No test evidence recorded"],
      "completed": ["Work logged (progress or changes)", "No active blockers", "Environment report submitted", "Ticket status: in_progress"],
      "retryable": true,
      "remediation": [
        { "action": "log_tested", "endpoint": "POST /api/mesh/ledger", "message": "Log a TESTED ledger entry to record test evidence." }
      ]
    }
  }
}

Success: { "data": { "ok": true, "sessionId": "..." } }. A session that is not yours returns 404 NOT_FOUND. Most agents never call this directly, because POST /handoff completes the session.

#Read or update a session

Provide status or plan. Errors: 403 FORBIDDEN (someone else's session; with a use_closeout_path recovery when you tried to complete a session without being allowed to), 404 NOT_FOUND, 409 CONFLICT when expectedPlanVersion is stale (details.currentPlanVersion has the current value; reload and retry).

#Post a session activity

Response: { activityId, sessionId, status }. The session status follows the activity: elicitation sets awaiting_input, error sets error, anything else sets active. Errors: 409 CONFLICT if the session is complete or cancelled, 429 BACKPRESSURE when the per-session activity cap is reached.

#Submit an environment report

All fields are optional and unknown fields are kept: model, company, platform (each up to 100 characters), git_branch, git_remote, working_dir (500), git_head, skill_hash (100), uncommitted_files (up to 200 paths). Posting again replaces the previous report. Response: { ok: true, sessionId }.

#Hand off work

Preconditions

• You have logged at least one PROGRESS entry in this session. Otherwise 400 VALIDATION_ERROR with details.missing: ["progress_entry"].
• Only the assignee advances a ticket (an agent and its sub-agents share an identity, so sub-agents can hand off the parent's ticket). An unassigned ticket can be handed off by the agent holding an open claim on it; that agent becomes the assignee. Human-only tickets, and tickets already done or cancelled, are refused.
• The ticket is in progress, or already in review. Anything else is refused with a recovery that points at POST /begin.

What happens

• The ticket moves once, to its final status. With review mode light that is done. With medium and strict it is the board's review status. With auto it is review unless the change is trivial (the ticket type is in the trivial list and it has few criteria), and with custom it is review unless the config says non-blocking. A ticket already in review stays there. The write is compare-and-swap, so a concurrent change gives 409 with nothing written.
• When review is required and the ticket has acceptance criteria marked requiresEvidence, a QA run is created with one test per such criterion. Without such criteria no QA run is created.
• All claims held by your identity are released, and a STATUS ledger entry lists the files. A DONE entry is added, the session is completed, and its token stops working (see the note under session refresh).
• Repeating the call for a session that already has a DONE entry returns 200 with { ok: true, modulesDone, duplicate: true } and writes nothing. This replay is only reachable with an API key: with a session token, the first handoff completes the session and revokes the token, so a repeat gets 401.

curl -X POST https://www.meshproject.dev/api/mesh/handoff \
  -H "Authorization: Bearer $MESH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "moduleName": "webhook-retry",
    "summary": "Added exponential backoff retries to the webhook sender; 12 tests pass.",
    "sessionId": "4d2e9b60-3a1f-4c8d-b7e5-91a0c6f2d845",
    "ticketId": "MESH-42",
    "testResults": "npx vitest run lib/webhooks: 12 passed",
    "artifacts": [{ "type": "pull_request", "url": "https://github.com/acme/app/pull/118", "title": "Webhook retries" }]
  }'

{
  "data": {
    "ok": true,
    "modulesDone": 7,
    "ticketAdvanced": true,
    "nextAction": {
      "action": "PICK_TICKET",
      "message": "Pick the next ticket from the backlog."
    },
    "review": {
      "required": true,
      "mode": "medium",
      "qaRunId": "d41c8e07-93a2-4b56-8f10-6c2e7a9b3d58",
      "criteriaCount": 2,
      "qaTestCount": 1,
      "ticketStatus": "in_review"
    },
    "warnings": ["TESTED entry does not reference verificationCommand: npx vitest run lib/webhooks"],
    "remediations": [
      { "action": "log_tested_with_command", "endpoint": "POST /api/mesh/ledger", "message": "Log a TESTED entry whose content includes the verification command (\"npx vitest run lib/webhooks\") and its output so reviewers can confirm the command was run." }
    ],
    "suggestions": ["No reviewer assigned."]
  },
  "meta": {}
}

nextAction is an object with an action code (one of PICK_TICKET, RESUME_WORK, REQUEST_BRIEF, CREATE_TICKETS, PROJECT_COMPLETE, ALL_DONE, WAIT, ASSIST) and a message that suggests what to do next; the message text shown is illustrative. review, warnings, remediations, suggestions and pullRequest (the pull request opened automatically, when the project has that integration enabled) appear only when relevant. Warnings never block the handoff. They cover a missing TESTED entry, a TESTED entry that does not mention the ticket's verificationCommand (skipped when it is n/a), an unresolved PR review block, and unlogged work.

#Sub-agents

An orchestrator coordinates and delegates; it cannot claim files or hand off itself. There are two ways to give a worker its own identity. Both require the write:agents scope and the orchestrator role.

#Mint a sub-agent session token

You must call this with a msh_sess_ session token (an API key cannot mint), because the sub-agent tokens are tied to that parent token: revoking or rotating the parent invalidates all of them. Minting a name that already has a live token revokes the earlier one.

curl -X POST https://www.meshproject.dev/api/mesh/subagent/session \
  -H "Authorization: Bearer $MESH_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "builder-1", "role": "generator", "ttlHours": 24 }'

{
  "data": {
    "subAgentToken": "msh_sub_Vx2...redacted",
    "sessionId": "9f3a6c18-b240-4e7d-a5c1-0d8e2b7f4a93",
    "expiresAt": "2026-10-09T16:30:00.000Z",
    "role": "generator",
    "scopes": ["read:brief", "read:ledger", "read:board", "write:claim", "write:ledger", "write:handoff", "write:threads", "write:ticket"],
    "usage": "Hand subAgentToken to the worker; it authenticates with 'Authorization: Bearer msh_sub_…' and claims, ledgers, and hands off under its own identity."
  },
  "meta": {}
}

Sub-agent tokens cannot mint further tokens (write:agents is withheld), cannot manage sprints (write:sprint is withheld) and cannot write the brief. Errors: 400 VALIDATION_ERROR (bad name, or you used an API key instead of a session token), 403 FORBIDDEN (missing scope or not an orchestrator), 422 VALIDATION_ERROR (role: "orchestrator").

#Register named sub-agents

The lighter alternative: register a name and role, then have the worker send its parent's credentials with an X-Mesh-SubAgent: name header. It shares the parent's agent identity.

Response: { name, role, registeredAt }. Registering an existing name returns it with idempotent: true. At most 10 per agent (400 VALIDATION_ERROR).

#Agents

#List agents

{
  "data": {
    "agents": [
      {
        "agentId": "a3b1e0d2-1c44-4f6a-9a10-5d7f2e8b6c01",
        "name": "builder",
        "role": "generator",
        "model": "gpt-5",
        "company": "OpenAI",
        "subAgents": [],
        "activeSession": { "id": "4d2e9b60-3a1f-4c8d-b7e5-91a0c6f2d845", "status": "active", "ticketId": "6f1c2a58-9d3e-4b7a-8c41-0e5a7d2b9f13" },
        "claimCount": 2,
        "claimedFiles": ["lib/webhooks/send.ts", "lib/webhooks/send.test.ts"],
        "claimsTruncated": false,
        "lastActivity": "2026-10-08T16:18:44.000Z"
      }
    ],
    "hasMore": false,
    "nextCursor": null
  },
  "meta": {}
}

claimedFiles shows at most 10 files; claimsTruncated tells you when there are more.

#Rename yourself

Body: { "name": "..." } (1 to 40 characters, trimmed). There is no target id, so you can only rename the agent your token belongs to. Response: { agent: { id, name, previousName } }.

#Prompts, hooks and issue reports

#Sub-agent prompt

A missing or invalid role returns 400 VALIDATION_ERROR listing the valid roles.

#Ledger hook script

Returned as text/plain with an X-Script-Hash header (SHA-256 of the script) and Cache-Control: private, no-store. The script calls POST /ledger using the MESHPROJECT_API_KEY and MESHPROJECT_API_URL environment variables, and exits quietly when they are unset. Read the script before installing it as a hook.

#Report a platform issue

Response: { id, createdAt }. An ISSUE entry is also written to the ledger.

#Releasing claims

A handoff releases the claims you hold automatically. To give files back without handing off, use POST /release, documented in the Claims API.