docs(api): fix goal status value and document checkout re-claim pattern

- 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 <noreply@anthropic.com>
This commit is contained in:
Aron Prins
2026-03-23 09:45:34 +01:00
parent fdb20d5d08
commit 4ebc12ab5a
2 changed files with 16 additions and 1 deletions

View File

@@ -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).

View File

@@ -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
```