DottaandPaperclip
0d7ecfa96d
Keep all fixture and production sources fixed except the stock discovery description and clickable-link recipe in the two operational skill sources. Co-Authored-By: Paperclip <noreply@paperclip.ing>
1.9 KiB
Issue documents through the API
Use this procedure for requested Paperclip task documents in API-based runtimes. Honor a destination explicitly chosen by the requester. Native Runner runtimes use their document tool and its contract. Downloadable files follow artifacts.md.
Create a document
Use the injected PAPERCLIP_API_URL and bearer PAPERCLIP_API_KEY. Include
X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID on the write and send JSON with
Content-Type: application/json.
Choose a descriptive document key such as report; keys use lowercase letters,
numbers, underscores, or hyphens and are at most 64 characters. Plans use plan.
PUT /api/issues/{issueId}/documents/{key}
{
"title": "Task report",
"format": "markdown",
"body": "# Task report\n\nThe requested findings.",
"baseRevisionId": null
}
A successful write returns HTTP 201 for creation or 200 for an update,
with the saved document JSON. Check its key, body, and latestRevisionId
before claiming delivery. This receipt is sufficient; another GET is unnecessary
when it confirms the intended content and a saved revision.
Link the returned document key in the completion comment or response:
/<prefix>/issues/<issue-identifier>#document-<returned-key>.
Use the returned key because a locked document can redirect an agent's write
to a new document.
Update or resolve an unclear write
For an existing document, first GET /api/issues/{issueId}/documents/{key}
and read its body and latestRevisionId. Send the updated body with
baseRevisionId set to that revision. On 409, fetch the latest document and
reconcile changes before retrying; preserve the skill's bounded-write retry rule.
If a write's status or receipt is unclear, GET the document to check the saved content and revision before retrying. If delivery cannot be confirmed, report that limitation instead of claiming the requested document was saved.