mirror of
https://github.com/paperclipai/paperclip
synced 2026-04-25 17:25:15 +02:00
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:
@@ -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).
|
||||
|
||||
@@ -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
|
||||
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user