# Endpoint reference

> Every Coline API route, with the scope it needs.

Source: https://docs.coline.app/api/endpoints

Paths are relative to `https://coline.app/api/v1`. Request and response schemas are in the [OpenAPI description](https://coline.app/api/v1/openapi/app-platform), and the developer portal has an [interactive reference](https://coline.app/developers/api-reference).

**OAuth** means the route acts for a person and needs an [OAuth token](/authentication/oauth); workspace API keys get `403 USER_IDENTITY_REQUIRED`. Every other route accepts both. Routes marked † work today but aren't in the OpenAPI description yet.

## Identity

| Method | Path                                    | Does                         | Scope                    |
| ------ | --------------------------------------- | ---------------------------- | ------------------------ |
| `GET`  | `/me/workspaces`                        | List the person's workspaces | `workspace.read` (OAuth) |
| `GET`  | `/workspaces/{workspaceSlug}/members` † | List workspace members       | `workspace.read`         |
| `GET`  | `/oauth/userinfo`                       | The signed-in person         | OAuth token              |

## Calendar

| Method                 | Path                                                                      | Does                                                   | Scope                                      |
| ---------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------ |
| `GET`                  | `/workspaces/{workspaceSlug}/calendar/calendars`                          | List calendars                                         | `calendar.read` (OAuth)                    |
| `POST`                 | `/workspaces/{workspaceSlug}/calendar/calendars`                          | Create a calendar                                      | `calendar.write` (OAuth)                   |
| `PATCH`                | `/workspaces/{workspaceSlug}/calendar/calendars/{calendarId}`             | Update a calendar and your preferences for it          | `calendar.write` (OAuth)                   |
| `DELETE`               | `/workspaces/{workspaceSlug}/calendar/calendars/{calendarId}`             | Archive a calendar                                     | `calendar.write` (OAuth)                   |
| `POST`                 | `/workspaces/{workspaceSlug}/calendar/calendars/{calendarId}/restore`     | Restore an archived calendar                           | `calendar.write` (OAuth)                   |
| `GET`                  | `/workspaces/{workspaceSlug}/calendar/calendars/{calendarId}/changes`     | List changes after a revision number (`afterRevision`) | `calendar.read` (OAuth)                    |
| `GET` `PUT` `DELETE`   | `/workspaces/{workspaceSlug}/calendar/calendars/{calendarId}/grants`      | Read, set or remove who can access a calendar          | `calendar.read` / `calendar.write` (OAuth) |
| `POST`                 | `/workspaces/{workspaceSlug}/calendar/calendars/{calendarId}/import`      | Import an `.ics` file                                  | `calendar.write` (OAuth)                   |
| `GET`                  | `/workspaces/{workspaceSlug}/calendar/calendars/{calendarId}/export`      | Export as `.ics`                                       | `calendar.read` (OAuth)                    |
| `GET`                  | `/workspaces/{workspaceSlug}/calendar/my-schedule`                        | The person's combined schedule                         | `calendar.read` (OAuth)                    |
| `GET`                  | `/workspaces/{workspaceSlug}/calendar/search`                             | Search events                                          | `calendar.read` (OAuth)                    |
| `GET`                  | `/workspaces/{workspaceSlug}/calendar/events`                             | List events between `start` and `end`                  | `calendar.read` (OAuth)                    |
| `POST`                 | `/workspaces/{workspaceSlug}/calendar/events`                             | Create an event                                        | `calendar.write` (OAuth)                   |
| `GET` `PATCH` `DELETE` | `/workspaces/{workspaceSlug}/calendar/events/{eventId}`                   | Read, update or delete an event                        | `calendar.read` / `calendar.write` (OAuth) |
| `GET` `PUT`            | `/workspaces/{workspaceSlug}/calendar/events/{eventId}/reminders`         | Read or replace the person's reminders                 | `calendar.read` / `calendar.write` (OAuth) |
| `PATCH`                | `/workspaces/{workspaceSlug}/calendar/events/{eventId}/response`          | Accept, decline or tentatively accept                  | `calendar.write` (OAuth)                   |
| `GET` `POST` `PATCH`   | `/workspaces/{workspaceSlug}/calendar/events/{eventId}/counter-proposals` | List, propose or answer new times                      | `calendar.read` / `calendar.write` (OAuth) |

Calendar writes that email people outside Coline wait for the person's approval when sent by an API client. See [Calendar](/calendar#invites-from-ai-clients).

## Tasks

| Method                | Path                                                                              | Does                                                     | Scope                                  |
| --------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------- |
| `GET`                 | `/workspaces/{workspaceSlug}/taskboards` †                                        | List taskboards with their statuses                      | `taskboards.read`                      |
| `GET`                 | `/workspaces/{workspaceSlug}/taskboards/{taskboardId}/tasks` †                    | List tasks, with search, status and assignee filters     | `taskboards.read`                      |
| `POST`                | `/workspaces/{workspaceSlug}/taskboards/{taskboardId}/tasks` †                    | Create a task                                            | `taskboards.write`                     |
| `GET`                 | `/workspaces/{workspaceSlug}/taskboards/{taskboardId}/tasks/{taskId}`             | Get a task                                               | `taskboards.read`                      |
| `PATCH`               | `/workspaces/{workspaceSlug}/taskboards/{taskboardId}/tasks/{taskId}`             | Update a task                                            | `taskboards.write`                     |
| `DELETE`              | `/workspaces/{workspaceSlug}/taskboards/{taskboardId}/tasks/{taskId}`             | Delete a task                                            | `taskboards.write`                     |
| `GET` `POST` `DELETE` | `/workspaces/{workspaceSlug}/taskboards/{taskboardId}/tasks/{taskId}/relations` † | Related, blocking and duplicate links between tasks      | `taskboards.read` / `taskboards.write` |
| `POST`                | `/workspaces/{workspaceSlug}/tasks/resolve` †                                     | Resolve a reference like `COL-42` or title text to tasks | `taskboards.read`                      |

## Files and drives

| Method                 | Path                                                   | Does                                  | Scope                        |
| ---------------------- | ------------------------------------------------------ | ------------------------------------- | ---------------------------- |
| `GET`                  | `/workspaces/{workspaceSlug}/drives` †                 | List drives                           | `files.read`                 |
| `GET`                  | `/workspaces/{workspaceSlug}/drives/{driveId}/files` † | List files in a drive or folder       | `files.read`                 |
| `GET` `PATCH` `DELETE` | `/workspaces/{workspaceSlug}/files/{fileId}` †         | Read, rename or move, or trash a file | `files.read` / `files.write` |
| `POST`                 | `/workspaces/{workspaceSlug}/uploads/initiate`         | Start a multipart upload              | `files.write`                |
| `GET`                  | `/workspaces/{workspaceSlug}/uploads/part`             | Get a signed URL for one part         | `files.write`                |
| `POST`                 | `/workspaces/{workspaceSlug}/uploads/part`             | Upload one part through Coline        | `files.write`                |
| `POST`                 | `/workspaces/{workspaceSlug}/uploads/complete`         | Finish the upload and create the file | `files.write`                |

## Docs and notes

| Method                 | Path                                           | Does                           | Scope                        |
| ---------------------- | ---------------------------------------------- | ------------------------------ | ---------------------------- |
| `GET` `POST`           | `/workspaces/{workspaceSlug}/docs` †           | List or create docs            | `files.read` / `files.write` |
| `GET` `PATCH` `DELETE` | `/workspaces/{workspaceSlug}/docs/{docId}` †   | Read, update or delete a doc   | `files.read` / `files.write` |
| `GET` `POST`           | `/workspaces/{workspaceSlug}/notes` †          | List or create notes           | `files.read` / `files.write` |
| `GET` `PUT` `DELETE`   | `/workspaces/{workspaceSlug}/notes/{noteId}` † | Read, replace or delete a note | `files.read` / `files.write` |

## Sheets

| Method       | Path                                                    | Does                                       | Scope                        |
| ------------ | ------------------------------------------------------- | ------------------------------------------ | ---------------------------- |
| `GET`        | `/workspaces/{workspaceSlug}/sheets`                    | List sheets                                | `files.read`                 |
| `POST`       | `/workspaces/{workspaceSlug}/sheets`                    | Create a sheet, optionally from a template | `files.write`                |
| `GET`        | `/workspaces/{workspaceSlug}/sheets/{sheetId}`          | Get a sheet                                | `files.read`                 |
| `PUT`        | `/workspaces/{workspaceSlug}/sheets/{sheetId}`          | Update a sheet                             | `files.write`                |
| `DELETE`     | `/workspaces/{workspaceSlug}/sheets/{sheetId}`          | Delete a sheet                             | `files.write`                |
| `GET` `POST` | `/workspaces/{workspaceSlug}/sheets/{sheetId}/rows` †   | Read or write rows                         | `files.read` / `files.write` |
| `POST`       | `/workspaces/{workspaceSlug}/sheets/{sheetId}/ops` †    | Apply cell and structure operations        | `files.write`                |
| `POST`       | `/workspaces/{workspaceSlug}/sheets/{sheetId}/import`   | Import CSV                                 | `files.write`                |
| `GET`        | `/workspaces/{workspaceSlug}/sheets/{sheetId}/export` † | Export                                     | `files.read`                 |

## Messages

Messages act for a person: you can read and post only in conversations that person is in, exactly as in the app. With an API key, only the public channel list is available.

| Method           | Path                                                                   | Does                                                         | Scope                                       |
| ---------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------- |
| `GET`            | `/workspaces/{workspaceSlug}/channels` †                               | List public channels, plus private channels the person is in | `workspace.read`                            |
| `GET` `POST`     | `/workspaces/{workspaceSlug}/channels/{channelId}/messages` †          | Read or post channel messages                                | `workspace.read` / `messages.write` (OAuth) |
| `GET`            | `/workspaces/{workspaceSlug}/dms` †                                    | List the person's DMs                                        | `workspace.read` (OAuth)                    |
| `GET` `POST`     | `/workspaces/{workspaceSlug}/dms/{dmId}/messages` †                    | Read or post DM messages                                     | `workspace.read` / `messages.write` (OAuth) |
| `GET`            | `/workspaces/{workspaceSlug}/messages/{messageId}` †                   | Get a message                                                | `workspace.read` (OAuth)                    |
| `PATCH` `DELETE` | `/workspaces/{workspaceSlug}/messages/{messageId}` †                   | Edit or delete your own message                              | `messages.write` (OAuth)                    |
| `GET` `POST`     | `/workspaces/{workspaceSlug}/messages/{messageId}/thread` †            | Read a thread, or reply in it                                | `workspace.read` / `messages.write` (OAuth) |
| `PUT` `DELETE`   | `/workspaces/{workspaceSlug}/messages/{messageId}/pin` †               | Pin or unpin a message                                       | `messages.write` (OAuth)                    |
| `PUT` `DELETE`   | `/workspaces/{workspaceSlug}/messages/{messageId}/reactions/{emoji}` † | Add or remove your reaction                                  | `messages.write` (OAuth)                    |

Messages you post appear under the person's name. Posting into a conversation the person isn't in fails with `403`.

## Search

| Method | Path                                   | Does                                                                        | Scope                    |
| ------ | -------------------------------------- | --------------------------------------------------------------------------- | ------------------------ |
| `POST` | `/workspaces/{workspaceSlug}/search` † | Search files, tasks, messages, app documents and mail the person can access | `workspace.read` (OAuth) |

## Apps in a workspace

| Method                 | Path                                                                         | Does                                                 | Scope                        |
| ---------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------- | ---------------------------- |
| `GET`                  | `/workspaces/{workspaceSlug}/apps`                                           | Installed apps and the catalog the workspace can see | `apps.read`                  |
| `POST`                 | `/workspaces/{workspaceSlug}/apps`                                           | Install an app                                       | `apps.write`                 |
| `GET`                  | `/workspaces/{workspaceSlug}/apps/{appKey}`                                  | Get an installed app                                 | `apps.read`                  |
| `DELETE`               | `/workspaces/{workspaceSlug}/apps/{appKey}`                                  | Uninstall an app                                     | `apps.write`                 |
| `GET` `PUT`            | `/workspaces/{workspaceSlug}/apps/{appKey}/permissions`                      | Read or change granted permissions                   | `apps.read` / `apps.write`   |
| `GET` `POST`           | `/workspaces/{workspaceSlug}/apps/{appKey}/secrets`                          | List, create or rotate app secrets                   | `apps.write`                 |
| `DELETE`               | `/workspaces/{workspaceSlug}/apps/{appKey}/secrets/{secretId}`               | Delete a secret                                      | `apps.write`                 |
| `GET` `POST`           | `/workspaces/{workspaceSlug}/apps/{appKey}/oauth-connections`                | List or set the app's OAuth connections              | `apps.write`                 |
| `DELETE`               | `/workspaces/{workspaceSlug}/apps/{appKey}/oauth-connections/{connectionId}` | Remove a connection                                  | `apps.write`                 |
| `GET` `POST`           | `/workspaces/{workspaceSlug}/apps/{appKey}/deliveries`                       | List deliveries, or send a signed test delivery      | `apps.write`                 |
| `POST`                 | `/workspaces/{workspaceSlug}/apps/{appKey}/deliveries/{deliveryId}/replay`   | Replay a delivery                                    | `apps.write`                 |
| `GET` `POST`           | `/workspaces/{workspaceSlug}/apps/{appKey}/files`                            | List or create the app's files                       | `files.read` / `files.write` |
| `GET` `PATCH` `DELETE` | `/workspaces/{workspaceSlug}/apps/{appKey}/files/{fileId}`                   | Read, update or trash an app file                    | `files.read` / `files.write` |
| `POST`                 | `/workspaces/{workspaceSlug}/apps/{appKey}/notifications`                    | Send a notification from the app                     | `notifications.write`        |
| `POST` `DELETE`        | `/workspaces/{workspaceSlug}/apps/{appKey}/index-documents`                  | Add or remove the app's search documents             | `index.write`                |
| `POST`                 | `/workspaces/{workspaceSlug}/apps/{appKey}/ambient/events`                   | Emit the app's events                                | `ambient.events.write`       |

## App Store and publishing

| Method | Path                                         | Does                                             | Scope                          |
| ------ | -------------------------------------------- | ------------------------------------------------ | ------------------------------ |
| `GET`  | `/apps`                                      | List public store apps                           | None                           |
| `GET`  | `/apps/{appKey}`                             | Get a store app                                  | None                           |
| `GET`  | `/apps/{appKey}/versions`                    | List approved versions                           | None                           |
| `POST` | `/apps`                                      | Register a new app and its first release         | Developer session              |
| `POST` | `/apps/{appKey}/versions`                    | Upload a new version (used by `coline-app push`) | `apps.write` or `apps.publish` |
| `POST` | `/apps/{appKey}/versions/{versionId}/submit` | Submit a version for store review                | Developer session              |

## Tab

| Method | Path                    | Does                                | Scope       |
| ------ | ----------------------- | ----------------------------------- | ----------- |
| `GET`  | `/tab/models`           | List Tab models and prices          | None        |
| `POST` | `/tab/chat/completions` | OpenAI-compatible inline completion | `ai.invoke` |

See [Tab](/api/tab).

## Upstream checks

| Method | Path                 | Does                                                       | Scope                   |
| ------ | -------------------- | ---------------------------------------------------------- | ----------------------- |
| `POST` | `/upstream/checks` † | Report a check result from external CI on a Change Request | `upstream.checks.write` |

The rest of Upstream has its own API at `https://api.upstream.codes`. See [Upstream](/upstream#api).

## OAuth

| Method | Path               | Does                                |
| ------ | ------------------ | ----------------------------------- |
| `GET`  | `/oauth/authorize` | Start the authorization code flow   |
| `POST` | `/oauth/token`     | Exchange a code, or refresh a token |

See [OAuth](/authentication/oauth).