# 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//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

```bash
curl -X POST "$COLABRA_API_URL/v1/requests" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d ''
```

## Text templates

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/v1/templates` | Create a workspace text template; requires `workspaceId` and `name` |
| `POST` | `/v1/templates/` | Update a template using its public `template_…` ID |
| `POST` | `/v1/templates//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](/docs/reporting-and-closing/generating-reports/) for the standard reporting set, or [Colabra AI](/docs/running-your-practice/ai-copilot/) 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

```bash
curl -X POST "$COLABRA_API_URL/v1/files" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d ''
```

## 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.