> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cymph.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Confluence

> Fetch pages and spaces from Atlassian Confluence.

## What Cymph uses it for

Cymph connects to Confluence for two purposes:

1. **Importing content** — reads pages and spaces, so existing documentation can be brought into Cymph. *(read)*
2. **Publishing documentation** — creates a new Confluence page from a playbook's documentation. *(write)* See [Deploy playbooks](/how-tos/deploy-playbooks).

A single token can serve either or both purposes. **If you only import, Cymph needs read scopes; publishing requires an additional write scope** — see [Permissions](#permissions) below.

<Note>
  Confluence and [JIRA](/integrations/ticketing/jira) are separate integration types but share the same Atlassian API token mechanism. The token must be created for the right app and carry the scopes listed below.
</Note>

## Requirements

| Field              | Description                                                         |
| ------------------ | ------------------------------------------------------------------- |
| **Instance URL**   | The URL of your instance, e.g. `https://mydomain.atlassian.net`     |
| **E-mail address** | The e-mail address of the Atlassian user, e.g. `myuser@example.com` |
| **API token**      | An API token for the account (see below)                            |

## Token setup

Follow the instructions provided [here](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) to generate a token.

## Permissions

### To import content

```
read:page:confluence
read:space:confluence
```

Or, if you are using classic scopes:

```
read:confluence-content.all
read:confluence-space.summary
```

### To also publish documentation

Add the following scope:

```
write:page:confluence
```

Or, with classic scopes:

```
write:confluence-content
```

An Atlassian API token inherits the permissions of the user it belongs to, so the account must have access to the spaces you want Cymph to read — and, for publishing, permission to add pages to the target space.

<Tip>
  Use a dedicated Atlassian service account rather than a personal one — pages created by Cymph will be attributed to whichever account owns the token.
</Tip>

## What Cymph reads and writes

Cymph reads spaces and page content, and creates pages when you publish documentation.

| Purpose                                   | Confluence API call       |
| ----------------------------------------- | ------------------------- |
| Create a page from playbook documentation | `POST /wiki/api/v2/pages` |

Pages are created with status `current` (published, not draft) in the space you select, using Confluence's **storage format** — Cymph converts the playbook's documentation blocks to Markdown and then to storage HTML. Cymph returns the new page's URL, which becomes the "navigate to the pushed playbook" link in Deploy History.

<Note>
  Cymph never updates or deletes existing pages — each publish creates a new page. Publishing the same playbook twice produces two pages, and Confluence rejects the second if the title collides within the space.
</Note>

## Publishing formats

Confluence accepts **Markdown documentation only**. PDF publishing is not supported — Confluence pages have no native PDF type, and Cymph will reject the attempt with "PDF push is not supported for Confluence". Image blocks are omitted.

## Testing the connection