API overview

Use the /v1 REST API for authenticated software integrations. Use 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

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

Obtain a bearer token through the appropriate authentication flow. API access and individual operations remain subject to workspace entitlements and resource permissions.

Confirm identity and scope

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

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

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:

{
  "ok": true,
  "data": {},
  "meta": {
    "fetched_at": "2026-09-09T12:00:00.000Z"
  }
}

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

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

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/{fileId}/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 and Writeback endpoints.