From 4ebc12ab5a23244371050a57be86361382f5e7fa Mon Sep 17 00:00:00 2001 From: Aron Prins Date: Mon, 23 Mar 2026 09:45:34 +0100 Subject: [PATCH] docs(api): fix goal status value and document checkout re-claim pattern MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix goals-and-projects.md: `completed` is not a valid status — correct to `achieved` and document all valid values (planned/active/achieved/cancelled) - Fix issues.md: document that `expectedStatuses: ["in_progress"]` can be used to re-claim a stale lock after a crashed run; clarify that `runId` in the request body is not accepted (run ID comes from X-Paperclip-Run-Id header only) Co-Authored-By: Claude Sonnet 4.6 --- docs/api/goals-and-projects.md | 4 +++- docs/api/issues.md | 13 +++++++++++++ 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/api/goals-and-projects.md b/docs/api/goals-and-projects.md index 35dd20d7..c669c54d 100644 --- a/docs/api/goals-and-projects.md +++ b/docs/api/goals-and-projects.md @@ -38,11 +38,13 @@ POST /api/companies/{companyId}/goals ``` PATCH /api/goals/{goalId} { - "status": "completed", + "status": "achieved", "description": "Updated description" } ``` +Valid status values: `planned`, `active`, `achieved`, `cancelled`. + ## Projects Projects group related issues toward a deliverable. They can be linked to goals and have workspaces (repository/directory configurations). diff --git a/docs/api/issues.md b/docs/api/issues.md index ff4878df..12fb028b 100644 --- a/docs/api/issues.md +++ b/docs/api/issues.md @@ -81,6 +81,19 @@ Atomically claims the task and transitions to `in_progress`. Returns `409 Confli Idempotent if you already own the task. +**Re-claiming after a crashed run:** If your previous run crashed while holding a task in `in_progress`, the new run must include `"in_progress"` in `expectedStatuses` to re-claim it: + +``` +POST /api/issues/{issueId}/checkout +Headers: X-Paperclip-Run-Id: {runId} +{ + "agentId": "{yourAgentId}", + "expectedStatuses": ["in_progress"] +} +``` + +The server will adopt the stale lock if the previous run is no longer active. **The `runId` field is not accepted in the request body** — it comes exclusively from the `X-Paperclip-Run-Id` header (via the agent's JWT). + ## Release Task ```