---
title: "Atomically claim a work item for a session (T879)"
method: POST
path: "/api/goal/nodes/claim"
tags: ["Goal"]
---

# Atomically claim a work item for a session (T879)

`POST /api/goal/nodes/claim`

## Request

- Base URL: `http://localhost:38200`
- URL: `http://localhost:38200/api/goal/nodes/claim`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `token`

Cross-machine atomic claim. The conditional UPDATE's WHERE clause is the lock, so exactly one concurrent caller wins. Losing is a 200 with `claimed: false` naming the holder, NOT a 409 — a fanned-out agent treats an error status as a transport failure and retries, while "someone else has it" is a final answer to act on. The claim does not move `status`; status is advanced through /advance.

## Request body

- object
  - `id` integer, required: Node id to claim
  - `session_id` integer, required: The claiming agent session

## Response `200`

Claim resolved. Check `claimed` — false means another session holds it.

- object
  - `node` object
  - `claimed` boolean
  - `heldBy` integer, nullable

## Other responses

- `400`: Request body/query failed Zod validation.
- `401`: Missing or invalid credentials.
- `404`: Node or agent session not found.

---

[API](https://skmtc.dev/contextq/apis/contextq-api.md) · [All operations](https://skmtc.dev/contextq/apis/contextq-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contextq/apis/contextq-api/revisions/7afc44056a22?raw)