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

# Confluence Integration

> Create and ingest Confluence integration artifacts.

<Warning>
  **Upcoming release — Zylon 1.58**

  These docs are published ahead of release so you can prepare your API integrations. The release image is not yet available. For installations running 1.57, use the [1.57 documentation](/en/v1.57/overview).
</Warning>

Confluence integrations are stored as artifacts. The integration identifier used by these endpoints is the integration artifact ID.

## Prerequisites

Enable Confluence at the instance level first. See [Confluence integration setup](/en/v1.58/operator-manual/knowledge-base/confluence).

For Confluence Cloud, create or reconnect the integration through the login flow documented in [OpenID & OAuth](/en/v1.58/developer-manual/build-with-zylon/workspace-api/authentication/openid). Use the artifact endpoints below after OAuth creates the integration artifact.

## Get a Confluence integration

This endpoint returns public artifact metadata. It never returns access tokens, passwords, or other private properties.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Path | `integrationArtifactID` | Yes | Confluence integration artifact identifier. |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```json theme={null}
  {
    "id": "{integrationArtifactID}",
    "child_count": 0,
    "project_id": "{projectID}",
    "name": "Confluence",
    "type": "Integration",
    "source": "Confluence",
    "state": "Published",
    "ingest_status": "NotApplicable",
    "props": {},
    "keep_file_after_ingestion": true,
    "created_by": {
      "id": "{accountID}",
      "state": "Active",
      "email": "operator@example.com",
      "name": "API operator",
      "provider": "Credentials",
      "roles": [],
      "created_at": "2026-03-01T10:55:00Z",
      "updated_at": "2026-03-01T10:55:00Z"
    },
    "created_at": "2026-03-01T11:00:00Z",
    "updated_at": "2026-03-01T11:00:00Z",
    "scopes": [
      {
        "scope_type": "project",
        "scope_id": "{projectID}",
        "enabled": true,
        "ws_auto_select": false
      }
    ]
  }
  ```
</Accordion>

## Start a Confluence ingest

The endpoint returns a server-sent event (SSE) stream. `space_ids` contains the Confluence spaces to ingest and is used for both Confluence Cloud and ConfluenceLocal.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Path | `integrationArtifactID` | Yes | Confluence integration artifact identifier. |
  | Body | `project_id` | Yes | Destination project identifier. |
  | Body | `space_ids` | Yes | Confluence space identifiers to ingest. |
</Accordion>

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}/ingest" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": "{projectID}",
    "space_ids": ["SUP", "ENG"]
  }'
```

<Accordion title="Example stream">
  ```text theme={null}
  event: SyncEvent
  data: {"type":"sync_started","current_artifact_count":42,"integration_item_count":120}

  event: SyncEvent
  data: {"type":"sync_completed"}
  ```
</Accordion>

## Create a ConfluenceLocal integration

ConfluenceLocal uses basic-auth credentials instead of OAuth. Send credentials only in `private_props`; artifact responses do not return them.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Body | `project_id` | No | Project that owns the integration artifact. Omit it for an organization integration; that requires `AppAdmin` or higher. |
  | Body | `type` | Yes | Must be `Integration`. |
  | Body | `source` | Yes | Must be `ConfluenceLocalLegacy`. |
  | Body | `name` | Yes | Display name for the integration. |
  | Body | `props` | Yes | Public provider properties; use an empty object. |
  | Body | `props.metadata` | No | Optional provider metadata. |
  | Body | `private_props.username` | Yes | ConfluenceLocal username. |
  | Body | `private_props.password` | Yes | ConfluenceLocal password. |
</Accordion>

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "Integration",
    "source": "ConfluenceLocalLegacy",
    "name": "ConfluenceLocal",
    "props": {},
    "private_props": {
      "username": "{confluence_username}",
      "password": "{confluence_password}"
    }
  }'
```

The response is an artifact object with `type: "Integration"` and `source: "ConfluenceLocalLegacy"`, like the public artifact response above.

## Update ConfluenceLocal credentials

Only the integration creator or an administrator can update private properties.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Path | `integrationArtifactID` | Yes | ConfluenceLocal integration artifact identifier. |
  | Body | `private_props.username` | Yes | Replacement username. |
  | Body | `private_props.password` | Yes | Replacement password. |
</Accordion>

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "private_props": {
      "username": "{confluence_username}",
      "password": "{confluence_password}"
    }
  }'
```

## Errors and edge cases

* **400**: invalid provider fields or ingest parameters.
* **403**: integration not enabled, missing permission, or caller cannot update private properties.
* **404**: integration artifact or project not found, or they do not belong together.


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