{ "openapi": "3.1.0", "info": { "title": "PageCycle REST API", "version": "1.0.0", "description": "Every PageCycle tool as an HTTPS route, acting as the person who signed in, with their Confluence permissions. A site or org admin turns App REST APIs on for PageCycle in Connected apps first. The authorization URL needs sns=db702242-b6fc-4a44-bcea-e6ad97e8db84.7b249cc1-1e34-4a73-850f-d51fafab4b8c, or the token carries none of PageCycle's scopes. Answers may gain fields: ignore the ones you do not know." }, "servers": [ { "url": "https://api.atlassian.com/svc/confluence/{cloudId}/apps/{appId}_{environmentId}", "variables": { "cloudId": { "default": "your-cloud-id", "description": "From https://api.atlassian.com/oauth/token/accessible-resources, or https://.atlassian.net/_edge/tenant_info." }, "appId": { "default": "db702242-b6fc-4a44-bcea-e6ad97e8db84" }, "environmentId": { "default": "7b249cc1-1e34-4a73-850f-d51fafab4b8c", "description": "PageCycle's production environment." } } } ], "tags": [ { "name": "Pages", "description": "One page at a time: read its status and History, move it to another status, or set its next review. Every call acts as the person who signed in, so it reaches only the pages that person can open, and a move follows the same rules as Move to in Confluence." }, { "name": "Spaces", "description": "A whole space at a glance: which spaces use PageCycle, how many pages sit in each status, which pages need attention, the space's History, its workflow and its automations. These routes only read, and they count only the pages the person can view." }, { "name": "Workflow changes", "description": "Change a space's workflow: statuses, moves, defaults, automations and settings, or turn PageCycle on or off. Space admins only. Each call returns a preview and changes nothing until you confirm it with `POST /confirmations/{id}`, the same preview and confirm Rovo uses." }, { "name": "Confirmations and operations", "description": "Apply a preview, and follow a change that touches many pages. A confirmation applies exactly what was previewed, once, for the person who asked for it. A long change answers `202` with an operation id: call `POST /operations/{id}` until it answers `200`." } ], "paths": { "/pages/{page}/status": { "get": { "operationId": "getPagecyclePageStatus", "summary": "A page's workflow status, since when and who moved it there, the version approved, its next review and the moves the person can make.", "tags": [ "Pages" ], "x-pagecycle-tool": "getPagecyclePageStatus", "security": [ { "atlassian": [ "read:pagecycle:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "page", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{1,20}$", "description": "The Confluence page id.", "example": "8013" } } ], "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "version": { "type": "integer" }, "spaceId": { "type": "string" } }, "required": [ "id", "title", "version", "spaceId" ], "additionalProperties": false }, "status": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "draft", "review", "final", "attention", "archived" ] } }, "required": [ "id", "name", "category" ], "additionalProperties": false }, "since": { "type": [ "string", "null" ], "format": "date-time" }, "movedBy": { "type": [ "string", "null" ], "description": "Who moved the page into its status; null for an automation, an import or Confluence itself." }, "approvedVersion": { "type": [ "integer", "null" ], "description": "The page version the move into this status was made on." }, "reviewBy": { "type": [ "string", "null" ], "format": "date", "description": "The next review, YYYY-MM-DD." }, "confluenceStatusRemoved": { "type": "boolean", "description": "Confluence shows no status where PageCycle knew one (a Confluence approval may be running): a move needs confirm." }, "flagged": { "type": "boolean", "description": "The last status change broke the workflow; an allowed move clears it." }, "canEdit": { "type": "boolean" }, "movesPaused": { "type": "boolean", "description": "The person could move the page, but the PageCycle license is inactive." }, "moves": { "type": "array", "items": { "type": "object", "properties": { "to": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "label": { "type": "string" }, "commentRequired": { "type": "boolean" } }, "required": [ "to", "label", "commentRequired" ], "additionalProperties": false }, "description": "The moves the person can make now." } }, "required": [ "page", "status", "since", "movedBy", "approvedVersion", "reviewBy", "confluenceStatusRemoved", "flagged", "canEdit", "movesPaused", "moves" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Approved by Jordan Lee, Sep 30 · version 4 · next review Mar 30\nYou can move it to Archived (Archive).", "code": null, "data": { "page": { "id": "8013", "title": "Export to CSV spec", "version": 4, "spaceId": "7001" }, "status": { "id": "approved", "name": "Approved", "category": "final" }, "since": "2026-09-30T10:00:00.000Z", "movedBy": "Jordan Lee", "approvedVersion": 4, "reviewBy": "2027-03-30", "confluenceStatusRemoved": false, "flagged": false, "canEdit": true, "movesPaused": false, "moves": [ { "to": { "id": "archived", "name": "Archived" }, "label": "Archive", "commentRequired": false } ] } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "500": { "$ref": "#/components/responses/R500" } } } }, "/pages/{page}/moves": { "post": { "operationId": "movePagecyclePage", "summary": "Moves a page to another status in its space's workflow, as the person, under the same rules as Move to in Confluence. Recorded in the page's History.", "tags": [ "Pages" ], "x-pagecycle-tool": "movePagecyclePage", "security": [ { "atlassian": [ "write:pagecycle-page:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "page", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{1,20}$", "description": "The Confluence page id.", "example": "8013" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "to" ], "properties": { "to": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The status to move to, by name or id." }, "comment": { "type": [ "string", "null" ], "maxLength": 2000 }, "reviewDate": { "type": [ "string", "null" ], "maxLength": 40, "description": "For a move into a signed-off status: YYYY-MM-DD or \"in 6 months\"." }, "confirm": { "type": "boolean", "description": "Only after the person agreed: go ahead on a page whose Confluence status was removed." } } } } } }, "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, "status": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "draft", "review", "final", "attention", "archived" ] } }, "required": [ "id", "name", "category" ], "additionalProperties": false }, "reviewBy": { "type": [ "string", "null" ], "format": "date" }, "endedApproval": { "type": "boolean", "description": "The page had no Confluence status (an approval may have been running); this move ended it." } }, "required": [ "page", "status", "reviewBy", "endedApproval" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "In review · recorded in History", "code": null, "data": { "page": { "id": "8013", "title": "Export to CSV spec" }, "status": { "id": "in-review", "name": "In review", "category": "review" }, "reviewBy": null, "endedApproval": false } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "500": { "$ref": "#/components/responses/R500" }, "503": { "$ref": "#/components/responses/R503" } } } }, "/pages/{page}/history": { "get": { "operationId": "getPagecyclePageHistory", "summary": "Every move on a page with who, when and why, newest first, and whether it changed since sign-off.", "tags": [ "Pages" ], "x-pagecycle-tool": "getPagecyclePageHistory", "security": [ { "atlassian": [ "read:pagecycle:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "page", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{1,20}$", "description": "The Confluence page id.", "example": "8013" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{1,3}$", "description": "At most this many rows (1 to 50)." } } ], "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "version": { "type": "integer" } }, "required": [ "id", "title", "version" ], "additionalProperties": false }, "status": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "draft", "review", "final", "attention", "archived" ] } }, "required": [ "id", "name", "category" ], "additionalProperties": false }, "signedOffVersion": { "type": [ "integer", "null" ] }, "editedSinceSignOff": { "type": [ "boolean", "null" ], "description": "For a signed-off page: whether it was edited after the version signed off." }, "entries": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "kind": { "type": "string" }, "outcome": { "type": "string" }, "from": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "to": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "by": { "type": [ "string", "null" ], "description": "Who made it; null for an automation or an import." }, "comment": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "sentence": { "type": "string" } }, "required": [ "at", "kind", "outcome", "from", "to", "by", "comment", "reason", "sentence" ], "additionalProperties": false }, "description": "Newest first." }, "truncated": { "type": "boolean", "description": "More History exists than this call returned." } }, "required": [ "page", "status", "signedOffVersion", "editedSinceSignOff", "entries", "truncated" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Needs re-review since Oct 1 · version 9 · next review Mar 2\nOct 1 · Priya Nair edited the page, so PageCycle moved it from Approved to Needs re-review (\"Edited after approval\")\nSep 2 · Jordan Lee moved it from In review to Approved: \"Checked against the release plan\"", "code": null, "data": { "page": { "id": "8023", "title": "Search filters spec", "version": 9 }, "status": { "id": "needs-re-review", "name": "Needs re-review", "category": "attention" }, "signedOffVersion": null, "editedSinceSignOff": null, "entries": [ { "at": "2026-10-01T10:00:00.000Z", "kind": "automation", "outcome": "accepted", "from": { "id": "approved", "name": "Approved" }, "to": { "id": "needs-re-review", "name": "Needs re-review" }, "by": null, "comment": null, "reason": null, "sentence": "Priya Nair edited the page, so PageCycle moved it from Approved to Needs re-review (\"Edited after approval\")" }, { "at": "2026-09-02T10:00:00.000Z", "kind": "formal", "outcome": "accepted", "from": { "id": "in-review", "name": "In review" }, "to": { "id": "approved", "name": "Approved" }, "by": "Jordan Lee", "comment": "Checked against the release plan", "reason": null, "sentence": "Jordan Lee moved it from In review to Approved: \"Checked against the release plan\"" } ], "truncated": false } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "500": { "$ref": "#/components/responses/R500" } } } }, "/pages/{page}/reviewDate": { "put": { "operationId": "setPagecycleReviewDate", "summary": "Sets or clears a signed-off page's next review, as the person (they need edit permission). Recorded in the page's History.", "tags": [ "Pages" ], "x-pagecycle-tool": "setPagecycleReviewDate", "security": [ { "atlassian": [ "write:pagecycle-page:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "page", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{1,20}$", "description": "The Confluence page id.", "example": "8013" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 40, "description": "YYYY-MM-DD or \"in 6 months\"; null clears it." } }, "required": [ "date" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, "reviewBy": { "type": [ "string", "null" ], "format": "date" } }, "required": [ "page", "reviewBy" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Next review Apr 2 · recorded in History", "code": null, "data": { "page": { "id": "8014", "title": "SSO for Enterprise PRD" }, "reviewBy": "2027-04-02" } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "500": { "$ref": "#/components/responses/R500" }, "503": { "$ref": "#/components/responses/R503" } } } }, "/spaces": { "get": { "operationId": "listPagecycleSpaces", "summary": "Every space that uses PageCycle and where the person can view a tracked page, with its counts.", "tags": [ "Spaces" ], "x-pagecycle-tool": "listPagecycleSpaces", "security": [ { "atlassian": [ "read:pagecycle:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{1,3}$", "description": "At most this many rows (1 to 50)." } } ], "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "spaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "pages": { "type": "integer" }, "needsAttention": { "type": "integer" }, "overdue": { "type": "integer" } }, "required": [ "id", "key", "name", "pages", "needsAttention", "overdue" ], "additionalProperties": false } }, "total": { "type": "integer" }, "truncated": { "type": "boolean" }, "pagesTruncated": { "type": "boolean", "description": "Counted only the first tracked pages." } }, "required": [ "spaces", "total", "truncated", "pagesTruncated" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "1 space uses PageCycle\nProduct (PROD) · 28 pages · 4 need attention · 2 past the review date", "code": null, "data": { "spaces": [ { "id": "7001", "key": "PROD", "name": "Product", "pages": 28, "needsAttention": 4, "overdue": 2 } ], "total": 1, "truncated": false, "pagesTruncated": false } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "500": { "$ref": "#/components/responses/R500" } } } }, "/spaces/{space}/summary": { "get": { "operationId": "getPagecycleSpaceSummary", "summary": "How many pages are in each status in a space, and the pages that need attention. Counts only pages the person can view.", "tags": [ "Spaces" ], "x-pagecycle-tool": "getPagecycleSpaceSummary", "security": [ { "atlassian": [ "read:pagecycle:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } } ], "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "space": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "key", "name" ], "additionalProperties": false }, "total": { "type": "integer" }, "withoutStatus": { "type": "integer" }, "statuses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "count": { "type": "integer" }, "overdue": { "type": "integer" } }, "required": [ "id", "name", "category", "count", "overdue" ], "additionalProperties": false } }, "needsAttention": { "type": "array", "items": { "type": "object", "properties": { "page": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, "status": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "detail": { "type": "string" } }, "required": [ "page", "status", "detail" ], "additionalProperties": false }, "description": "At most 10; needsAttentionTotal counts them all." }, "needsAttentionTotal": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "space", "total", "withoutStatus", "statuses", "needsAttention", "needsAttentionTotal", "truncated" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "28 pages · 10 approved and current · 6 in review · 2 need re-review · 2 review due · 6 drafts · 2 archived\nNeeds re-review: Search filters spec · edited Oct 1\nNeeds re-review: API rate limits spec · edited Sep 30\nReview due: Data retention requirements · 17 days overdue\nReview due: Integrations roadmap · 4 days overdue", "code": null, "data": { "space": { "id": "7001", "key": "PROD", "name": "Product" }, "total": 28, "withoutStatus": 0, "statuses": [ { "id": "approved", "name": "Approved", "category": "final", "count": 10, "overdue": 0 }, { "id": "in-review", "name": "In review", "category": "review", "count": 6, "overdue": 0 }, { "id": "needs-re-review", "name": "Needs re-review", "category": "attention", "count": 2, "overdue": 0 }, { "id": "review-due", "name": "Review due", "category": "attention", "count": 2, "overdue": 2 }, { "id": "draft", "name": "Draft", "category": "draft", "count": 6, "overdue": 0 }, { "id": "archived", "name": "Archived", "category": "archived", "count": 2, "overdue": 0 } ], "needsAttention": [ { "page": { "id": "8023", "title": "Search filters spec" }, "status": { "id": "needs-re-review", "name": "Needs re-review" }, "detail": "edited Oct 1" }, { "page": { "id": "8024", "title": "API rate limits spec" }, "status": { "id": "needs-re-review", "name": "Needs re-review" }, "detail": "edited Sep 30" }, { "page": { "id": "8025", "title": "Data retention requirements" }, "status": { "id": "review-due", "name": "Review due" }, "detail": "17 days overdue" }, { "page": { "id": "8026", "title": "Integrations roadmap" }, "status": { "id": "review-due", "name": "Review due" }, "detail": "4 days overdue" } ], "needsAttentionTotal": 4, "truncated": false } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "500": { "$ref": "#/components/responses/R500" } } } }, "/spaces/{space}/pages": { "get": { "operationId": "listPagecyclePages", "summary": "Pages in a space by status, overdue for review, or stuck in their status for some days, at most 50 at a time.", "tags": [ "Spaces" ], "x-pagecycle-tool": "listPagecyclePages", "security": [ { "atlassian": [ "read:pagecycle:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 500, "description": "One status name, or several separated by commas." } }, { "name": "overdue", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "stuckDays", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{1,4}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{1,3}$", "description": "At most this many rows (1 to 50)." } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{1,20}$", "description": "The next value of the previous answer." } } ], "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "space": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "key", "name" ], "additionalProperties": false }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "draft", "review", "final", "attention", "archived" ] } }, "required": [ "id", "name", "category" ], "additionalProperties": false }, "daysInStatus": { "type": [ "integer", "null" ] }, "owner": { "type": [ "string", "null" ] }, "version": { "type": [ "integer", "null" ] }, "signedOffVersion": { "type": [ "integer", "null" ] }, "reviewBy": { "type": [ "string", "null" ], "format": "date" } }, "required": [ "id", "title", "status", "daysInStatus", "owner", "version", "signedOffVersion", "reviewBy" ], "additionalProperties": false } }, "total": { "type": "integer", "description": "Every page that matches." }, "next": { "type": [ "string", "null" ], "description": "Pass it as after for the next rows; null on the last." }, "truncated": { "type": "boolean" } }, "required": [ "space", "pages", "total", "next", "truncated" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Checkout redesign spec · Mobile onboarding PRD · Q1 roadmap · 3 more\nCheckout redesign spec · in review 8 days · owner Maya Chen\nMobile onboarding PRD · in review 3 days · owner Priya Nair\n4 more: call again with after: \"8008\".", "code": null, "data": { "space": { "id": "7001", "key": "PROD", "name": "Product" }, "pages": [ { "id": "8007", "title": "Checkout redesign spec", "status": { "id": "in-review", "name": "In review", "category": "review" }, "daysInStatus": 8, "owner": "Maya Chen", "version": 6, "signedOffVersion": null, "reviewBy": null }, { "id": "8008", "title": "Mobile onboarding PRD", "status": { "id": "in-review", "name": "In review", "category": "review" }, "daysInStatus": 3, "owner": "Priya Nair", "version": 4, "signedOffVersion": null, "reviewBy": null } ], "total": 6, "next": "8008", "truncated": false } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "500": { "$ref": "#/components/responses/R500" } } } }, "/spaces/{space}/history": { "get": { "operationId": "getPagecycleSpaceHistory", "summary": "A space's History, newest first, filtered by person, status or dates, for pages the person can view.", "tags": [ "Spaces" ], "x-pagecycle-tool": "getPagecycleSpaceHistory", "security": [ { "atlassian": [ "read:pagecycle:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } }, { "name": "person", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{1,3}$", "description": "At most this many rows (1 to 50)." } } ], "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "space": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "key", "name" ], "additionalProperties": false }, "entries": { "type": "array", "items": { "type": "object", "properties": { "page": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, "at": { "type": "string", "format": "date-time" }, "kind": { "type": "string" }, "outcome": { "type": "string" }, "from": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "to": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "by": { "type": [ "string", "null" ], "description": "Who made it; null for an automation or an import." }, "comment": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "sentence": { "type": "string" } }, "required": [ "page", "at", "kind", "outcome", "from", "to", "by", "comment", "reason", "sentence" ], "additionalProperties": false }, "description": "Newest first." }, "total": { "type": "integer" }, "truncated": { "type": "boolean" }, "windowFull": { "type": "boolean", "description": "The search read only the newest 500 changes: older matches may exist (narrow with to)." } }, "required": [ "space", "entries", "total", "truncated", "windowFull" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "30 changes in Product\nOct 1 · Priya Nair moved \"Offline mode spec\" to Draft\nOct 1 · Sam Park moved \"Saved views PRD\" to In review\nShowing the newest 2 (ask for up to 50, or narrow by person, status or dates).", "code": null, "data": { "space": { "id": "7001", "key": "PROD", "name": "Product" }, "entries": [ { "page": { "id": "8001", "title": "Offline mode spec" }, "at": "2026-10-01T10:00:00.000Z", "kind": "formal", "outcome": "accepted", "from": null, "to": { "id": "draft", "name": "Draft" }, "by": "Priya Nair", "comment": null, "reason": null, "sentence": "Priya Nair moved \"Offline mode spec\" to Draft" }, { "page": { "id": "8011", "title": "Saved views PRD" }, "at": "2026-10-01T10:00:00.000Z", "kind": "formal", "outcome": "accepted", "from": null, "to": { "id": "in-review", "name": "In review" }, "by": "Sam Park", "comment": null, "reason": null, "sentence": "Sam Park moved \"Saved views PRD\" to In review" } ], "total": 30, "truncated": true, "windowFull": false } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "500": { "$ref": "#/components/responses/R500" } } } }, "/spaces/{space}/workflow": { "get": { "operationId": "getPagecycleWorkflow", "summary": "A space's statuses and moves: who may make each move, which need a comment, and where pages start.", "tags": [ "Spaces" ], "x-pagecycle-tool": "getPagecycleWorkflow", "security": [ { "atlassian": [ "read:pagecycle:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } } ], "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "space": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "key", "name" ], "additionalProperties": false }, "enabled": { "type": "boolean" }, "statuses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "color": { "type": "string" } }, "required": [ "id", "name", "category", "color" ], "additionalProperties": false } }, "moves": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "from": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "to": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "groups": { "type": "array", "items": { "type": "string" } }, "commentRequired": { "type": "boolean" }, "automationOnly": { "type": "boolean" } }, "required": [ "id", "label", "from", "to", "groups", "commentRequired", "automationOnly" ], "additionalProperties": false } }, "startStatus": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "newPageStatus": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "space", "enabled", "statuses", "moves", "startStatus", "newPageStatus" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Product: 6 statuses, 11 moves\nStatuses: Draft (draft, purple), In review (in review, blue), Approved (signed off, green), Needs re-review (needs attention, yellow), Review due (needs attention, red), Archived (archived, grey)\nMove \"Submit for review\": Draft → In review · anyone who can edit\nMove \"Request changes\": In review → Draft · anyone who can edit\nMove \"Approve\": In review → Approved · pagecycle-approvers · comment required\nMove \"Edited after approval\": Approved → Needs re-review · automations only\nMove \"Resubmit\": Needs re-review → In review · anyone who can edit\nMove \"Re-approve\": Needs re-review → Approved · pagecycle-approvers · comment required\nMove \"Review date reached\": Approved → Review due · automations only\nMove \"Start review\": Review due → In review · anyone who can edit\nMove \"Confirm still valid\": Review due → Approved · pagecycle-approvers · comment required\nMove \"Archive\": Approved → Archived · anyone who can edit\nMove \"Reopen\": Archived → Draft · anyone who can edit\nPages start in Draft. New pages get no status.", "code": null, "data": { "space": { "id": "7001", "key": "PROD", "name": "Product" }, "enabled": true, "statuses": [ { "id": "draft", "name": "Draft", "category": "draft", "color": "purple" }, { "id": "in-review", "name": "In review", "category": "review", "color": "blue" }, { "id": "approved", "name": "Approved", "category": "final", "color": "green" }, { "id": "needs-re-review", "name": "Needs re-review", "category": "attention", "color": "yellow" }, { "id": "review-due", "name": "Review due", "category": "attention", "color": "red" }, { "id": "archived", "name": "Archived", "category": "archived", "color": "grey" } ], "moves": [ { "id": "submit", "label": "Submit for review", "from": { "id": "draft", "name": "Draft" }, "to": { "id": "in-review", "name": "In review" }, "groups": [], "commentRequired": false, "automationOnly": false }, { "id": "request-changes", "label": "Request changes", "from": { "id": "in-review", "name": "In review" }, "to": { "id": "draft", "name": "Draft" }, "groups": [], "commentRequired": false, "automationOnly": false }, { "id": "approve", "label": "Approve", "from": { "id": "in-review", "name": "In review" }, "to": { "id": "approved", "name": "Approved" }, "groups": [ "pagecycle-approvers" ], "commentRequired": true, "automationOnly": false }, { "id": "edited-after-approval", "label": "Edited after approval", "from": { "id": "approved", "name": "Approved" }, "to": { "id": "needs-re-review", "name": "Needs re-review" }, "groups": [], "commentRequired": false, "automationOnly": true }, { "id": "resubmit", "label": "Resubmit", "from": { "id": "needs-re-review", "name": "Needs re-review" }, "to": { "id": "in-review", "name": "In review" }, "groups": [], "commentRequired": false, "automationOnly": false }, { "id": "re-approve", "label": "Re-approve", "from": { "id": "needs-re-review", "name": "Needs re-review" }, "to": { "id": "approved", "name": "Approved" }, "groups": [ "pagecycle-approvers" ], "commentRequired": true, "automationOnly": false }, { "id": "review-date", "label": "Review date reached", "from": { "id": "approved", "name": "Approved" }, "to": { "id": "review-due", "name": "Review due" }, "groups": [], "commentRequired": false, "automationOnly": true }, { "id": "start-review", "label": "Start review", "from": { "id": "review-due", "name": "Review due" }, "to": { "id": "in-review", "name": "In review" }, "groups": [], "commentRequired": false, "automationOnly": false }, { "id": "still-valid", "label": "Confirm still valid", "from": { "id": "review-due", "name": "Review due" }, "to": { "id": "approved", "name": "Approved" }, "groups": [ "pagecycle-approvers" ], "commentRequired": true, "automationOnly": false }, { "id": "archive", "label": "Archive", "from": { "id": "approved", "name": "Approved" }, "to": { "id": "archived", "name": "Archived" }, "groups": [], "commentRequired": false, "automationOnly": false }, { "id": "reopen", "label": "Reopen", "from": { "id": "archived", "name": "Archived" }, "to": { "id": "draft", "name": "Draft" }, "groups": [], "commentRequired": false, "automationOnly": false } ], "startStatus": { "id": "draft", "name": "Draft" }, "newPageStatus": null } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "500": { "$ref": "#/components/responses/R500" } } } }, "/spaces/{space}/automations": { "get": { "operationId": "getPagecycleAutomations", "summary": "A space's automations in plain words, and for space admins whether they run well.", "tags": [ "Spaces" ], "x-pagecycle-tool": "getPagecycleAutomations", "security": [ { "atlassian": [ "read:pagecycle:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } } ], "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "space": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "key", "name" ], "additionalProperties": false }, "automations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "position": { "type": "integer" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "sentence": { "type": "string" } }, "required": [ "id", "position", "name", "enabled", "sentence" ], "additionalProperties": false } }, "health": { "type": [ "object", "null" ], "properties": { "checksLate": { "type": "boolean" }, "problems24h": { "type": "integer" }, "recent": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "page": { "type": [ "object", "null" ], "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false } }, "required": [ "text", "page" ], "additionalProperties": false } } }, "required": [ "checksLate", "problems24h", "recent" ], "additionalProperties": false, "description": "Space admins only." } }, "required": [ "space", "automations", "health" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Product: 2 automations\n1. Edited after approval: When a page is edited, if kind is signed off: move to Needs re-review\n2. Review date reached: When the review date passes, if kind is signed off: move to Review due; comment \"The review date for this page has passed. Please check it is still accurate, then move it to Approved again or start a review.\"\nHealth: PageCycle's status checks are running late; 0 problems in this space in the last 24 hours.", "code": null, "data": { "space": { "id": "7001", "key": "PROD", "name": "Product" }, "automations": [ { "id": "edited-after-approval", "position": 1, "name": "Edited after approval", "enabled": true, "sentence": "When a page is edited, if kind is signed off: move to Needs re-review" }, { "id": "review-due", "position": 2, "name": "Review date reached", "enabled": true, "sentence": "When the review date passes, if kind is signed off: move to Review due; comment \"The review date for this page has passed. Please check it is still accurate, then move it to Approved again or start a review.\"" } ], "health": { "checksLate": true, "problems24h": 0, "recent": [] } } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "500": { "$ref": "#/components/responses/R500" } } }, "post": { "operationId": "addPagecycleAutomation", "summary": "Previews a new automation written in words: when, if, then.", "tags": [ "Workflow changes" ], "x-pagecycle-tool": "addPagecycleAutomation", "security": [ { "atlassian": [ "manage:pagecycle-space:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "when": { "type": "string", "maxLength": 500, "description": "\"a page is edited\", \"moved to \", \"moved to any status\" or \"the review date passes\"." }, "if": { "type": "string", "maxLength": 1000, "description": "Conditions separated by \";\": \"status is A or B\", \"kind is signed off\", \"mover in group G\", \"label L\"." }, "then": { "type": "string", "maxLength": 1000, "description": "Actions separated by \";\": \"move to S\", \"review in N days\", \"add label L\", comment \"text\"." }, "name": { "type": "string", "maxLength": 255, "description": "The automation's name (default \"When \")." } }, "required": [ "when", "then" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "preview": { "type": "string", "maxLength": 60000, "description": "What would change, in words. Show it to the person. A preview over 60,000 bytes is refused, never cut." }, "note": { "type": [ "string", "null" ], "description": "Pages the change would leave alone, when there are any." }, "confirmation": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" }, "expiresAt": { "type": "string", "format": "date-time", "description": "After this, confirming answers 409 with a fresh preview." }, "confirmableAt": { "type": "string", "format": "date-time", "description": "Confirming before this answers 425." } }, "required": [ "preview", "note", "confirmation", "expiresAt", "confirmableAt" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Preview: adds the automation \"When moved to Approved\" in Product: When moved to Approved: review in 180 days\nNothing changes yet. Show this preview to the person. Once they agree, send POST /confirmations/op_id2, at least 8 seconds from now and within 15 minutes.", "code": null, "data": { "preview": "adds the automation \"When moved to Approved\" in Product: When moved to Approved: review in 180 days", "note": null, "confirmation": "op_id2", "expiresAt": "2026-10-02T12:15:00.000Z", "confirmableAt": "2026-10-02T12:00:08.000Z" } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "429": { "$ref": "#/components/responses/R429" }, "500": { "$ref": "#/components/responses/R500" } } } }, "/spaces/{space}/statuses": { "post": { "operationId": "addPagecycleStatus", "summary": "Previews a new status after an existing one, with the moves in and out of it copied from that status.", "tags": [ "Workflow changes" ], "x-pagecycle-tool": "addPagecycleStatus", "security": [ { "atlassian": [ "manage:pagecycle-space:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "The new status's name." }, "after": { "type": "string", "maxLength": 255, "description": "The status it comes after: pages reach it and leave it the way they leave that one." }, "kind": { "type": "string", "maxLength": 40, "description": "draft, in review, signed off, needs attention or archived (default: the kind of the status it comes after)." }, "color": { "type": "string", "maxLength": 40, "description": "purple, blue, green, yellow, red or grey (default: the kind's color)." } }, "required": [ "name", "after" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "preview": { "type": "string", "maxLength": 60000, "description": "What would change, in words. Show it to the person. A preview over 60,000 bytes is refused, never cut." }, "note": { "type": [ "string", "null" ], "description": "Pages the change would leave alone, when there are any." }, "confirmation": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" }, "expiresAt": { "type": "string", "format": "date-time", "description": "After this, confirming answers 409 with a fresh preview." }, "confirmableAt": { "type": "string", "format": "date-time", "description": "Confirming before this answers 425." } }, "required": [ "preview", "note", "confirmation", "expiresAt", "confirmableAt" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Preview: adds the status On hold (draft, purple) after Draft in Product · moves added: \"Send to On hold\" (Draft → On hold, anyone who can edit); \"Submit for review\" (On hold → In review, anyone who can edit) · no pages move\nNothing changes yet. Show this preview to the person. Once they agree, send POST /confirmations/op_id1, at least 8 seconds from now and within 15 minutes.", "code": null, "data": { "preview": "adds the status On hold (draft, purple) after Draft in Product · moves added: \"Send to On hold\" (Draft → On hold, anyone who can edit); \"Submit for review\" (On hold → In review, anyone who can edit) · no pages move", "note": null, "confirmation": "op_id1", "expiresAt": "2026-10-02T12:15:00.000Z", "confirmableAt": "2026-10-02T12:00:08.000Z" } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "429": { "$ref": "#/components/responses/R429" }, "500": { "$ref": "#/components/responses/R500" } } } }, "/spaces/{space}/statuses/{status}": { "patch": { "operationId": "updatePagecycleStatus", "summary": "Previews renaming, recoloring or changing the kind of a status, and updating every page that has it.", "tags": [ "Workflow changes" ], "x-pagecycle-tool": "updatePagecycleStatus", "security": [ { "atlassian": [ "manage:pagecycle-space:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } }, { "name": "status", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Its name, or its id (always works)." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "A new name." }, "color": { "type": "string", "maxLength": 40, "description": "purple, blue, green, yellow, red or grey (default: the kind's color)." }, "kind": { "type": "string", "maxLength": 40, "description": "draft, in review, signed off, needs attention or archived (default: the kind of the status it comes after)." } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "preview": { "type": "string", "maxLength": 60000, "description": "What would change, in words. Show it to the person. A preview over 60,000 bytes is refused, never cut." }, "note": { "type": [ "string", "null" ], "description": "Pages the change would leave alone, when there are any." }, "confirmation": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" }, "expiresAt": { "type": "string", "format": "date-time", "description": "After this, confirming answers 409 with a fresh preview." }, "confirmableAt": { "type": "string", "format": "date-time", "description": "Confirming before this answers 425." } }, "required": [ "preview", "note", "confirmation", "expiresAt", "confirmableAt" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Preview: renames Parked to On hold in Product · 0 pages hold it; their Confluence status and the label under the page title are rewritten under your name · a page whose Confluence status was removed is left as it is\nNothing changes yet. Show this preview to the person. Once they agree, send POST /confirmations/op_id1, at least 8 seconds from now and within 15 minutes.", "code": null, "data": { "preview": "renames Parked to On hold in Product · 0 pages hold it; their Confluence status and the label under the page title are rewritten under your name · a page whose Confluence status was removed is left as it is", "note": null, "confirmation": "op_id1", "expiresAt": "2026-10-02T12:15:00.000Z", "confirmableAt": "2026-10-02T12:00:08.000Z" } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "429": { "$ref": "#/components/responses/R429" }, "500": { "$ref": "#/components/responses/R500" } } }, "delete": { "operationId": "removePagecycleStatus", "summary": "Previews removing a status, moving its pages to another one first.", "tags": [ "Workflow changes" ], "x-pagecycle-tool": "removePagecycleStatus", "security": [ { "atlassian": [ "manage:pagecycle-space:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } }, { "name": "status", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Its name, or its id (always works)." } }, { "name": "moveTo", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255, "description": "Where its pages go." } } ], "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "preview": { "type": "string", "maxLength": 60000, "description": "What would change, in words. Show it to the person. A preview over 60,000 bytes is refused, never cut." }, "note": { "type": [ "string", "null" ], "description": "Pages the change would leave alone, when there are any." }, "confirmation": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" }, "expiresAt": { "type": "string", "format": "date-time", "description": "After this, confirming answers 409 with a fresh preview." }, "confirmableAt": { "type": "string", "format": "date-time", "description": "Confirming before this answers 425." } }, "required": [ "preview", "note", "confirmation", "expiresAt", "confirmableAt" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Preview: removes the status Parked from Product · first moves its 0 pages to Draft under your name (a page whose Confluence status was removed moves in PageCycle only) · moves into and out of Parked go too\nNothing changes yet. Show this preview to the person. Once they agree, send POST /confirmations/op_id1, at least 8 seconds from now and within 15 minutes.", "code": null, "data": { "preview": "removes the status Parked from Product · first moves its 0 pages to Draft under your name (a page whose Confluence status was removed moves in PageCycle only) · moves into and out of Parked go too", "note": null, "confirmation": "op_id1", "expiresAt": "2026-10-02T12:15:00.000Z", "confirmableAt": "2026-10-02T12:00:08.000Z" } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "429": { "$ref": "#/components/responses/R429" }, "500": { "$ref": "#/components/responses/R500" } } } }, "/spaces/{space}/moves": { "post": { "operationId": "addPagecycleMove", "summary": "Previews a new move between two statuses, optionally limited to groups or needing a comment.", "tags": [ "Workflow changes" ], "x-pagecycle-tool": "addPagecycleMove", "security": [ { "atlassian": [ "manage:pagecycle-space:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "maxLength": 255, "description": "The status the move starts from." }, "to": { "type": "string", "maxLength": 255, "description": "The status it moves to." }, "label": { "type": "string", "maxLength": 255 }, "groups": { "type": "string", "maxLength": 2000, "description": "Group names, separated by commas." }, "commentRequired": { "type": "boolean" } }, "required": [ "from", "to" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "preview": { "type": "string", "maxLength": 60000, "description": "What would change, in words. Show it to the person. A preview over 60,000 bytes is refused, never cut." }, "note": { "type": [ "string", "null" ], "description": "Pages the change would leave alone, when there are any." }, "confirmation": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" }, "expiresAt": { "type": "string", "format": "date-time", "description": "After this, confirming answers 409 with a fresh preview." }, "confirmableAt": { "type": "string", "format": "date-time", "description": "Confirming before this answers 425." } }, "required": [ "preview", "note", "confirmation", "expiresAt", "confirmableAt" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Preview: adds the move \"Shelve\" (Draft → Archived, anyone who can edit) in Product\nNothing changes yet. Show this preview to the person. Once they agree, send POST /confirmations/op_id1, at least 8 seconds from now and within 15 minutes.", "code": null, "data": { "preview": "adds the move \"Shelve\" (Draft → Archived, anyone who can edit) in Product", "note": null, "confirmation": "op_id1", "expiresAt": "2026-10-02T12:15:00.000Z", "confirmableAt": "2026-10-02T12:00:08.000Z" } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "429": { "$ref": "#/components/responses/R429" }, "500": { "$ref": "#/components/responses/R500" } } } }, "/spaces/{space}/moves/{move}": { "patch": { "operationId": "updatePagecycleMove", "summary": "Previews renaming a move, changing who may make it, or whether it needs a comment. Name it by its label or \"From → To\".", "tags": [ "Workflow changes" ], "x-pagecycle-tool": "updatePagecycleMove", "security": [ { "atlassian": [ "manage:pagecycle-space:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } }, { "name": "move", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Its name, or its id (always works)." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 255 }, "groups": { "type": "string", "maxLength": 2000 }, "commentRequired": { "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "preview": { "type": "string", "maxLength": 60000, "description": "What would change, in words. Show it to the person. A preview over 60,000 bytes is refused, never cut." }, "note": { "type": [ "string", "null" ], "description": "Pages the change would leave alone, when there are any." }, "confirmation": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" }, "expiresAt": { "type": "string", "format": "date-time", "description": "After this, confirming answers 409 with a fresh preview." }, "confirmableAt": { "type": "string", "format": "date-time", "description": "Confirming before this answers 425." } }, "required": [ "preview", "note", "confirmation", "expiresAt", "confirmableAt" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Preview: changes the move \"Shelve old\" (In review → Archived, anyone who can edit) to \"Retire\" (In review → Archived, anyone who can edit) in Product\nNothing changes yet. Show this preview to the person. Once they agree, send POST /confirmations/op_id1, at least 8 seconds from now and within 15 minutes.", "code": null, "data": { "preview": "changes the move \"Shelve old\" (In review → Archived, anyone who can edit) to \"Retire\" (In review → Archived, anyone who can edit) in Product", "note": null, "confirmation": "op_id1", "expiresAt": "2026-10-02T12:15:00.000Z", "confirmableAt": "2026-10-02T12:00:08.000Z" } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "429": { "$ref": "#/components/responses/R429" }, "500": { "$ref": "#/components/responses/R500" } } }, "delete": { "operationId": "removePagecycleMove", "summary": "Previews removing a move.", "tags": [ "Workflow changes" ], "x-pagecycle-tool": "removePagecycleMove", "security": [ { "atlassian": [ "manage:pagecycle-space:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } }, { "name": "move", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Its name, or its id (always works)." } } ], "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "preview": { "type": "string", "maxLength": 60000, "description": "What would change, in words. Show it to the person. A preview over 60,000 bytes is refused, never cut." }, "note": { "type": [ "string", "null" ], "description": "Pages the change would leave alone, when there are any." }, "confirmation": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" }, "expiresAt": { "type": "string", "format": "date-time", "description": "After this, confirming answers 409 with a fresh preview." }, "confirmableAt": { "type": "string", "format": "date-time", "description": "Confirming before this answers 425." } }, "required": [ "preview", "note", "confirmation", "expiresAt", "confirmableAt" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Preview: removes the move \"Shelve old\" (In review → Archived, anyone who can edit) from Product · pages keep their status\nNothing changes yet. Show this preview to the person. Once they agree, send POST /confirmations/op_id1, at least 8 seconds from now and within 15 minutes.", "code": null, "data": { "preview": "removes the move \"Shelve old\" (In review → Archived, anyone who can edit) from Product · pages keep their status", "note": null, "confirmation": "op_id1", "expiresAt": "2026-10-02T12:15:00.000Z", "confirmableAt": "2026-10-02T12:00:08.000Z" } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "429": { "$ref": "#/components/responses/R429" }, "500": { "$ref": "#/components/responses/R500" } } } }, "/spaces/{space}/workflowDefaults": { "put": { "operationId": "setPagecycleWorkflowDefaults", "summary": "Previews where pages start and which status new pages get.", "tags": [ "Workflow changes" ], "x-pagecycle-tool": "setPagecycleWorkflowDefaults", "security": [ { "atlassian": [ "manage:pagecycle-space:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "startStatus": { "type": "string", "maxLength": 255 }, "newPageStatus": { "type": "string", "maxLength": 255 } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "preview": { "type": "string", "maxLength": 60000, "description": "What would change, in words. Show it to the person. A preview over 60,000 bytes is refused, never cut." }, "note": { "type": [ "string", "null" ], "description": "Pages the change would leave alone, when there are any." }, "confirmation": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" }, "expiresAt": { "type": "string", "format": "date-time", "description": "After this, confirming answers 409 with a fresh preview." }, "confirmableAt": { "type": "string", "format": "date-time", "description": "Confirming before this answers 425." } }, "required": [ "preview", "note", "confirmation", "expiresAt", "confirmableAt" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Preview: new pages get In review in Product\nNothing changes yet. Show this preview to the person. Once they agree, send POST /confirmations/op_id1, at least 8 seconds from now and within 15 minutes.", "code": null, "data": { "preview": "new pages get In review in Product", "note": null, "confirmation": "op_id1", "expiresAt": "2026-10-02T12:15:00.000Z", "confirmableAt": "2026-10-02T12:00:08.000Z" } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "429": { "$ref": "#/components/responses/R429" }, "500": { "$ref": "#/components/responses/R500" } } } }, "/spaces/{space}/automations/{automation}": { "patch": { "operationId": "updatePagecycleAutomation", "summary": "Previews changing an automation, turning it on or off, or moving it in the list. Name it by its name or position.", "tags": [ "Workflow changes" ], "x-pagecycle-tool": "updatePagecycleAutomation", "security": [ { "atlassian": [ "manage:pagecycle-space:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } }, { "name": "automation", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Its name, or its id (always works)." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "when": { "type": "string", "maxLength": 500, "description": "\"a page is edited\", \"moved to \", \"moved to any status\" or \"the review date passes\"." }, "if": { "type": "string", "maxLength": 1000, "description": "Conditions separated by \";\": \"status is A or B\", \"kind is signed off\", \"mover in group G\", \"label L\"." }, "then": { "type": "string", "maxLength": 1000, "description": "Actions separated by \";\": \"move to S\", \"review in N days\", \"add label L\", comment \"text\"." }, "name": { "type": "string", "maxLength": 255 }, "enabled": { "type": "boolean" }, "position": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "preview": { "type": "string", "maxLength": 60000, "description": "What would change, in words. Show it to the person. A preview over 60,000 bytes is refused, never cut." }, "note": { "type": [ "string", "null" ], "description": "Pages the change would leave alone, when there are any." }, "confirmation": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" }, "expiresAt": { "type": "string", "format": "date-time", "description": "After this, confirming answers 409 with a fresh preview." }, "confirmableAt": { "type": "string", "format": "date-time", "description": "Confirming before this answers 425." } }, "required": [ "preview", "note", "confirmation", "expiresAt", "confirmableAt" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Preview: changes the automation \"Edited after approval\" in Product to: When a page is edited, if kind is signed off: move to Needs re-review (off)\nNothing changes yet. Show this preview to the person. Once they agree, send POST /confirmations/op_id1, at least 8 seconds from now and within 15 minutes.", "code": null, "data": { "preview": "changes the automation \"Edited after approval\" in Product to: When a page is edited, if kind is signed off: move to Needs re-review (off)", "note": null, "confirmation": "op_id1", "expiresAt": "2026-10-02T12:15:00.000Z", "confirmableAt": "2026-10-02T12:00:08.000Z" } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "429": { "$ref": "#/components/responses/R429" }, "500": { "$ref": "#/components/responses/R500" } } }, "delete": { "operationId": "removePagecycleAutomation", "summary": "Previews removing an automation.", "tags": [ "Workflow changes" ], "x-pagecycle-tool": "removePagecycleAutomation", "security": [ { "atlassian": [ "manage:pagecycle-space:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } }, { "name": "automation", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Its name, or its id (always works)." } } ], "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "preview": { "type": "string", "maxLength": 60000, "description": "What would change, in words. Show it to the person. A preview over 60,000 bytes is refused, never cut." }, "note": { "type": [ "string", "null" ], "description": "Pages the change would leave alone, when there are any." }, "confirmation": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" }, "expiresAt": { "type": "string", "format": "date-time", "description": "After this, confirming answers 409 with a fresh preview." }, "confirmableAt": { "type": "string", "format": "date-time", "description": "Confirming before this answers 425." } }, "required": [ "preview", "note", "confirmation", "expiresAt", "confirmableAt" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Preview: removes the automation \"Edited after approval\" (When a page is edited, if kind is signed off: move to Needs re-review) from Product\nNothing changes yet. Show this preview to the person. Once they agree, send POST /confirmations/op_id1, at least 8 seconds from now and within 15 minutes.", "code": null, "data": { "preview": "removes the automation \"Edited after approval\" (When a page is edited, if kind is signed off: move to Needs re-review) from Product", "note": null, "confirmation": "op_id1", "expiresAt": "2026-10-02T12:15:00.000Z", "confirmableAt": "2026-10-02T12:00:08.000Z" } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "429": { "$ref": "#/components/responses/R429" }, "500": { "$ref": "#/components/responses/R500" } } } }, "/spaces/{space}/settings": { "put": { "operationId": "updatePagecycleSpaceSettings", "summary": "Previews what happens when someone breaks the workflow in Confluence, and how long History is kept.", "tags": [ "Workflow changes" ], "x-pagecycle-tool": "updatePagecycleSpaceSettings", "security": [ { "atlassian": [ "manage:pagecycle-space:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "onBreak": { "type": "string", "maxLength": 40, "description": "\"put back\" or \"flag\"." }, "keepHistory": { "type": "string", "maxLength": 40, "description": "30 days, 90 days, 1 year or 3 years." } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "preview": { "type": "string", "maxLength": 60000, "description": "What would change, in words. Show it to the person. A preview over 60,000 bytes is refused, never cut." }, "note": { "type": [ "string", "null" ], "description": "Pages the change would leave alone, when there are any." }, "confirmation": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" }, "expiresAt": { "type": "string", "format": "date-time", "description": "After this, confirming answers 409 with a fresh preview." }, "confirmableAt": { "type": "string", "format": "date-time", "description": "Confirming before this answers 425." } }, "required": [ "preview", "note", "confirmation", "expiresAt", "confirmableAt" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Preview: a status change that breaks the workflow is flagged in Product\nNothing changes yet. Show this preview to the person. Once they agree, send POST /confirmations/op_id1, at least 8 seconds from now and within 15 minutes.", "code": null, "data": { "preview": "a status change that breaks the workflow is flagged in Product", "note": null, "confirmation": "op_id1", "expiresAt": "2026-10-02T12:15:00.000Z", "confirmableAt": "2026-10-02T12:00:08.000Z" } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "429": { "$ref": "#/components/responses/R429" }, "500": { "$ref": "#/components/responses/R500" } } } }, "/spaces/{space}/pagecycle": { "post": { "operationId": "enablePagecycleSpace", "summary": "Previews turning PageCycle on in a space: the default workflow, and the space's Confluence statuses matched to it.", "tags": [ "Workflow changes" ], "x-pagecycle-tool": "enablePagecycleSpace", "security": [ { "atlassian": [ "manage:pagecycle-space:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "mapping": { "type": "string", "maxLength": 2000, "description": "How Confluence statuses map to PageCycle statuses, when the preview asks." } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "preview": { "type": "string", "maxLength": 60000, "description": "What would change, in words. Show it to the person. A preview over 60,000 bytes is refused, never cut." }, "note": { "type": [ "string", "null" ], "description": "Pages the change would leave alone, when there are any." }, "confirmation": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" }, "expiresAt": { "type": "string", "format": "date-time", "description": "After this, confirming answers 409 with a fresh preview." }, "confirmableAt": { "type": "string", "format": "date-time", "description": "Confirming before this answers 425." } }, "required": [ "preview", "note", "confirmation", "expiresAt", "confirmableAt" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Preview: turns PageCycle on in News · 0 pages scanned · 0 without a status stay without one · pages restricted from you aren't counted\nNothing changes yet. Show this preview to the person. Once they agree, send POST /confirmations/op_id1, at least 8 seconds from now and within 15 minutes.", "code": null, "data": { "preview": "turns PageCycle on in News · 0 pages scanned · 0 without a status stay without one · pages restricted from you aren't counted", "note": null, "confirmation": "op_id1", "expiresAt": "2026-10-02T12:15:00.000Z", "confirmableAt": "2026-10-02T12:00:08.000Z" } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "429": { "$ref": "#/components/responses/R429" }, "500": { "$ref": "#/components/responses/R500" } } }, "delete": { "operationId": "disablePagecycleSpace", "summary": "Previews turning PageCycle off in a space. History and settings stay.", "tags": [ "Workflow changes" ], "x-pagecycle-tool": "disablePagecycleSpace", "security": [ { "atlassian": [ "manage:pagecycle-space:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "space", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9~_-]{1,255}$", "description": "The Confluence space key.", "example": "WS" } } ], "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "preview": { "type": "string", "maxLength": 60000, "description": "What would change, in words. Show it to the person. A preview over 60,000 bytes is refused, never cut." }, "note": { "type": [ "string", "null" ], "description": "Pages the change would leave alone, when there are any." }, "confirmation": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" }, "expiresAt": { "type": "string", "format": "date-time", "description": "After this, confirming answers 409 with a fresh preview." }, "confirmableAt": { "type": "string", "format": "date-time", "description": "Confirming before this answers 425." } }, "required": [ "preview", "note", "confirmation", "expiresAt", "confirmableAt" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Preview: turns PageCycle off in Product · History is kept · pages keep their Confluence status · moves are no longer checked\nNothing changes yet. Show this preview to the person. Once they agree, send POST /confirmations/op_id1, at least 8 seconds from now and within 15 minutes.", "code": null, "data": { "preview": "turns PageCycle off in Product · History is kept · pages keep their Confluence status · moves are no longer checked", "note": null, "confirmation": "op_id1", "expiresAt": "2026-10-02T12:15:00.000Z", "confirmableAt": "2026-10-02T12:00:08.000Z" } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "429": { "$ref": "#/components/responses/R429" }, "500": { "$ref": "#/components/responses/R500" } } } }, "/confirmations/{id}": { "post": { "operationId": "confirmPagecycleChange", "summary": "Applies a preview, for the person who asked for it, at least 8 seconds after it and within 15 minutes. Repeating it answers the saved result.", "tags": [ "Confirmations and operations" ], "x-pagecycle-tool": "confirmPagecycleChange", "security": [ { "atlassian": [ "manage:pagecycle-space:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" } } ], "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "operation": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" }, "status": { "type": "string", "enum": [ "previewed", "applying", "running", "done", "failed", "expired", "superseded" ] }, "progress": { "type": [ "string", "null" ], "description": "How far a long change got." }, "preview": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "operation", "status" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Done: the move \"Shelve\" is in Product's workflow.", "code": null, "data": { "operation": "op_id1", "status": "done" } } } } }, "202": { "$ref": "#/components/responses/R202" }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "425": { "$ref": "#/components/responses/R425" }, "500": { "$ref": "#/components/responses/R500" }, "503": { "$ref": "#/components/responses/R503" } } } }, "/operations/{id}": { "post": { "operationId": "getPagecycleOperation", "summary": "Continues a long change by its next batch, for its previewer or another space admin, and says how far it got.", "tags": [ "Confirmations and operations" ], "x-pagecycle-tool": "getPagecycleOperation", "security": [ { "atlassian": [ "manage:pagecycle-space:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" } } ], "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "operation": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" }, "status": { "type": "string", "enum": [ "previewed", "applying", "running", "done", "failed", "expired", "superseded" ] }, "progress": { "type": [ "string", "null" ], "description": "How far a long change got." }, "preview": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "operation", "status" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Done: the move \"Shelve\" is in Product's workflow.", "code": null, "data": { "operation": "op_id1", "status": "done" } } } } }, "202": { "$ref": "#/components/responses/R202" }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "500": { "$ref": "#/components/responses/R500" }, "503": { "$ref": "#/components/responses/R503" } } }, "get": { "operationId": "getPagecycleOperationStatus", "summary": "Where a change stands, read only: it never applies a batch. For a space admin of its space; a preview nobody confirmed only for its previewer.", "tags": [ "Confirmations and operations" ], "x-pagecycle-tool": "getPagecycleOperationStatus", "security": [ { "atlassian": [ "read:pagecycle:custom", "read:forge-app:confluence" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" } } ], "responses": { "200": { "description": "Done, in words and as data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string", "description": "The same words Rovo and MCP get." }, "code": { "type": [ "string", "null" ], "description": "null on success; \"working\" for a long change that goes on." }, "data": { "type": "object", "properties": { "operation": { "type": "string", "pattern": "^op_[A-Za-z0-9]{1,40}$", "description": "The confirmation or operation id a preview or a progress answer gave.", "example": "op_8f2c1d0e9a7b6c5d" }, "status": { "type": "string", "enum": [ "previewed", "applying", "running", "done", "failed", "expired", "superseded" ] }, "kind": { "type": "string", "description": "The tool that previewed it." }, "preview": { "type": "string" }, "progress": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "operation", "status", "kind", "preview", "progress", "expiresAt", "finishedAt" ], "additionalProperties": false } } }, "example": { "ok": true, "answer": "Previewed, not applied: adds the move \"Shelve\" (Draft → Archived, anyone who can edit) in Product", "code": null, "data": { "operation": "op_id1", "status": "previewed", "kind": "addPagecycleMove", "preview": "adds the move \"Shelve\" (Draft → Archived, anyone who can edit) in Product", "progress": null, "expiresAt": "2026-10-02T12:15:00.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/R400" }, "401": { "$ref": "#/components/responses/R401" }, "403": { "$ref": "#/components/responses/R403" }, "404": { "$ref": "#/components/responses/R404" }, "409": { "$ref": "#/components/responses/R409" }, "500": { "$ref": "#/components/responses/R500" } } } } }, "components": { "securitySchemes": { "atlassian": { "type": "oauth2", "description": "OAuth 2.0 (3LO) with an integration you create in the Atlassian developer console. Add sns=db702242-b6fc-4a44-bcea-e6ad97e8db84.7b249cc1-1e34-4a73-850f-d51fafab4b8c to the authorization URL, or Atlassian leaves PageCycle's scopes out of the token.", "flows": { "authorizationCode": { "authorizationUrl": "https://auth.atlassian.com/authorize", "tokenUrl": "https://auth.atlassian.com/oauth/token", "scopes": { "read:pagecycle:custom": "Read PageCycle: page statuses, History, next reviews, space summaries, workflows, automations and change progress, for what the person can view.", "write:pagecycle-page:custom": "Move PageCycle pages: move a page to another status and set or clear its next review, as the person.", "manage:pagecycle-space:custom": "Change PageCycle space settings (space admins): statuses, moves, defaults, automations and settings, turning PageCycle on or off, and confirming previewed changes.", "read:forge-app:confluence": "Atlassian's scope for calling a Forge app's REST API." } } } } }, "schemas": { "Refusal": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "const": false }, "answer": { "type": "string", "description": "Why, in the words Rovo and MCP get; a refused change starts \"Not done.\"" }, "code": { "type": "string", "enum": [ "bad_input", "conflict", "expired", "failed", "limited", "needs_access", "not_admin", "not_allowed", "not_found", "other_actor", "stale", "too_early", "unknown_actor", "unlicensed" ] }, "data": { "type": [ "object", "null" ], "description": "A fresh preview, a confirmableAt time, an operation, or confirmNeeded: true when a move needs the person's go-ahead (send it again with confirm: true once they agree)." } } }, "Working": { "type": "object", "required": [ "ok", "answer", "code", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "answer": { "type": "string" }, "code": { "type": "string", "const": "working" }, "data": { "type": "object", "required": [ "operation", "status" ], "properties": { "operation": { "type": "string", "description": "Continue with POST /operations/{operation}." }, "status": { "type": "string" }, "progress": { "type": "string" } } } } } }, "responses": { "R202": { "description": "Working: a long change goes on; continue it with POST /operations/{id}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Working" } } } }, "R400": { "description": "The request is malformed, or names something the tool cannot read (code bad_input).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "R401": { "description": "No person is signed in behind the token (code unknown_actor).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "R403": { "description": "The person may not do this: no permission, not a space admin, someone else's preview, or they have not allowed PageCycle access yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "R404": { "description": "Not found, or the person cannot view it. Nothing in the answer names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "R409": { "description": "Does not fit the space as it is now: PageCycle is off in the space, the workflow does not allow it, the page needs the person's go-ahead first (data.confirmNeeded), or the preview expired or the settings changed (a fresh preview is in data).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "R425": { "description": "Too early: a confirmation waits 8 seconds after its preview (data.confirmableAt).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "R429": { "description": "Too many unconfirmed previews in two minutes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "R500": { "description": "PageCycle could not finish; the answer says so in words.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "R503": { "description": "The PageCycle license is inactive: moves, review dates and long changes are paused; reads and settings still answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }