Writeback endpoints

These endpoints mutate Colabra state. Use them with bearer auth.

Read this page as the “save work back into the project” layer. The common writeback actions are:

• create or resolve a request
• add a comment or reply in context
• upload a new file
• manage reusable templates

Requests and comments

Method	Path	Purpose	Notes
GET	/v1/requests	List open requests	Filter with workspaceId, optional projectId, optional taskId
POST	/v1/requests	Create a request tied to a task	Requires taskId, title, body
POST	/v1/requests/{requestId}/resolve	Resolve a request through its thread	Can use body; defaults to "Resolved"
GET	/v1/comments	List comments for a target	Supports targets such as project, task, file, entity, request
POST	/v1/comments	Create a top-level comment or thread action	Requires targetId and bodyMarkdown
POST	/v1/comments/reply	Reply to a comment	Requires targetId, parentCommentId, bodyMarkdown

Idempotency

The request and comment creation flows support idempotencyKey in the request body. Use it when retries are possible and duplicate comments or requests would be harmful.

Example: create a request

curl -X POST "$COLABRA_API_URL/v1/requests" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "'"$WORKSPACE_ID"'",
    "taskId": "TSK-7",
    "title": "Provide signed customer schedule",
    "body": "The latest version is unsigned and missing the latest renewal terms.",
    "idempotencyKey": "req-pro42-task7-customer-schedule"
  }'

Text templates

Method	Path	Purpose
POST	/v1/templates	Create a workspace text template; requires workspaceId and name
POST	/v1/templates/{templateId}	Update a template using its public template_… ID
POST	/v1/templates/{templateId}/delete	Soft-delete a template

Text templates contain reusable wording. They are separate from project outputs and AI-generated files.

Reports and deliverables

The old /v1/reports create/update and /v1/reports/generate routes are no longer registered. Use Project reports and outputs for the standard reporting set, or Colabra AI for custom deliverables.

An external client may create a local document using its own tools. Upload it as evidence only when the user wants that file added to the project; this does not create a versioned project output.

File upload

Method	Path	Purpose	Notes
POST	/v1/files	Upload a standalone project file	Requires projectId, filename, and contentBase64

Optional fields on upload:

• mimeType
• provider
• metadata

Enforced limit: 20 MiB (20,971,520 bytes) after base64 decoding. The API upload limit is separate from browser upload limits. Supply an idempotencyKey for safe retries; MCP uploads require one.

Upload example

curl -X POST "$COLABRA_API_URL/v1/files" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "'"$WORKSPACE_ID"'",
    "projectId": "PRO-42",
    "filename": "customer-master-services-agreement.pdf",
    "mimeType": "application/pdf",
    "contentBase64": "'"$BASE64_CONTENT"'"
  }'

Writeback rules worth keeping

• Create requests from the task that owns the work, not from a side channel.
• Keep comment bodies in Markdown so they are consistently rendered to HTML server-side.
• Use text templates for reusable drafting snippets and project Outputs for reviewed reports.

In other words: write back into the same object model the team already uses. That is what keeps the integration aligned with the live diligence workflow instead of creating parallel records elsewhere.