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
• create or update a report
• 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, report, 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"
  }'

Reports and templates

Method	Path	Purpose	Notes
POST	/v1/reports	Create a new report	Requires projectId; optional name, summary, bodyMarkdown, assigneeId
POST	/v1/reports/{reportId}	Update a report	Supports name, summary, bodyMarkdown, assigneeId
POST	/v1/reports/generate	Queue AI report generation	Requires projectId, templateId, and phase
POST	/v1/templates	Create a workspace text template	Requires workspaceId and name
POST	/v1/templates/{templateUuid}	Update a workspace text template	Supports name and summary
POST	/v1/templates/{templateUuid}/delete	Soft-delete a workspace text template	Returns { deleted: true }

Example: generate a report

curl -X POST "$COLABRA_API_URL/v1/reports/generate" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "'"$WORKSPACE_ID"'",
    "projectId": "PRO-42",
    "templateId": "dd-red-flag-memo",
    "phase": "PHASE_1",
    "focusInstructions": "Bias towards commercial concentration risk and change-of-control clauses."
  }'

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 MB after base64 decoding.

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 report generation for structured outputs and Templates for reusable drafting snippets.

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.