# Confluence

K-AI ingests pages from Atlassian Confluence Cloud via the Confluence Cloud REST API v2. The connector discovers pages across one space or every visible space, converts each page to Markdown, and syncs incrementally using page modification timestamps.

## Supported source versions

* **Confluence Cloud** — REST API v2 (`/wiki/api/v2/...`).

Confluence Server / Data Center is **not supported**. The connector targets the Cloud v2 endpoints only (`/wiki/api/v2/spaces`, `/wiki/api/v2/spaces/{id}/pages`, `/wiki/api/v2/pages/{id}`).

## Authentication

Authentication uses HTTP **Basic** with an Atlassian account email and an API token. The connector combines them as `email:api_token`, Base64-encodes the pair, and sends it on every request:

```
Authorization: Basic base64(email:api_token)
```

The API token is generated from the Atlassian account security settings (`id.atlassian.com` → Security → API tokens). The account must have **read** access to the spaces you want to ingest. K-AI never requires write or admin permissions.

Credentials are validated at registration with `GET /wiki/api/v2/spaces?limit=1`. A `401`/`403` from Atlassian surfaces as an authentication error; a missing `space_key` surfaces as a not-found error.

## Configuration

| Field       | Type           | Required | Description                                                                                                                            |
| ----------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `kind`      | string         | yes      | Source discriminator. Must be `"CONFLUENCE"`.                                                                                          |
| `base_url`  | string         | yes      | Workspace root, e.g. `https://your-org.atlassian.net`. Do **not** add a `/wiki/api` suffix — the connector appends the v2 path itself. |
| `email`     | string         | yes      | Atlassian account email that owns the API token.                                                                                       |
| `api_token` | string         | yes      | Atlassian API token. Encrypted at rest by the platform.                                                                                |
| `space_key` | string \| null | no       | Space key, e.g. `ENG`, to limit discovery to a single space. Omit or set `null` to enumerate every visible space.                      |

A source's scope path overrides `space_key` when set, letting one source pin to a different space than the credential's default. Sessions are cached per `(base_url, email)` pair, so rotating the API token does not require re-registering the source.

## Document types ingested

* Confluence **pages** — fetched as Atlassian Storage XHTML (`body-format=storage`), normalized, and converted to **Markdown** (`text/markdown`) before indexing. The page title is prepended as a top-level heading so the [indexation pipeline](/knowledge-ai/sources-and-ingestion/indexation-pipeline.md) produces section-aware chunks.

Inline images embedded in a page (`<ac:image>` → `ri:attachment`) are rewritten to their Confluence download URLs (`/wiki/download/attachments/...`). Standalone attachments, comments, and blog posts are **not** ingested as separate documents.

## Sync mode

Discovery is incremental. The connector lists pages with `GET /wiki/api/v2/spaces/{spaceId}/pages` (one space, or every visible space when `space_key` is null) and tracks the most recent page modification timestamp as the delta token. On the next run it passes a CQL predicate — `lastModified > "YYYY-MM-DD HH:MM"` — and also re-applies the same filter client-side, so the contract holds even when the server ignores the predicate.

Confluence Cloud v2 page listings expose **no deletion signal**, so the connector does not emit tombstones. Deletions are reconciled by the platform's orphan scan on full crawls.

## ACL handling

The connector deliberately does **not** extract Confluence space permissions or page restrictions — `restrictions[]` is treated as sensitive and is never emitted. Access in K-AI is therefore **mapped via group rules**, not mirrored from Confluence's native ACL model. Set the source's ACL strategy at registration accordingly.

Page metadata emitted alongside each document: `web_url`, `space_key`, `version_number`, `created_at`, and `created_by_display_name` (when the API returns it). Page lineage (`ancestors[]`), restrictions, raw body, and author email addresses are never emitted.

## Rate limits & throttling

Confluence Cloud enforces per-tenant rate limits. The connector caps concurrency (semaphore of 8 in-flight requests) and honours the `Retry-After` header on `429` responses. `5xx` responses are treated as transient and retried; `401`/`403` and `404` are surfaced as permanent errors.

## Known limitations

* **Cloud only.** Confluence Server / Data Center is not supported.
* **Pages only.** Attachments, comments, and blog posts are not ingested as documents; inline images are referenced by URL, not downloaded into the page body.
* **No native ACLs.** Confluence space permissions and page restrictions are not mirrored; use mapped group rules.
* **No native deletion signal.** Removed pages are reconciled by the orphan scan on full crawls, not in incremental runs.
* **Macros** are rendered from their Storage representation; custom macros are not expanded.

## Setup walkthrough

1. **Generate an API token** at `id.atlassian.com` → Security → API tokens, on an Atlassian account with read access to the target space(s).
2. **Register the source** set `base_url` to your workspace root, `email` and `api_token` to the account credentials, and `space_key` to a single space key (or `null` for all visible spaces).
3. **Trigger a test sync** and confirm the document count via the [Documents endpoint](/knowledge-ai/sources-and-ingestion/instance-api/documents.md) of the K-AI Instance.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://k-ai.gitbook.io/knowledge-ai/sources-and-ingestion/connectors/confluence.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.