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:
parent
fdb20d5d08
commit
4ebc12ab5a
2 changed files with 16 additions and 1 deletions
|
|
@ -38,11 +38,13 @@ POST /api/companies/{companyId}/goals
|
||||||
```
|
```
|
||||||
PATCH /api/goals/{goalId}
|
PATCH /api/goals/{goalId}
|
||||||
{
|
{
|
||||||
"status": "completed",
|
"status": "achieved",
|
||||||
"description": "Updated description"
|
"description": "Updated description"
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Valid status values: `planned`, `active`, `achieved`, `cancelled`.
|
||||||
|
|
||||||
## Projects
|
## Projects
|
||||||
|
|
||||||
Projects group related issues toward a deliverable. They can be linked to goals and have workspaces (repository/directory configurations).
|
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.
|
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
|
## Release Task
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue