What we need

[] Confluence Subdomain (e.g., your-company.atlassian.net) [] API Token [] Username / email

Confluence rest API V2 Integration Guide

This guide explains how to set up programmatic access to Confluence Cloud to retrieve:

1. Confluence users
2. Confluence pages
3. User activity on Confluence pages

Prerequisites

Before you begin, ensure you have:

• Administrator access to your Confluence Cloud instance
• An Atlassian account with appropriate permissions
• Your Confluence instance URL (e.g., your-company.atlassian.net)

Step 1: Generate an Atlassian API Token

1. Log in to your Atlassian account

   • Visit the Atlassian account management page.
   • Sign in with your Atlassian account credentials.

2. Create an API token

   • Click on Create API token.
   • Enter a meaningful label for your token (e.g., “Parable Confluence Integration”).
   • Pick an expiration data that won’t drive you nuts.
   • Click Create.

3. Copy and secure your token

   • Once generated, copy the token value.
   • Store it securely. This token cannot be viewed again after you close the dialog.

Step 2: Set Up Authentication

Confluence API v2 uses Basic Authentication with your email and API token:

import base64
import requests

def get_confluence_auth_header(email, api_token):
    credentials = f"{email}:{api_token}"
    encoded_credentials = base64.b64encode(credentials.encode('utf-8')).decode('utf-8')
    return {"Authorization": f"Basic {encoded_credentials}"}

# Example usage
headers = get_confluence_auth_header("your-email@example.com", "your-api-token")

For Accessing Users

• Space Administrator or Confluence Administrator role
• Alternatively, Can use global permission with User Management access

For Accessing Pages

• Space permissions: View permission for all spaces you want to access
• For private spaces, explicit access must be granted to the user

For Accessing User Activity

• Confluence Administrator role is required to access comprehensive user activity data
• For content-specific activity, Space Administrator permission for the relevant spaces is sufficient

Step 4: API Endpoints Reference

1. Retrieving Confluence Users

GET /wiki/api/v2/users

Parameters:

• start (int): Starting index for pagination (0-based)
• limit (int): Maximum number of users to return (default: 25, max: 100)
• accountId (string, optional): Filter by account ID

Example request:

response = requests.get(
    f"https://your-company.atlassian.net/wiki/api/v2/users",
    headers=headers,
    auth=auth
    params={"limit": 100}
)
users = response.json()

2. Retrieving Confluence Pages

GET /wiki/api/v2/pages

Parameters:

• start (int): Starting index for pagination (0-based)
• limit (int): Maximum number of items to return (default: 25, max: 100)
• spaceKey (string, optional): Key of the space to filter by
• expand (string, optional): Properties to expand (e.g., “body,version,space,history”)

Example request:

response = requests.get(
    f"https://your-company.atlassian.net/wiki/api/v2/pages",
    headers=headers,
    auth=auth
    params={
        "limit": 100,
        "spaceKey": "ENG",
        "expand": "body.storage,version,space,history"
    }
)
pages = response.json()

Item Checklist for Integration

1. Your Atlassian account email address
2. Confluence API token
3. Confluence instance URL (e.g., your-company.atlassian.net)
4. Appropriate permissions for the user generating the token
5. List of space keys you want to access (optional, for targeted data collection)

Common Issues

1. 401 Unauthorized: Check your email and API token are correct
2. 403 Forbidden: The authenticated user lacks necessary permissions
3. 429 Too Many Requests: You’ve hit the rate limit; implement backoff and retry logic

Permission Errors

If you encounter permission errors:

1. Verify the user has appropriate space permissions
2. For user data access, ensure the user has admin privileges
3. For activity data, confirm the user has Confluence Administrator role

API Changes

Atlassian occasionally updates their API. Refer to the official Confluence REST API documentation for the most current information.