Getting Started with the REST API

Setting up API access requires three one-time steps: enabling the feature on your Atlassian site, creating an OAuth 2.0 integration and connecting it to the app, then completing the authorization flow to obtain an access token.

Note: App REST APIs on Forge are disabled by default and must be explicitly enabled by a site or org admin. See the official Atlassian documentation for a full walkthrough.

Step 1 — Enable App REST APIs (site admin)

This step must be completed by a site or org admin and only needs to be done once per Confluence site.

  1. Go to the Manage apps section in your Atlassian admin panel and find Markdown Exporter for Confluence
  2. Click View app details
  3. Open the Details tab and locate the App REST APIs section
  4. Toggle it on to enable

Once enabled, the base URL for the API is displayed under this toggle.

Step 2 — Create an OAuth 2.0 Integration

Only site members can create OAuth 2.0 integrations that connect to that site's Forge app APIs.

Create the integration

  1. Go to developer.atlassian.com/console
  2. Click Create → OAuth 2.0 integration and give it a name (e.g. Markdown Exporter API)

Connect it to Markdown Exporter

  1. Open the Permissions section of your new integration
  2. Click Add Marketplace or custom app
  3. Select the site where Markdown Exporter is installed
  4. Select Markdown Exporter for Confluence and the environment from the list
  5. Add the scope: export:markdown:custom
  6. Click Add
  7. Still under Permissions, also add the Confluence product scope: read:forge-app:confluence

Both scopes must be present before you authorize. Use only the minimum scopes required.

Configure the callback URL

  1. Go to the Authorization section
  2. Add your callback URL. For quick testing, https://httpbin.org/anything works — the auth code will appear in the redirect response JSON.

Step 3 — Authorize and Obtain Tokens

Get the authorization URL

  1. In the Authorization section of your integration, locate the authorization URL generated for the Markdown Exporter entry
  2. Copy that URL and open it in a browser
  3. On the consent screen, select the site and click Accept
  4. You will be redirected to your callback URL — copy the code query parameter from the URL

If you need offline_access (refresh token for automated pipelines), append %20offline_access to the scope parameter in the authorization URL before opening it.

Exchange the code for tokens

curl --request POST \
  --url 'https://auth.atlassian.com/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "CODE_FROM_REDIRECT",
    "redirect_uri": "YOUR_CALLBACK_URL"
  }'

Your Client ID and Client Secret are available in the Settings tab of your OAuth integration.

Response:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Store both tokens. The access_token is valid for 1 hour. Use the refresh_token to obtain new access tokens without user interaction — see Authentication for rotation details.

Step 4 — Find Your Cloud ID

Your Cloud ID is required to construct the API URL:

GET https://your-site.atlassian.net/_edge/tenant_info

It is also displayed in the REST API tab inside the app settings: Confluence Admin → Apps → Markdown Exporter → REST API.

Step 5 — Make Your First Request

Two URL formats are supported:

https://api.atlassian.com/svc/confluence/{cloudId}/apps/{appId}_{envId}/{path}
https://{site-name}/gateway/api/svc/confluence/apps/{appId}_{envId}/{path}

App IDs

Field Value
App ID 0def1d4f-1593-4dd0-99a3-a098b3959067
Production env ID 796457c9-9c03-4382-b44f-d19571068ece
Staging env ID 73c9d7be-47c5-479a-b08d-14fb79453df8
Dev env ID 08a10a13-932b-47bb-b760-0cc1e93d4a50

Export a single page

curl --request POST \
  --url "https://api.atlassian.com/svc/confluence/{cloudId}/apps/0def1d4f-1593-4dd0-99a3-a098b3959067_796457c9-9c03-4382-b44f-d19571068ece/singleExport" \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"pageId": "123456"}' \
  > my-page.md

A successful response returns the page's Markdown content as plain text.

Next Steps