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

# Confluence integration

[Back to list of integrations](https://koreai.mintlify.site/agent-platform/integrations/enterprise-systems.md)

Use the Confluence integration to let agents read, search, create, and manage pages, comments, attachments, and labels through Action Tools, and to start workflows when Confluence content changes. Artemis supports Confluence Cloud with OAuth 2.0 and Confluence Data Center 10.2 with OAuth 2.0 client credentials, a bearer token, or basic authentication.

| Authentication | Actions | Workflow triggers |
| - | - | - |
| OAuth 2.0 (Cloud); OAuth 2.0 client credentials, bearer token, or basic auth (Data Center) | [21](#supported-actions) | [5](#supported-triggers) |

## Supported actions

Actions are Confluence operations that an agent runs as Action Tools during a conversation. You can also run them from an [Integration node](https://koreai.mintlify.site/agent-platform/workflows.md#integration-node) in a workflow.

| Action | Use it to |
| - | - |
| [Get Page Content](#get-page-content) | Get a page's content, and optionally its child pages. |
| [Get Page by URL](#get-page-by-url) | Get a page from its Confluence URL. |
| [Find Page by Title](#find-page-by-title) | Find a page by its exact title. |
| [Search Content (CQL)](#search-content-cql) | Search content with Confluence Query Language (CQL). |
| [Create Page](#create-page) | Create a page in a space. |
| [Create Page from Template](#create-page-from-template) | Create a page from a template. |
| [Update Page](#update-page) | Change a page's title, body, or status. |
| [Delete Page](#delete-page) | Move a page to the trash, or delete it permanently. |
| [Move Page](#move-page) | Move a page to a new position in the page tree. |
| [Publish Draft](#publish-draft) | Publish a draft page. |
| [Add Comment to Page](#add-comment-to-page) | Add a footer comment to a page. |
| [Reply to Comment](#reply-to-comment) | Reply to a footer comment. |
| [List Comments](#list-comments) | List the footer or inline comments on a page. |
| [Upload Attachment](#upload-attachment) | Attach a file to a page. |
| [Download Attachment](#download-attachment) | Download an attachment as a file. |
| [List Attachments](#list-attachments) | List the attachments on a page. |
| [Add Label to Page](#add-label-to-page) | Add labels to a page. |
| [Remove Label from Page](#remove-label-from-page) | Remove a label from a page. |
| [Find User](#find-user) | Find users by name, email, or keyword. |
| [List Spaces](#list-spaces) | List the spaces the authenticated user can access. |
| [Custom API Call](#custom-api-call) | Call a Confluence API endpoint that the other actions don't cover. |

## Supported triggers

Triggers start a [workflow](https://koreai.mintlify.site/agent-platform/workflows.md) when an event occurs in Confluence.

| Trigger | Starts a workflow when |
| - | - |
| New Page | A page is created. |
| Updated Page | An existing page is updated (version 2 or later). |
| New Comment on Page | A footer comment is added to the selected page. |
| New Attachment | An attachment is uploaded to the selected page. |
| New Blog Post | A blog post is published in the selected space. |

## Prerequisites

* **Confluence Cloud**: An OAuth 2.0 (3LO) app in the Atlassian Developer Console with the Confluence API scopes listed in the auth profile. See [OAuth 2.0 (3LO) apps](https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/).
* **Confluence Data Center 10.2**: Credentials for one of the supported authentication types, and network access from Artemis to your Confluence server.
* A Confluence user with access to the spaces that agents use.

## Set up the integration

**1. Prepare credentials**

For Confluence Cloud, create an OAuth 2.0 (3LO) app in the Atlassian Developer Console. Add the Confluence API scopes, set the app's callback URL to the **Callback URL** from the Artemis profile form, and copy the **Client ID** and **Client Secret**.

For Confluence Data Center, prepare OAuth 2.0 client credentials, a bearer token, or a username and password.

**2. Create the auth profile**

In **Integrations**, select **Confluence** > **Connect**. On **Project Auth Profiles**, select **New Profile** > **Integration Profile** > **Confluence** > **Continue**. Select the **Version**, and then complete the fields.

> [tab] Cloud
>
> | Field | Value |
> | - | - |
> | **Version** | **Cloud** |
> | **Auth Type** | **OAuth 2.0** |
> | **Profile Name** | A name for the profile, for example `Confluence - Production` |
> | **Usage Mode** | **Preconfigured** (default), **JIT (Just-in-Time)**, or **Preflight**. With **Preconfigured**, an admin provides credentials at setup, and users don't authorize. See [Auth profiles](https://koreai.mintlify.site/agent-platform/administration/integrations-settings.md#auth-profiles). |
> | **Authorization URL**, **Token URL**, **Refresh URL** | Pre-filled with the Atlassian endpoints. Keep the defaults. |
> | **Scopes** | Pre-filled with the scopes the actions require. Add the same scopes to your Atlassian app. |
> | **Callback URL** | Read only. Add it to your Atlassian app's callback URL. |
> | **Client ID**, **Client Secret** | From your Atlassian app. |
>
> Select **Create Profile**, and complete the Atlassian sign-in and consent when prompted.

> [tab] Data Center 10.2
>
> | Field | Value |
> | - | - |
> | **Version** | **Data Center 10.2** |
> | **Auth Type** | **OAuth 2.0 Client Credentials** (default), **Bearer Token**, or **Basic Auth** |
> | **Profile Name** | A name for the profile |
> | **Usage Mode** | **Preconfigured** |
>
> For **OAuth 2.0 Client Credentials**, also complete these fields:
>
> | Field | Value |
> | - | - |
> | **Authorize Using** | **Client Secret** |
> | **Token URL** | Token endpoint of your Confluence server. |
> | **Refresh Token URL** | Optional. |
> | **Scopes** | Optional. Separate scopes with spaces. |
> | **Client ID**, **Client Secret** | From your Confluence server. |
>
> For **Bearer Token** or **Basic Auth**, enter the credentials the form requests. Then select **Create Profile**.

**3. Create the action tool**

In **Tools**, open the **Actions** tab and select **Create Tool**. Enter a **Tool Name** and **Description**, and select **Select Integration** > **Confluence** > **Continue**. Select the **Action** and **Auth Profile**, set parameter defaults (leave a value empty for the agent to supply at runtime), choose an output mode, and select **Create Tool**. Then [assign the tool to an agent](https://koreai.mintlify.site/agent-platform/tools/actions.md#assign-an-action-to-an-agent).

## Action reference

> [accordion] Get Page Content
>
> Gets a page's content, and optionally the content of all its child pages.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `pageId` | string | Page ID. Find it in the page URL. |
> | `includeDescendants` | boolean | Gets all child pages recursively. Default: `False`. |
> | `dynamic` | object | Dynamic properties. |

> [accordion] Get Page by URL
>
> Gets a page from its Confluence URL. Artemis extracts the page ID from the URL.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `url` | string | Page URL, for example `https://your-domain.atlassian.net/wiki/spaces/DOCS/pages/12345/My+Page`. |
> | `bodyFormat` | enum | Format of the returned body. Default: `Storage (XHTML)`. |

> [accordion] Find Page by Title
>
> Finds a page by its exact title, optionally in one space.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `spaceId` | enum | Space to search. |
> | `title` | string | Exact page title. |

> [accordion] Search Content (CQL)
>
> Searches content with a CQL query, for example `type = "page" AND space = "DOCS" AND title ~ "release"`.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `cql` | string | CQL query. See [Advanced searching using CQL](https://developer.atlassian.com/cloud/confluence/advanced-searching-using-cql/). |
> | `maxResults` | number | Maximum number of results. |
> | `expand` | string | Comma-separated properties to expand, for example `body.storage,version,space,history`. |

> [accordion] Create Page
>
> Creates a page in a space.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `spaceId` | enum | Space. |
> | `parentId` | enum | Parent page. |
> | `title` | string | Page title. |
> | `bodyFormat` | enum | Body format. Default: `Storage (XHTML)`. |
> | `body` | string | Page content in the selected format. |
> | `status` | enum | Page status. Default: `Published`. |

> [accordion] Create Page from Template
>
> Creates a page from a template.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `spaceId` | enum | Space. |
> | `templateId` | enum | Template. |
> | `folderId` | enum | Parent folder. |
> | `title` | string | Page title. |
> | `status` | enum | Page status. Default: `Draft`. |
> | `templateVariables` | object | Values for the template variables. |

> [accordion] Update Page
>
> Changes a page's title, body, or status.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `spaceId` | enum | Space. |
> | `pageId` | enum | Page. |
> | `title` | string | New title. Leave empty to keep the current title. |
> | `bodyFormat` | enum | Body format. Default: `Storage (XHTML)`. |
> | `body` | string | New content. Leave empty to keep the current body. |
> | `status` | enum | Page status. |

> [accordion] Delete Page
>
> Moves a page to the trash, or deletes it permanently.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `spaceId` | enum | Space. |
> | `pageId` | enum | Page. |
> | `purge` | boolean | Deletes the page permanently from the trash. If `False`, moves the page to the trash. Default: `False`. |

> [accordion] Move Page
>
> Moves a page to a new parent as a child or sibling, or to the top of the parent.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `spaceId` | enum | Space. |
> | `pageId` | enum | Page to move. |
> | `position` | enum | Position relative to the target page. Default: `Append as last child of target`. |
> | `targetPageId` | string | Target page. Use `append` or `before` to nest the page under the target, or `after` to place it as a sibling. |

> [accordion] Publish Draft
>
> Publishes a draft page by changing its status from draft to current.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `pageId` | string | Draft page ID. |

> [accordion] Add Comment to Page
>
> Adds a footer comment to a page.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `spaceId` | enum | Space. |
> | `pageId` | enum | Page. |
> | `body` | string | Comment in storage (XHTML) format. Plain text also works. |

> [accordion] Reply to Comment
>
> Replies to a footer comment on a page.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `parentCommentId` | string | ID of the comment to reply to. |
> | `body` | string | Reply in storage (XHTML) format. |

> [accordion] List Comments
>
> Lists the footer or inline comments on a page.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `spaceId` | enum | Space. |
> | `pageId` | enum | Page. |
> | `commentType` | enum | Comment type. Default: `Footer comments`. |
> | `bodyFormat` | enum | Body format. Default: `Storage (XHTML)`. |

> [accordion] Upload Attachment
>
> Attaches a file to a page.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `spaceId` | enum | Space. |
> | `pageId` | enum | Page. |
> | `file` | string | File to upload. |
> | `comment` | string | Optional. Comment for this attachment version. |
> | `minorEdit` | boolean | Doesn't notify page watchers. Default: `True`. |

> [accordion] Download Attachment
>
> Downloads an attachment and returns it as a file.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `attachmentId` | string | Attachment ID. To find it, use [List Attachments](#list-attachments). |

> [accordion] List Attachments
>
> Lists the attachments on a page.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `spaceId` | enum | Space. |
> | `pageId` | enum | Page. |

> [accordion] Add Label to Page
>
> Adds one or more labels to a page.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `spaceId` | enum | Space. |
> | `pageId` | enum | Page. |
> | `labels` | array | Label names, one per row. |
> | `prefix` | enum | Label prefix. Default: `Global`. |

> [accordion] Remove Label from Page
>
> Removes a label from a page.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `spaceId` | enum | Space. |
> | `pageId` | enum | Page. |
> | `label` | string | Label name. |

> [accordion] Find User
>
> Finds users by name, email, or keyword.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `keyword` | string | Username, email, or display name. |
> | `limit` | number | Maximum number of results. |

> [accordion] List Spaces
>
> Lists the spaces the authenticated user can access.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `type` | enum | Space type. |
> | `status` | enum | Space status. Default: `Current`. |

> [accordion] Custom API Call
>
> Sends a request to a Confluence API endpoint. Artemis adds the authorization headers from the auth profile.
>
> | Parameter | Type | Description |
> | - | - | - |
> | `url` | object | Endpoint URL. |
> | `method` | enum | HTTP method. |
> | `headers` | object | Request headers. Authorization headers are added automatically. |
> | `queryParams` | object | Query parameters. |
> | `body_type` | enum | Body type. Default: `None`. |
> | `body` | object | Request body. |
> | `response_is_binary` | boolean | Returns the response as a file. Use for PDFs, images, and other files. Default: `False`. |
> | `failsafe` | boolean | Returns a result instead of an error when the request fails. |
> | `timeout` | number | Timeout, in seconds. |
> | `followRedirects` | boolean | Follows HTTP redirects. Default: `False`. |

## Troubleshoot common issues

| Issue | Resolution |
| - | - |
| Authorization fails with a redirect error | Confirm the Atlassian app's callback URL matches the **Callback URL** from the profile form. |
| The profile status stays **Awaiting authorization** | Complete the Atlassian sign-in and consent in the same browser session. |
| `401` or `403` after authorization | Add every scope in the auth profile to the Atlassian app, and reauthorize the profile. |
| The space or page list is empty | Confirm the authorizing user can view the space. |
| A CQL search returns an error | Check the query syntax. Enclose values that contain spaces in quotation marks. |
| Page content contains unexpected markup | Set `bodyFormat` to the format your content uses. The default is `Storage (XHTML)`. |
| Data Center requests fail to connect | Confirm Artemis can reach your Confluence server and that the **Token URL** is correct. |

**Related articles:**

* [Auth profiles](https://koreai.mintlify.site/agent-platform/administration/integrations-settings.md#auth-profiles)
* [Action Tools](https://koreai.mintlify.site/agent-platform/tools/actions.md)
* [Workflows](https://koreai.mintlify.site/agent-platform/workflows.md)
* [Confluence Cloud REST API](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.