# Colabra

> Colabra is the AI workspace for M&A due diligence. It turns sell-side document dumps into a clause-linked risk register, entity map, and live gap analysis.

Use this file as the curated starting point for understanding Colabra, connecting to its API or MCP server, and evaluating trust and operational fit.

## Preferred entry points

- [Product site](https://www.colabra.ai/): Homepage and product positioning for the AI workspace used in M&A due diligence.
- [Docs home](https://www.colabra.ai/docs/): Product documentation hub.
- [API overview](https://www.colabra.ai/docs/api/overview/): REST API surface, response conventions, and integration model.
- [Authentication](https://www.colabra.ai/docs/api/authentication/): Service-account auth, user auth, and MCP OAuth details.
- [Resource endpoints](https://www.colabra.ai/docs/api/resource-endpoints/): Read/search routes for projects, tasks, files, structured evidence, entities, and requests.
- [Writeback endpoints](https://www.colabra.ai/docs/api/writeback-endpoints/): Mutation routes for requests, comments, text templates, and evidence uploads.
- [MCP guide](https://www.colabra.ai/docs/mcp-and-integrations/mcp/): Remote MCP setup for ChatGPT, Claude, Codex, and other tools.
- [Trust and security](https://www.colabra.ai/trust/): Security posture, compliance, backups, and data handling.
- [Responsible disclosure](https://www.colabra.ai/rdp/): Security disclosure policy and contact details.
- [OpenAPI spec](https://www.colabra.ai/openapi.json): Machine-readable REST API specification.

## Preferred Markdown docs

- [Docs home (Markdown)](https://www.colabra.ai/docs.md)
- [API overview (Markdown)](https://www.colabra.ai/docs/api/overview.md)
- [Authentication (Markdown)](https://www.colabra.ai/docs/api/authentication.md)
- [Resource endpoints (Markdown)](https://www.colabra.ai/docs/api/resource-endpoints.md)
- [Writeback endpoints (Markdown)](https://www.colabra.ai/docs/api/writeback-endpoints.md)
- [MCP guide (Markdown)](https://www.colabra.ai/docs/mcp-and-integrations/mcp.md)

## Integration facts

- Primary product: AI workspace for M&A due diligence.
- Core workflows: evidence review, workstreams, checklist tasks, requests, versioned project outputs, and custom Colabra AI deliverables.
- External MCP clients use scoped source access; tool availability depends on the connection profile and permissions.
- REST API host: `https://api.colabra.ai`
- REST API base: `https://api.colabra.ai/v1`
- Remote MCP URL: `https://api.colabra.ai/mcp`
- MCP OAuth authorization server metadata: `https://api.colabra.ai/.well-known/oauth-authorization-server`
- MCP protected resource metadata: `https://api.colabra.ai/.well-known/oauth-protected-resource/mcp`
- Published MCP OAuth scope: `mcp:tools`
- Preferred machine-readable resources: `llms.txt`, `llms-full.txt`, Markdown docs under `/docs*.md`, and `openapi.json`.

## Trust and operations

- Trust page: https://www.colabra.ai/trust/
- Responsible disclosure: https://www.colabra.ai/rdp/
- Security contact: `mailto:trust@colabra.ai`
- Status page: https://status.colabra.ai
- Stated trust signals: SOC 2 Type II, regular third-party penetration testing, GDPR and CCPA compliance, SAML SSO, SCIM, MFA, encryption at rest and in transit, and explicit no-training-on-customer-data language.

## Extended documentation

The sections below inline the key product and integration documentation in Markdown-friendly form.

## Docs home

Canonical URL: https://www.colabra.ai/docs/
Markdown URL: https://www.colabra.ai/docs.md

# Start here

Colabra AI turns deal evidence into source-linked findings, financial models, and investment memos. These guides walk through setting up a project, reviewing the evidence, and preparing your diligence work for review.

## Start your first review

1. [Create a project](/docs/setting-up/setting-up-a-deal/) and confirm the target and review scope.
2. [Add evidence](/docs/data-dump-to-structure/ingesting-documents/) and check processing.
3. [Ask Colabra AI](/docs/running-your-practice/ai-copilot/) a specific question or request a deliverable.
4. Review sources and follow up through the [checklist and requests](/docs/work-management/diligence-tasks/).
5. Prepare and file the relevant [project output](/docs/reporting-and-closing/generating-reports/).

## Product walkthrough




## Follow the deal lifecycle

  [Why Colabra Storage is not analysis](/docs/why-colabra/not-another-data-room/)
  [Core concepts Workspace, project, findings](/docs/why-colabra/core-concepts/)
  [Setting up a deal Project and team setup](/docs/setting-up/setting-up-a-deal/)
  [Data dump to structure Ingest, sort, extract, reconcile](/docs/data-dump-to-structure/ingesting-documents/)
  [Flag and screen Thresholds, risks, gaps](/docs/flag-and-screen/guardrails-and-thresholds/)
  [Run the diligence Tasks, requests, decisions](/docs/working-as-a-team/external-requests/)
  [Reporting and closing Reports, exports, views](/docs/reporting-and-closing/generating-reports/)
  [MCP & integrations Storage, transcripts, alerts](/docs/mcp-and-integrations/overview/)

## API overview

Canonical URL: https://www.colabra.ai/docs/api/overview/
Markdown URL: https://www.colabra.ai/docs/api/overview.md

# API overview

Use the `/v1` REST API for authenticated software integrations. Use [MCP](/docs/mcp-and-integrations/mcp/) for an AI client that should discover tools and follow governed evidence routes. The two surfaces share resource handling, but their exposed capabilities and authentication are not interchangeable.

## Base URL and authentication

```bash
export COLABRA_API_URL="https://api.colabra.ai"
```

Obtain a bearer token through the appropriate [authentication flow](/docs/api/authentication/). API access and individual operations remain subject to workspace entitlements and resource permissions.

## Confirm identity and scope

```bash
curl "$COLABRA_API_URL/v1/me" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

Use a workspace ID returned by the API, then select a project:

```bash
curl "$COLABRA_API_URL/v1/projects?workspaceId=$WORKSPACE_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

Pass workspace scope explicitly for integrations that can access multiple workspaces. Do not infer permission from knowing a project or file ID.

## Public IDs

| Resource | Format |
| --- | --- |
| Workspace | `ws_` followed by the returned identifier |
| Project | `PRO-42` |
| Task | `TSK-7` |
| File | `FIL-104` |
| Entity | `ENT-` followed by the returned identifier |
| Request | `REQ-3` |
| Template | `template_` followed by the returned identifier |
| Comment | `cmt_` followed by the returned identifier |
| Service account | `apik_` followed by the returned identifier |

Copy IDs from responses. Database UUIDs, raw storage identifiers, and hand-constructed aliases are not interchangeable with public IDs.

## Response envelope

Successful resource responses use an envelope with `ok`, `data`, and `meta`:

```json
{
  "ok": true,
  "data": ,
  "meta":
}
```

Errors include a machine-readable code, message, and retryability:

```json
{
  "ok": false,
  "error":
}
```

Inspect the response status and error before retrying. Honor `Retry-After` when supplied, and use idempotency keys on supported mutations.

## Pagination and evidence freshness

Treat cursors and route tokens as opaque. Replay returned continuation arguments without constructing or changing tokens. Keep the same scope and filters while paging unless the endpoint explicitly permits a change.

Preserve version, freshness, and coverage metadata when using evidence. A bounded response or search result does not establish complete coverage. If a source changes or access expires, obtain a new authorized route instead of reusing stale evidence authority.

The previous `/v1/files//content` interface is no longer the source-reading contract. AI clients should follow the current MCP source routes. The previous report CRUD and report-generation routes are also retired; use project Outputs or Colabra AI for deliverables.

Continue with [Resource endpoints](/docs/api/resource-endpoints/) and [Writeback endpoints](/docs/api/writeback-endpoints/).

## Authentication

Canonical URL: https://www.colabra.ai/docs/api/authentication/
Markdown URL: https://www.colabra.ai/docs/api/authentication.md

# Authentication

## Recommended auth choices

| Use case | Recommended method |
| --- | --- |
| Server-to-server automation | Service account |
| User-driven CLI or tool login | Magic code or CLI browser login |
| AI client with user consent | MCP OAuth |

Choose the auth flow based on who is acting:

- a backend service should use a **service account**
- a human operator in a tool or CLI should use a **user login flow**
- an MCP client acting on behalf of a signed-in user should use **OAuth**

## Service-account flow

Service accounts are created at the workspace level and exchange `clientId` plus `clientSecret` for bearer tokens.

```bash
curl -X POST "$COLABRA_API_URL/v1/auth/service-account/token" \
  -H "Content-Type: application/json" \
  -d ''
```

The response returns:

- `access_token`
- `refresh_token`
- `expires_in_seconds`
- service-account metadata

Use the returned bearer token on `/v1` requests.

This is the default for scheduled jobs, internal automations, and system-to-system integrations where no person is present at runtime.

## Refresh and logout

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/v1/auth/refresh` | Rotate a refresh token into a new access-token pair |
| `POST` | `/v1/auth/logout` | Revoke the active bearer token and optional refresh token |

`/v1/auth/refresh` requires both `refreshToken` and `clientId`.

## User login flows

### Magic-code login

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/v1/auth/login/start` | Start login by email, optionally with a CLI redirect URI |
| `POST` | `/v1/auth/magic-code/start` | Send a magic code directly |
| `POST` | `/v1/auth/magic-code/verify` | Exchange `email` and `code` for tokens |

Use this flow for operator-facing tooling where a human can receive and enter a code.

### CLI browser login

The CLI/browser flow is designed for tools that want to hand off login to the browser and then poll until completion.

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/v1/auth/cli/start` | Starts a browser-based CLI login flow |
| `GET` | `/v1/auth/cli/browser-complete` | Browser completion endpoint |
| `GET` | `/v1/auth/cli/poll` | Polls for pending, complete, or error state |
| `GET` | `/v1/auth/cli/callback` | SSO callback for CLI flows |

## Identity and workspace context

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/me` | Return the authenticated principal and visible workspaces |
| `GET` | `/v1/workspaces` | List workspaces the principal can access |

## Service-account management

These endpoints require a **user** principal with workspace integration permissions.

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/service-accounts` | List service accounts for a workspace |
| `POST` | `/v1/service-accounts` | Create a new service account |
| `POST` | `/v1/service-accounts//rotate` | Rotate credentials |
| `POST` | `/v1/service-accounts//revoke` | Revoke the service account |

When a service account is created, Colabra also generates a webhook signing secret.

## MCP OAuth

The MCP server uses OAuth endpoints rather than service-account bearer exchange.

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/.well-known/oauth-authorization-server` | OAuth server metadata |
| `GET` | `/.well-known/oauth-protected-resource/mcp` | Protected resource metadata |
| `GET` | `/mcp/oauth/authorize` | Authorization step |
| `POST` | `/mcp/oauth/authorize/decision` | Consent decision |
| `POST` | `/mcp/oauth/register` | Dynamic client registration |
| `POST` | `/mcp/oauth/token` | Token exchange |

The MCP scope currently exposed is `mcp:tools`.

Use MCP OAuth only for MCP clients. It is not a general replacement for bearer-token auth on `/v1`.

## Resource endpoints

Canonical URL: https://www.colabra.ai/docs/api/resource-endpoints/
Markdown URL: https://www.colabra.ai/docs/api/resource-endpoints.md

# Resource endpoints

The following `/v1` routes use bearer authentication. They are an endpoint map, not a promise that every route is exposed through MCP. Evidence operations may additionally require a current session and server-issued route arguments.

## Workspace configuration

Use the public `ws_…` workspace ID in these paths.

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/workspaces//diligence-settings` | Workspace diligence defaults |
| `GET` | `/v1/workspaces//ai-settings` | AI configuration |
| `GET` | `/v1/workspaces//ai-prompts` | Saved prompts |
| `GET` | `/v1/workspaces//workflow-settings` | Workflow configuration |
| `GET` | `/v1/workspaces//property-definitions` | Custom property definitions |
| `GET` | `/v1/templates` | Workspace text templates |
| `GET` | `/v1/templates/` | One text template, using its public `template_…` ID |

## Projects and tasks

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/projects` | Select a project in a workspace |
| `GET` | `/v1/projects/` | Project details |
| `GET` | `/v1/projects//diligence-settings` | Effective project settings |
| `GET` | `/v1/projects//overview` | Bounded project orientation |
| `GET` | `/v1/projects//qoe` | Project financial analysis |
| `GET` | `/v1/projects//gap-analysis` | Persisted checklist coverage |
| `GET` | `/v1/tasks` | Task list |
| `GET` | `/v1/tasks/` | Selected task |
| `GET` | `/v1/tasks//files` | Evidence linked to the task |

List responses can be paginated. Follow the returned continuation rather than assuming the first page contains the complete project.

## Files and structured evidence

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/v1/files/search` | Search for candidate source files |
| `POST` | `/v1/files/search/batch` | Submit independent source searches |
| `GET` | `/v1/files` | List files in the selected scope |
| `GET` | `/v1/files/` | Selected file metadata |
| `GET` | `/v1/files//status` | Processing status |
| `GET` | `/v1/files//structured` | Available file-derived structure |
| `GET` | `/v1/structured-data/catalog` | Discover supported structured-data schemas |
| `GET` | `/v1/projects//structured-artifacts` | Discover extracted artifacts |
| `GET` | `/v1/projects//structured-data/rows` | Query one supported row schema |
| `POST` | `/v1/projects//structured-data/rows/aggregate` | Governed aggregation over structured rows |
| `GET` | `/v1/projects//contract-matrix` | Contract and clause inventory |
| `GET` | `/v1/projects//file-relationships` | Document version and relationship context |
| `POST` | `/v1/files/grep` | Literal search in processed source text |
| `POST` | `/v1/files/diff` | Compare two selected source files |

Inspect the catalog before choosing structured fields and filters. Use aggregation for totals and counts when supported. An extracted row or search result routes a reviewer to evidence; it does not replace checking the operative source for a material conclusion.

For an AI integration, use the [MCP source workflow](/docs/mcp-and-integrations/mcp/), including its exact source and continuation routes. Do not reconstruct source URLs from file IDs or use the retired `/content` endpoint.

## Entities

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/entities` | Entities in the authorized scope |
| `POST` | `/v1/entities/search` | Find an entity |
| `GET` | `/v1/entities//overview` | Selected entity with linked-source context |
| `GET` | `/v1/entities//risk` | Available risk-domain observations |
| `GET` | `/v1/entities//files` | Linked evidence |
| `GET` | `/v1/entities//graph` | Relationship context |

Entity discovery requires an explicit project. Screening observations and relationship hints should be checked against current sources before treating them as identity or risk conclusions.

## Requests and comments

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/requests` | Requests in the selected scope |
| `GET` | `/v1/requests/` | One request |
| `GET` | `/v1/comments` | Discussion for a selected target |

See [Writeback endpoints](/docs/api/writeback-endpoints/) for supported mutations. Project and entity `/bundle` routes and the old report routes have been replaced or retired; do not build new integrations around them.

## Writeback endpoints

Canonical URL: https://www.colabra.ai/docs/api/writeback-endpoints/
Markdown URL: https://www.colabra.ai/docs/api/writeback-endpoints.md

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

## MCP guide

Canonical URL: https://www.colabra.ai/docs/mcp-and-integrations/mcp/
Markdown URL: https://www.colabra.ai/docs/mcp-and-integrations/mcp.md

# MCP

Connect your AI client to Colabra when it needs to investigate live deal evidence. Each user signs in with their own Colabra account; workspace and project permissions continue to apply.

## Choose a plugin or a connector

| Connection | What it provides |
| --- | --- |
| **Colabra plugin**, in supported clients | Colabra workflow skills and supporting tools, plus authenticated evidence access |
| **Remote MCP connector** | Access to the capabilities exposed by the Colabra server in that client; it does not install local plugin skills or report helpers |

Start from **Settings → Integrations** in Colabra for the setup and downloads available to your workspace. Your AI workspace administrator may need to enable Colabra before individual users can connect.

The hosted MCP endpoint is:

```text
https://api.colabra.ai/mcp
```

Use remote HTTP MCP with OAuth. A service-account token for the REST API is a separate authentication flow.

## What the connector can do

Available tools depend on the connection’s permissions and capability profile. The default review profile emphasizes current source evidence.

| Area | Available workflow |
| --- | --- |
| **Select a deal** | Identify your workspace and project before reading private evidence |
| **Find evidence** | Search and list files, inspect selected file details, and follow source routes |
| **Read sources** | Open processed source passages with version and location context |
| **Compare and calculate** | Query supported structured data, aggregate rows, and compare selected documents |
| **Investigate entities** | Find entities, linked evidence, and relationship context within the selected project |
| **Follow up** | Inspect requests and, when enabled and explicitly requested, create or resolve requests, add comments, or upload evidence |

The tool list exposed in your client is authoritative for that connection. Existing analysis, task, and risk-summary tools may require a broader profile. The connector does not expose the app’s complete internal findings register or the old report-create and report-generate tools.

## A useful first session

Ask the client to:

1. Confirm the workspace and project by name.
2. Find the source evidence relevant to a specific question.
3. Open the current passages before drawing material conclusions.
4. Distinguish supported facts, conflicting evidence, and missing information.
5. Prepare the requested answer or deliverable, with source references.

For example: “Review the customer agreements in this project for transfer restrictions. Identify the operative agreement and amendments, cite the relevant language, and draft questions for anything unresolved.”

Ask separately to save a comment, create a seller request, or upload a file when you want the project record changed. A local deliverable created by the external client is not automatically a project report.

## Source coverage

MCP reads are scoped and paginated. A search hit identifies a candidate source; it is not a complete review. A passage may cover only part of a document. Clients should follow the returned source and continuation routes and retain the reported coverage limits.

The connector provides processed evidence access. It is not a bulk-download interface for the original data room. Use the app’s permitted export controls for that task.

## Client guides

- [Claude and Cowork](/docs/mcp-and-integrations/claude/)
- [OpenAI Codex](/docs/mcp-and-integrations/codex/)
- [OpenAI ChatGPT](/docs/mcp-and-integrations/chatgpt/)
- [Google Gemini](/docs/mcp-and-integrations/gemini/)
- [Microsoft Copilot](/docs/mcp-and-integrations/microsoft-copilot/)

## OAuth discovery

Clients should discover OAuth settings automatically. If manual configuration is required, use:

| Setting | URL |
| --- | --- |
| Authorization metadata | `https://api.colabra.ai/.well-known/oauth-authorization-server` |
| Protected resource metadata | `https://api.colabra.ai/.well-known/oauth-protected-resource/mcp` |
| Token endpoint | `https://api.colabra.ai/mcp/oauth/token` |

If no tools appear, check that Colabra is enabled in the current AI workspace, complete sign-in, and confirm access to the intended project. For software integrations, see the [REST API overview](/docs/api/overview/).