API and AI agents
Scripts and AI agents can work with your Colletta documents as you, with a personal API token or by connecting an app such as Claude or ChatGPT. Either way it sees only what you can see, and does only what you allowed when you made the token or connected the app:
| Choice | What it can do |
|---|---|
| Read only | list, search and read documents, comments and versions |
| Read, suggest and comment | also suggest changes, comment, reply and create drafts |
| Read, suggest, comment and edit | also change text directly, where an Owner allows it |
Everything it writes shows as you via the token or app, such as “Alice via Claude”. A suggestion changes nothing until someone accepts it, and a draft stays private to you until you publish it. Allowing more than reading needs a two-factor sign-in. Each workspace’s Owners and Admins also choose what agents may do there (see the end of this page).
If a workspace turns off Viewers can download, export, print and duplicate (see Sharing settings), a token can’t export the documents you can only view there.
There are three ways in:
- the API at
/api/v1, with a token, for scripts and your own tools, - the MCP server at
/mcp, with a token, for AI agents such as Claude Code, Cursor and VS Code, - the same MCP server for chat apps such as Claude and ChatGPT, which you connect by signing in instead of with a token.
The examples below use https://app.colletta.app, the hosted app. If you open Colletta at another address, use that
instead.
Make a token
Section titled “Make a token”- Choose Settings at the bottom of the sidebar, then API tokens under Your account.
- Give the token a Name that says what it’s for, such as “Release notes script”.
- Under Workspaces, choose one workspace, or All my workspaces.
- Under Can, choose Read only, Read, suggest and comment, or Read, suggest, comment and edit.
- Under Expires in, choose 7 days, 30 days, 90 days or 1 year. Every token expires.
- Choose Create token, then Copy the token straight away. It’s shown only once.
Keep a token secret, like a password. Anyone who has it can do what the token can, as you. It starts with cmb_pat_, which
makes it easy for secret scanners to spot if it ends up somewhere it shouldn’t.
You can have up to 20 active tokens. The page lists each one with its workspace, what it can do, its expiry and when it was last used. Expired and revoked tokens stay on a separate list for 30 days.
Choose one workspace when you can
Section titled “Choose one workspace when you can”A token for one workspace can’t see anything in your other workspaces. If it leaks, less is exposed, and if you leave that workspace the token stops working.
Stop a token
Section titled “Stop a token”- Revoke one token on the API tokens page. Anything using it stops working at once.
- Revoke all API tokens, in your account menu or on the API tokens page, stops all of them.
Logging out, even with Log out everywhere, does not stop your tokens. Tokens are meant for scripts and agents that keep running after you close your browser. Revoke them when you no longer need them.
A token also stops working when it expires, and a token for one workspace stops when you leave that workspace or the workspace is deleted.
Use the API
Section titled “Use the API”Send the token in an Authorization header on every request:
curl -H "Authorization: Bearer cmb_pat_..." https://app.colletta.app/api/v1/workspaces| Request | What you get |
|---|---|
GET /api/v1/me | who the token acts for, its workspace and when it expires |
GET /api/v1/workspaces | your workspaces and your role in each |
GET /api/v1/workspaces/{id}/tree | the folders and documents you can see |
GET /api/v1/workspaces/{id}/search?q=... | search results, with passages and where the matches are |
GET /api/v1/workspaces/{id}/recent | recently edited documents, by whom and when |
GET /api/v1/documents/{id} | a document’s title, folder and last edit |
GET /api/v1/documents/{id}/markdown | the document’s markdown |
GET /api/v1/documents/{id}/comments | the document’s comment threads |
GET /api/v1/documents/{id}/versions | the document’s saved versions, newest first |
GET /api/v1/documents/{id}/versions/{version} | a version’s markdown (current for the text now) |
GET /api/v1/documents/{id}/compare | what changed between two versions, as a diff |
Write requests need the token permission shown below, your own access to the document, and the workspace’s approval for agents (see the end of this page).
| Request | What it does | Token permission |
|---|---|---|
POST /api/v1/documents/{id}/suggestions | suggests replacing a passage | Read, suggest and comment |
POST /api/v1/documents/{id}/comments | starts a comment thread on a passage | Read, suggest and comment |
POST /api/v1/threads/{id}/replies | replies in a thread | Read, suggest and comment |
POST /api/v1/workspaces/{id}/documents | creates a document as your draft | Read, suggest and comment |
POST /api/v1/documents/{id}/edits | changes a passage directly | Read, suggest, comment and edit |
A request names a passage by quoting its words exactly as the markdown shows them. If the words appear more than once, it’s refused unless the request quotes more of them or says which occurrence it means.
The full description, in OpenAPI format, is at https://app.colletta.app/api/v1/openapi.json. Anyone can read it,
without a token, and most API tools can import it.
The API is versioned by its path, /api/v1. A breaking change comes only in a new path version, and the previous
version keeps working for at least 6 months, with notice in the changelog.
The raw .md link from Copy raw .md link also accepts a token, so a script can fetch a document by the same link
you’d open in the browser:
curl -H "Authorization: Bearer cmb_pat_..." https://app.colletta.app/api/documents/<id>.mdWhat a token can see
Section titled “What a token can see”A token sees exactly what its person can see, checked on every request. Restricted documents you can’t open stay hidden, and if you lose access to something, the next request already reflects it. Anything outside the token’s workspace, or that you can’t open, answers “not found”, as if it didn’t exist.
Each token can make 60 requests in a burst, then one a second. Past that, requests are refused with status 429 and a
Retry-After header saying when to try again. A missing, expired or revoked token gets status 401.
Connect an AI agent (MCP)
Section titled “Connect an AI agent (MCP)”Colletta has a server for the Model Context Protocol (MCP) at /mcp. It lets an AI agent search and read your
documents while it works, and suggest, comment or edit if you allowed it.
In Claude Code, run:
claude mcp add --transport http colletta https://app.colletta.app/mcp --header "Authorization: Bearer cmb_pat_..."Cursor and VS Code take the same address and header in their MCP settings.
Every agent gets the reading tools:
| Tool | What it does |
|---|---|
list_workspaces | lists your workspaces |
list_documents | lists a workspace’s documents with their folder paths |
search | searches one workspace, or each of your workspaces |
read_document | reads a document’s markdown, by id or by its Colletta link; long documents come in parts |
recent_changes | lists recently edited documents |
get_comments | reads a document’s comment threads |
list_versions, read_version, compare_versions | lists a document’s versions, reads one, and shows what changed |
An agent that may suggest and comment also gets suggest_edit, add_comment, reply_to_comment and
create_document (as your draft). One that may edit gets edit_document, where an Owner allows it. The edit tool is
marked as a change, so agents that ask before acting ask you first.
Connect a chat app
Section titled “Connect a chat app”Chat apps such as Claude and ChatGPT connect when you sign in, with no token to copy.
- In the app, add a connector with the address
https://app.colletta.app/mcp. - The app opens the sign-in page in your browser. Sign in if you need to.
- On Connect an app, check the app’s name and address. Only continue if you started connecting it yourself.
- Under It also asks to, untick anything you don’t want it to do: Suggest changes, comment and create drafts, or Edit text directly.
- Under Which workspaces can it reach?, choose one workspace, or All my workspaces.
- Choose Allow.
The app then works as you, within what you chose. It’s listed under Connected apps on your API tokens page, where Disconnect stops it at once.
For Owners and Admins: API access in a workspace
Section titled “For Owners and Admins: API access in a workspace”Owners and Admins can see and control which tokens and apps reach their workspace, and what agents may do there. Open Settings at the bottom of the sidebar, then API access.
- API and agent access is a switch for the whole workspace, on by default. Off, no token or connected app can read anything in the workspace. Signing in works as usual.
- Agents may suggest and comment, on by default, lets tokens and apps that were allowed to write suggest changes, comment, reply and create drafts here.
- Agents may edit text directly, off by default, lets those allowed to edit change text here. Each edit is in history as the person via the app. A safety version is saved before the app’s first edit in a session (a new session starts after 30 minutes without its edits), not before every edit.
- Tokens that reach this workspace lists every active token that can read it, with its name and its person.
- A token made for this workspace only can be revoked with Revoke.
- A token made for all of someone’s workspaces can be blocked here with Block here, and allowed again with Unblock. It keeps working in that person’s other workspaces.
The person who owns a token sees on their API tokens page when it’s blocked in a workspace, or when API access is off there. Changes in Settings may ask for two-factor sign-in.