# REST API

> Base URL, authentication, request and response format for the Coline API.

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

The Coline API is a JSON API over HTTPS. It covers calendars, sheets, docs, notes, files and uploads, tasks, messages, workspace apps and Tab completions. The OpenAPI 3.1 description is at:

```text
https://coline.app/api/v1/openapi/app-platform
```

The API is in beta (`1.0.0-beta`). Routes in the OpenAPI description are stable. Routes marked † in the [endpoint reference](/api/endpoints) work today but may change before they're added to it.

## Base URL

```text
https://coline.app/api/v1
```

Workspace routes start with `/workspaces/{workspaceSlug}`. You can pass the workspace's slug (the part after `coline.app/` in its URL) or its ID.

## Authentication

Send a bearer token in the `Authorization` header:

```bash
curl https://coline.app/api/v1/workspaces/acme/taskboards \
  -H "Authorization: Bearer col_ws_..."
```

| Credential                                  | Prefix    | Acts as       | Best for                          |
| ------------------------------------------- | --------- | ------------- | --------------------------------- |
| [API key](/authentication/api-keys)         | `col_ws_` | The workspace | Servers, scripts, CI, the app CLI |
| [OAuth access token](/authentication/oauth) | `col_at_` | A person      | Apps that sign people in          |

Both are limited by [scopes](/authentication/scopes).

## Responses

Successful responses wrap the result in `data`:

```json
{ "data": { "sheets": [ ... ] } }
```

Errors use one shape, with a matching HTTP status:

```json
{ "error": { "code": "TASK_NOT_FOUND", "message": "Task not found." } }
```

The code is also sent in the `x-coline-error-code` header. See [errors](/api/errors).

## Requests

* Send JSON bodies with `Content-Type: application/json`.
* Times are ISO 8601. Calendar writes also take an IANA `timeZone`, such as `America/Vancouver`.
* List routes take a `limit` and either an `offset` or a `cursor`. Each route's parameters are in the OpenAPI description.
* Creates are not idempotent. If a create times out, read back before retrying.

## Rate limits

Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. See [rate limits](/api/rate-limits).

## Usage and credits

Most requests are free. Metered calls, such as [Tab](/api/tab) completions and AI calls from apps, draw from the workspace's prepaid API credits, which you can add in the [developer console](https://coline.app/developers/console). Recent requests, with status codes and timings, are under **Request logs**.

## Related

* [Endpoint reference](/api/endpoints)
* [MCP server](/api/mcp) for agents
* [Upstream API](/upstream#api) for repositories, Change Requests and issues