API overview

Colabra currently exposes two different integration surfaces. They are related, but they are not interchangeable.

This page is the map. Read it first if you are deciding whether to build against /v1 or connect an AI client over MCP.

Choose the right surface

Surface	Auth model	Best for	Notes
`/v1` REST API	Bearer token	Most integrations and automations	Richest public surface
MCP server	OAuth	AI clients and interactive assistants	Mirrors core read/write capabilities as tools

The practical distinction is simple:

choose /v1 when your own software needs predictable API calls
choose MCP when an interactive AI client should explore and act on live Colabra context with user-approved access

If you are building an unattended workflow, start with /v1. If you are wiring up ChatGPT, Claude, Codex, or another assistant, start with MCP.

Base URL

Use your Colabra API host:

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

Response envelope

All /v1 endpoints return a consistent envelope:

{
  "ok": true,
  "data": {},
  "meta": {
    "fetched_at": "2026-03-15T12:34:56.000Z"
  }
}

Errors return:

{
  "ok": false,
  "error": {
    "code": "invalid_payload",
    "message": "projectId is required",
    "retryable": false
  }
}

Common conventions

Public IDs

Colabra uses readable IDs in the API:

PRO-42 for projects
TSK-7 for tasks
FIL-104 for files
RPT-11 for reports
ENT-... for entities
REQ-3 for requests
apik_... for service accounts

Workspace scoping

Many endpoints infer workspaceId from the authenticated principal, but most integrations should still pass it explicitly when the resource is workspace-scoped.

Pagination

Where supported, list endpoints return cursor metadata such as next_cursor. Cursor style depends on the resource:

numeric sequence cursors for projects, tasks, and reports
raw UUID-style cursors for entity lists

Freshness metadata

Analysis-heavy endpoints often return:

freshness
source_file_version_ids
analysis_updated_at
entity_enriched_at

Treat that metadata as part of the contract. It tells you whether you are looking at ready output, stale output, or missing output.

Search endpoints use `POST`

File and entity search both accept request bodies rather than long query strings, which makes filters and search text easier to manage.

File content may be chunked

GET /v1/files/{fileId}/content can return:

chunked text with a locator
a direct image URL
an image or summary fallback when text extraction is unavailable

Quick example

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

Common build path

Most integrations follow this sequence:

choose the auth model in Authentication
read data through Resource endpoints
mutate state through Writeback endpoints when needed