paperclip_upsert_document
Create or update a document on an issue, with optimistic concurrency control using a base revision ID.
Instructions
Create or update an issue document. Send baseRevisionId for safe concurrent updates.
Args:
issueId: string — Issue ID or identifier (example: "PAP-42")
key: string — Document key (example: "plan")
title: string — Document title
body: string — Document body (markdown)
format: "markdown" (optional) — Document format (default: markdown)
baseRevisionId: string (optional) — Current revision ID from a prior get; omit on first create
Returns: Returns the updated document object: key, title, body, revisionId, updatedAt.
Examples:
Use when: writing or updating the implementation plan document on an issue mid-run
Don't use when: you want to delete a document — use paperclip_delete_document (board-only)
Error Handling:
400: validation failure → check title and body are non-empty
401: authentication failed → check PAPERCLIP_API_KEY
404: issue not found → verify ID with paperclip_list_issues
409: conflict — baseRevisionId mismatch → re-read with paperclip_get_document and retry
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| issueId | Yes | Issue ID or identifier (e.g. PAP-22) | |
| key | Yes | Document key (e.g. `plan`) | |
| title | Yes | Document title | |
| body | Yes | Document body (markdown) | |
| format | No | Document format (default: markdown) | |
| baseRevisionId | No | Current revision ID for optimistic concurrency — omit on first create |