REST API

Everything PageCycle's tools do is also an HTTPS route: check, move and find pages, read History and change a space's workflow from your own scripts. Each call acts as the person who signed in, with exactly their Confluence permissions. PageCycle runs on Atlassian's platform and answers only the integrations people on your site authorize.

Turn it onCopy Anchor Link

A site or org admin switches the API on once per site. It is off until then, and switching it off again stops every call at once.

1. Open Atlassian Administration, pick your site and open Connected apps.
2. Find PageCycle and select View app details.
3. On the Details tab, under App REST APIs, select Enable app REST APIs, then Enable.

The section then reads Enabled. Reinstalling PageCycle turns it off again.

Create an OAuth 2.0 integrationCopy Anchor Link

Calls are signed in as a person with an OAuth 2.0 (3LO) integration you create in the Atlassian developer console. It acts only for a person on your site who signs in and accepts it, and only with their permissions.

1. Open the developer console, select Create, then OAuth 2.0 integration. Name it, choose Resource-level and create it.
2. Open Permissions and select Add Marketplace or custom app. Pick your site, then PageCycle, then the scopes your script needs (below).
3. Still in Permissions, open Confluence API, select Configure, then Granular scopes, and add read:forge-app:confluence. Every call needs it.
4. Open Authorization and add your callback URL.
5. Open Settings for the Client ID and Secret. Keep the secret out of your code and your logs.

Get a tokenCopy Anchor Link

Send the person to the authorization URL. They sign in, pick your site and accept:

https://auth.atlassian.com/authorize
  ?audience=api.atlassian.com
  &client_id=YOUR_CLIENT_ID
  &scope=read%3Apagecycle%3Acustom%20write%3Apagecycle-page%3Acustom%20read%3Aforge-app%3Aconfluence%20offline_access
  &redirect_uri=YOUR_CALLBACK_URL
  &state=A_VALUE_YOU_CHECK
  &response_type=code
  &prompt=consent
  &sns=db702242-b6fc-4a44-bcea-e6ad97e8db84.7b249cc1-1e34-4a73-850f-d51fafab4b8c

Keep sns as written. It names PageCycle; without it, Atlassian leaves PageCycle's scopes out of the token and every call answers 403 Missing required scopes. With it, the consent screen lists what the script may do in PageCycle.

Exchange the code your callback receives for a token:

curl -s -X POST https://auth.atlassian.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"authorization_code","client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_SECRET","code":"THE_CODE","redirect_uri":"YOUR_CALLBACK_URL"}'

The answer's access_token lasts an hour; offline_access adds a refresh_token to get a new one. Your site's cloud id is at https://YOUR_SITE.atlassian.net/_edge/tenant_info.

BasicsCopy Anchor Link

Every route lives under one base URL:

https://api.atlassian.com/svc/confluence/YOUR_CLOUD_ID/apps/db702242-b6fc-4a44-bcea-e6ad97e8db84_7b249cc1-1e34-4a73-850f-d51fafab4b8c

Send the token as Authorization: Bearer YOUR_TOKEN and Accept: application/json; send JSON bodies with Content-Type: application/json, up to 16,000 bytes. Every answer from PageCycle has the same four fields (Atlassian's own refusals, below, are plain):

A page's next review is reviewBy in every answer; you send it as reviewDate with a move and as date to PUT /pages/{page}/reviewDate. Lists check the person's view of every page, so a large space takes a few seconds a call: page through it with after, and don't poll in a tight loop.

ExamplesCopy Anchor Link

Check a pageCopy Anchor Link

curl -s "$BASE/pages/8013/status" -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json'

Move a pageCopy Anchor Link

curl -s -X POST "$BASE/pages/8013/moves" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'Accept: application/json' \
  -d '{"to":"In review","comment":"Added the over-limit case"}'

Change a space's workflowCopy Anchor Link

Ask for the change; the answer is a preview:

curl -s -X POST "$BASE/spaces/WS/statuses" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'Accept: application/json' \
  -d '{"name":"On hold","after":"Draft"}'

Show the person data.preview. When they agree, confirm it with data.confirmation:

curl -s -X POST "$BASE/confirmations/op_8f2c1d0e9a7b6c5d" -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json'

A change that touches many pages (removing or renaming a status, turning PageCycle on) answers 202 with data.operation. Call POST /operations/{id} until it answers 200; GET /operations/{id} only reads where it stands.

RoutesCopy Anchor Link

Every route's fields and a real answer are in the API reference. To generate a client, download the OpenAPI file.

{page} is a page id. {space} is a space key. A status, move or automation in a path is its name or its id; a name with / or % in it must be named by its id, because Atlassian refuses those characters in a path.

ReadCopy Anchor Link

Scope read:pagecycle:custom. Anyone who can view the page or space.

Move pagesCopy Anchor Link

Scope write:pagecycle-page:custom. People who can edit the page, within the move's groups.

Space adminCopy Anchor Link

Scope manage:pagecycle-space:custom. Space admins. Each answers a preview.

Confirmations and long changesCopy Anchor Link

Scope manage:pagecycle-space:custom.

Pages a person can't view never appear in a list, a count or a History line. Lists answer at most 50 rows: only the page list takes after (pass the previous answer's data.next); the others say data.truncated and narrow by their filters.

Status codesCopy Anchor Link

Refusals from AtlassianCopy Anchor Link

Some calls never reach PageCycle. Atlassian's gateway answers them itself, in plain text or its own JSON, without the four fields:

ScopesCopy Anchor Link