> For the complete documentation index, see [llms.txt](https://sandgarden.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sandgarden.gitbook.io/docs/reference/connections-api.md).

# Connections API

Manage Sources and providers over the REST API.

This page covers direct integration with Doc Holiday's API.

Use this reference when an integration needs the public Connections endpoints. See [Connection Types](/docs/reference/connection-types.md) for the full type list.

All endpoints on this page require authenticated access; see [API overview](/docs/reference/api-overview.md) for how to create and send an API key.

### Common shapes

* `config` is a one-of object. `POST /api/v1/connections` and `PUT /api/v1/connections/{id}` return `400` when `config` is missing or when more than one variant is set.
* Connection responses include `id`, `orgId`, `name`, `type`, `allowedTriggerEvents`, `healthy`, `paused`, redacted `config`, `createdAt`, `updatedAt`, and `deletedAt`.
* List responses return `connections`, `channels`, `repos`, or `statuses`, and include `nextPageToken` and `previousPageToken` when present.

#### Config examples

**`githubRepo`**

```json
{
  "githubRepo": {
    "githubAppConnectionId": "cnn-0123456789abcdef",
    "repositoryUrl": "https://github.com/example/docs"
  }
}
```

**`notion`**

```json
{
  "notion": {
    "integrationKey": "********"
  }
}
```

**`slackChannel`**

```json
{
  "slackChannel": {
    "slackAppConnectionId": "cnn-0123456789abcdef",
    "channelId": "C01234567"
  }
}
```

### Endpoint reference

#### `POST /api/v1/connections`

Creates a connection that Doc Holiday can use to read from or write to an external system.

* Key parameters: `name`, `config`, `paused`, `sync`
* curl:

```bash
curl -X POST "https://api.doc.holiday/api/v1/connections" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Docs repo","paused":false,"sync":true,"config":{"githubRepo":{"githubAppConnectionId":"cnn-0123456789abcdef","repositoryUrl":"https://github.com/acme/docs"}}}'
```

* JSON:

```json
{"id":"cnn-0123456789abcdef","name":"Docs repo","type":"githubRepo","healthy":true,"paused":false,"allowedTriggerEvents":["pullRequests","newIssues","issueComments","releases"],"config":{"githubRepo":{"githubAppConnectionId":"cnn-0123456789abcdef","repositoryUrl":"https://github.com/acme/docs"}}}
```

* Behaviors: Returns `400` when `config` is missing or more than one connection type is set.

#### `GET /api/v1/connections`

Lists connections and supports filtering by name, type, pause state, sync time, rate limit, and health.

* Key parameters: `name`, `type`, `paused`, `syncedAtBefore`, `remainingRateLimitPercent`, `healthy`
* Returns: `connections`, plus `nextPageToken` and `previousPageToken` when present
* curl:

```bash
curl "https://api.doc.holiday/api/v1/connections?type=githubRepo&healthy=true" \
  -H "Authorization: Bearer <token>"
```

* JSON:

```json
{"connections":[{"id":"cnn-0123456789abcdef","name":"Docs repo","type":"githubRepo","healthy":true,"paused":false,"allowedTriggerEvents":["pullRequests","newIssues","issueComments","releases"],"config":{"githubRepo":{"githubAppConnectionId":"cnn-0123456789abcdef","repositoryUrl":"https://github.com/acme/docs"}}}],"nextPageToken":"eyJ..."}
```

* Behaviors: Returns `400` for invalid filters.

#### `GET /api/v1/connections/{id}`

Returns one connection record with the redacted configuration and trigger events it can emit.

* Key parameters: `id`
* Returns: one connection record
* curl:

```bash
curl "https://api.doc.holiday/api/v1/connections/cnn-0123456789abcdef" \
  -H "Authorization: Bearer <token>"
```

* JSON:

```json
{"id":"cnn-0123456789abcdef","name":"Docs repo","type":"githubRepo","healthy":true,"paused":false,"allowedTriggerEvents":["pullRequests","newIssues","issueComments","releases"],"config":{"githubRepo":{"githubAppConnectionId":"cnn-0123456789abcdef","repositoryUrl":"https://github.com/acme/docs"}}}
```

* Behaviors: Returns `400` for an invalid or missing `id`.

#### `PUT /api/v1/connections/{id}`

Updates the connection name, pause state, and exactly one connection config variant.

* Key parameters: `id`, `name`, `paused`, `config`
* curl:

```bash
curl -X PUT "https://api.doc.holiday/api/v1/connections/cnn-0123456789abcdef" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Docs source","paused":true,"config":{"notion":{"integrationKey":"********"}}}'
```

* JSON:

```json
{"id":"cnn-0123456789abcdef","name":"Docs source","type":"notion","healthy":true,"paused":true,"allowedTriggerEvents":[],"config":{"notion":{"integrationKey":"********"}}}
```

* Behaviors: Returns `400` when `config` is missing, ambiguous, or fails validation.

#### `DELETE /api/v1/connections/{id}`

Removes a connection and can keep dependent records when needed.

* Key parameters: `id`, `preserveDependencies`
* Returns: no content
* curl:

```bash
curl -X DELETE "https://api.doc.holiday/api/v1/connections/cnn-0123456789abcdef?preserveDependencies=true" \
  -H "Authorization: Bearer <token>"
```

* Behaviors: Returns `204 No Content` with no response body.

#### `POST /api/v1/connections/{id}/sync`

Starts a background sync for the selected connection.

* Key parameters: `id`, `wait`
* curl:

```bash
curl -X POST "https://api.doc.holiday/api/v1/connections/cnn-0123456789abcdef/sync" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"wait":true}'
```

* Behaviors: Returns `202 Accepted` with no response body; invalid `wait` values return `400`.

#### `GET /api/v1/connections/{id}/health`

Checks whether a connection is healthy and returns any message or error when present.

* Key parameters: `id`
* Returns: `id`, `status`, and optional `message`, `error`
* curl:

```bash
curl "https://api.doc.holiday/api/v1/connections/cnn-0123456789abcdef/health" \
  -H "Authorization: Bearer <token>"
```

* JSON:

```json
{"id":"cnn-0123456789abcdef","status":"healthy"}
```

* Behaviors: Returns `400` for an invalid or missing `id`.

#### `GET /api/v1/connections/{id}/channels`

Lists the channels that the selected connection can reach.

* Key parameters: `id`
* Returns: `channels`
* curl:

```bash
curl "https://api.doc.holiday/api/v1/connections/cnn-0123456789abcdef/channels" \
  -H "Authorization: Bearer <token>"
```

* JSON:

```json
{"channels":[{"id":"C01234567","name":"docs"}]}
```

* Behaviors: Returns `400` for an invalid or unsupported connection.

#### `GET /api/v1/bitbucket/repos`

Lists Bitbucket repositories using either a connection ID or workspace credentials.

* Key parameters: `connectionId`, `workspace`, `token`
* Returns: `repos`
* curl:

```bash
curl "https://api.doc.holiday/api/v1/bitbucket/repos?connectionId=cnn-0123456789abcdef" \
  -H "Authorization: Bearer <token>"
```

* JSON:

```json
{"repos":[{"fullName":"acme/docs","slug":"docs"}]}
```

* Behaviors: Use `connectionId` alone, or provide `workspace` and `token` together. Returns `400` for invalid parameters.

#### `GET /api/v1/connections/{id}/jira/statuses`

Lists the Jira statuses that a connection can use.

* Key parameters: `id`
* Returns: `statuses`
* curl:

```bash
curl "https://api.doc.holiday/api/v1/connections/cnn-0123456789abcdef/jira/statuses" \
  -H "Authorization: Bearer <token>"
```

* JSON:

```json
{"statuses":[{"id":"100","name":"To Do"},{"id":"101","name":"Done"}]}
```

* Behaviors: Returns `400` for an invalid or missing `id`.

#### `POST /api/v1/connections/{id}/merges/summarize`

Starts a background summary for one merged pull request on a connection.

* Key parameters: `id`, `number`
* curl:

```bash
curl -X POST "https://api.doc.holiday/api/v1/connections/cnn-0123456789abcdef/merges/summarize" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"number":123}'
```

* Behaviors: Returns `202 Accepted` with no response body; missing or invalid `number` values return `400`.