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

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

## Response envelope

All `/v1` endpoints return a consistent envelope:

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

Errors return:

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

## 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//content` can return:

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

## Quick example

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

## Common build path

Most integrations follow this sequence:

1. choose the auth model in [Authentication](/docs/api/authentication/)
2. read data through [Resource endpoints](/docs/api/resource-endpoints/)
3. mutate state through [Writeback endpoints](/docs/api/writeback-endpoints/) when needed