# Confluence

Confluence is Atlassian's team workspace and knowledge management platform where teams create, organize, and collaborate on documents, meeting notes, project plans, and more. The Sling Confluence connector extracts data from the Confluence Cloud REST API v2, supporting spaces, pages, blog posts, comments, attachments, labels, tasks, versions, and more.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials and inputs are accepted:

**Secrets:**

* `email` **(required)** -> Your Atlassian account email address
* `api_token` **(required)** -> Your Atlassian API token
* `domain` **(required)** -> Your Confluence Cloud domain (e.g., `your-company.atlassian.net`)

**Inputs:**

* `anchor_date` (optional) -> The starting date for historical data extraction (default: 1 year ago). Format: `YYYY-MM-DD`

### Getting Your API Token

1. Log in to your Atlassian account at [id.atlassian.com](https://id.atlassian.com)
2. Go to **Security** > [**API tokens**](https://id.atlassian.com/manage-profile/security/api-tokens)
3. Click **Create API token**
4. Give your token a descriptive label (e.g., "Sling Integration")
5. Set an expiration date (up to 1 year)
6. Click **Create** and copy the token

Your domain is the subdomain of your Confluence Cloud instance (e.g., if your URL is `https://acme.atlassian.net/wiki`, the domain is `acme.atlassian.net`).

### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set CONFLUENCE type=api spec=confluence \
  secrets='{ email: user@company.com, api_token: ATATT3xFfGF0..., domain: your-company.atlassian.net }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export CONFLUENCE='{ type: api, spec: confluence, secrets: { email: "user@company.com", api_token: "ATATT3xFfGF0...", domain: "your-company.atlassian.net" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  CONFLUENCE:
    type: api
    spec: confluence
    secrets:
      email: "user@company.com"
      api_token: "ATATT3xFfGF0..."
      domain: "your-company.atlassian.net"
```

## Replication

Here's an example replication configuration to sync Confluence data to a PostgreSQL database:

```yaml
source: CONFLUENCE
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: confluence.{stream_name}

streams:
  # sync all endpoints
  '*':
```

**Selective sync with specific endpoints:**

```yaml
source: CONFLUENCE
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: confluence.{stream_name}

streams:
  # Core entities
  spaces:
  pages:
  blog_posts:
  attachments:
  tasks:
  groups:

  # Page details (depend on pages queue)
  page_labels:
  page_versions:
  page_footer_comments:
  page_inline_comments:
  page_content_properties:
  child_pages:

  # Blog post details (depend on blog_posts queue)
  blog_post_labels:
  blog_post_versions:

  # Space details (depend on spaces queue)
  space_labels:
  space_permissions:
```

## Endpoints

| Endpoint                        | Description                              | Incremental |
| ------------------------------- | ---------------------------------------- | ----------- |
| `spaces`                        | All Confluence spaces (global, personal) | No          |
| `pages`                         | All pages across all spaces              | No          |
| `blog_posts`                    | All blog posts across all spaces         | No          |
| `attachments`                   | All file attachments                     | No          |
| `tasks`                         | All tasks from pages and blog posts      | No          |
| `groups`                        | All user groups                          | No          |
| `custom_content`                | All custom content types                 | No          |
| `page_footer_comments`          | Footer comments on each page             | No          |
| `page_inline_comments`          | Inline comments on each page             | No          |
| `page_labels`                   | Labels assigned to each page             | No          |
| `page_versions`                 | Version history for each page            | No          |
| `page_content_properties`       | Content properties for each page         | No          |
| `child_pages`                   | Child pages for each page                | No          |
| `blog_post_footer_comments`     | Footer comments on each blog post        | No          |
| `blog_post_inline_comments`     | Inline comments on each blog post        | No          |
| `blog_post_labels`              | Labels assigned to each blog post        | No          |
| `blog_post_versions`            | Version history for each blog post       | No          |
| `blog_post_content_properties`  | Content properties for each blog post    | No          |
| `attachment_labels`             | Labels assigned to each attachment       | No          |
| `attachment_versions`           | Version history for each attachment      | No          |
| `attachment_content_properties` | Content properties for each attachment   | No          |
| `space_labels`                  | Labels assigned to each space            | No          |
| `space_permissions`             | Permissions for each space               | No          |
| `space_properties`              | Properties for each space                | No          |

To discover available endpoints:

```bash
sling conns discover CONFLUENCE
```

## How It Works

### Queues and Dependencies

The Confluence connector uses a queue-based system for parent-child relationships:

* **`spaces`** populates the `space_ids` queue, which feeds into `space_labels`, `space_permissions`, and `space_properties`
* **`pages`** populates the `page_ids` queue, which feeds into `page_footer_comments`, `page_inline_comments`, `page_labels`, `page_versions`, `page_content_properties`, and `child_pages`
* **`blog_posts`** populates the `blog_post_ids` queue, which feeds into `blog_post_footer_comments`, `blog_post_inline_comments`, `blog_post_labels`, `blog_post_versions`, and `blog_post_content_properties`
* **`attachments`** populates the `attachment_ids` queue, which feeds into `attachment_labels`, `attachment_versions`, and `attachment_content_properties`

This means child endpoints automatically iterate over the parent data, so you get comments, labels, and versions for all synced content without additional configuration.

### API Versions

The connector primarily uses the Confluence Cloud REST API v2 with cursor-based pagination for optimal performance. The `groups` endpoint uses the v1 API with offset-based pagination as group listing is not available in v2.

## Rate Limiting

The Confluence Cloud API uses a points-based rate limiting model:

* Core objects (pages, spaces, attachments): 1 point per request
* Identity/access (users, groups, permissions): 2 points per request
* Quotas reset hourly at the top of each UTC hour

The connector automatically:

* Limits to 5 requests per second
* Uses up to 5 concurrent requests for child endpoints
* Retries with exponential backoff on 429 (rate limit) responses
* Retries with linear backoff on 500+ server errors

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).