openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "IntraVox API",
    "version": "3.1.2",
    "description": "IntraVox is a modern intranet page builder for Nextcloud. This API provides endpoints for managing pages, media, navigation, comments, reactions, the Photo Story widget (galleries with EXIF, maps and lightbox) and the File Story widget (document libraries with MetaVox-aware filtering and federated-share awareness).\n\n## Authentication failures and 429\n\nNextcloud applies brute-force protection to failed authentication at the platform level. Any authenticated endpoint here can therefore answer 429 Too Many Requests after repeated bad credentials from one address, whether or not that operation documents its own rate limit — and once tripped it keeps answering 429 even for correct credentials until the window expires.\n\nThis surprises automated clients most: a retry loop on a wrong token does not eventually succeed, it locks the address out. Treat 401 as terminal and fix the credentials rather than retrying.",
    "license": {
      "name": "AGPL-3.0",
      "url": "https://www.gnu.org/licenses/agpl-3.0.html"
    }
  },
  "servers": [
    {
      "url": "https://{nextcloud_host}/apps/intravox",
      "description": "The app mount. Every path in this document answers here. Browser-session routes require the Nextcloud session cookie plus a requesttoken; the rest accept an app password over Basic auth.",
      "variables": {
        "nextcloud_host": {
          "default": "localhost",
          "description": "Nextcloud server hostname"
        }
      }
    }
  ],
  "security": [
    {
      "basic_auth": []
    },
    {
      "bearer_auth": []
    }
  ],
  "tags": [
    {
      "name": "Analytics",
      "description": "Page view statistics and their collection settings."
    },
    {
      "name": "Bulk",
      "description": "Administrator-only batch operations over pages, capped at 100 ids per call. Each item is convergent so a partial batch can be retried whole."
    },
    {
      "name": "Calendar",
      "description": "Calendar events surfaced by the calendar widget."
    },
    {
      "name": "Comments",
      "description": "Page comments and reactions"
    },
    {
      "name": "Demo Data",
      "description": "Bundled demo content: install it per language, or wipe a language and start fresh."
    },
    {
      "name": "Export",
      "description": "Content export"
    },
    {
      "name": "External API",
      "description": "The /ocs/v2.php entry points, for tools outside the browser session."
    },
    {
      "name": "Feeds",
      "description": "External feed sources: RSS/Atom plus configured connections to Moodle, Canvas, Brightspace, Jira, SharePoint, OpenProject and generic REST APIs."
    },
    {
      "name": "File Story",
      "description": "Paginated document browsing with grouping."
    },
    {
      "name": "LMS",
      "description": "Per-user account linking to learning platforms, by OAuth2 or by a manually issued API token. Tokens are stored per user and never returned."
    },
    {
      "name": "Languages",
      "description": "Which languages the instance offers, and their homepages."
    },
    {
      "name": "Licensing",
      "description": "Subscription key, usage reporting and telemetry."
    },
    {
      "name": "Link Previews",
      "description": "Server-side fetching of link preview metadata."
    },
    {
      "name": "Media",
      "description": "Media file operations"
    },
    {
      "name": "Navigation",
      "description": "Navigation management"
    },
    {
      "name": "News",
      "description": "News widget data"
    },
    {
      "name": "Orphaned Data",
      "description": "Administrator tooling for GroupFolder directories left on disk without a database row. Reads and writes the raw data directory."
    },
    {
      "name": "Page Locks",
      "description": "Cooperative editing locks that stop two people overwriting each other."
    },
    {
      "name": "Pages",
      "description": "Page management operations"
    },
    {
      "name": "People",
      "description": "User directory queries behind the people widget."
    },
    {
      "name": "Photo Story",
      "description": "Paginated photo browsing, clustering and EXIF."
    },
    {
      "name": "Public Share",
      "description": "Anonymous access to shared content via Nextcloud share links. No authentication required — access is controlled by the share token. Password-protected shares require session-based authentication via the /s/{token}/authenticate endpoint."
    },
    {
      "name": "RSS Feed",
      "description": "Token-authenticated RSS output and its token management."
    },
    {
      "name": "Settings",
      "description": "App settings (admin only)"
    },
    {
      "name": "Templates",
      "description": "Page template management - create pages from templates, save custom templates, and manage template library"
    },
    {
      "name": "Translations",
      "description": "Linking pages as language versions of one another."
    }
  ],
  "paths": {
    "/api/admin/shares": {
      "get": {
        "operationId": "get-active-shares",
        "summary": "Every public link share on IntraVox content",
        "description": "Lists all link shares pointing into the IntraVox group folder, newest first, with enough context to judge each one: what it exposes, who made it, whether it has expired and where to find it.\n\nAdministrators only, and the reason is the token: this response contains the actual share TOKENS, so anyone who can read it can open every shared page regardless of their own permissions.\n\nExpired shares are INCLUDED and flagged rather than filtered out — an expired link that still exists is exactly what an audit wants to see.",
        "tags": [
          "Public Share"
        ],
        "responses": {
          "200": {
            "description": "Active and expired link shares.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "token": {
                        "type": "string",
                        "description": "The live share token. Treat as a credential."
                      },
                      "scope": {
                        "type": "string",
                        "enum": [
                          "page",
                          "folder",
                          "language"
                        ],
                        "description": "What the link exposes: a single page, a folder subtree, or a whole language."
                      },
                      "scopeLabel": {
                        "type": "string",
                        "description": "Human label — the page title where one could be read, otherwise a derived name."
                      },
                      "language": {
                        "type": "string"
                      },
                      "path": {
                        "type": "string",
                        "description": "Path within the group folder."
                      },
                      "owner": {
                        "type": "string"
                      },
                      "expired": {
                        "type": "boolean"
                      },
                      "expirationDate": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "createdAt": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "filesUrl": {
                        "type": "string",
                        "description": "Relative link to the item in the Files app."
                      },
                      "publicUrl": {
                        "type": "string",
                        "description": "Relative public share link."
                      }
                    },
                    "required": [
                      "token",
                      "scope",
                      "language",
                      "path",
                      "owner",
                      "expired"
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Administrator access required."
          },
          "500": {
            "description": "Shares could not be listed."
          }
        }
      }
    },
    "/api/analytics/dashboard": {
      "get": {
        "operationId": "get-analytics-dashboard",
        "summary": "Instance-wide analytics",
        "tags": [
          "Analytics"
        ],
        "description": "Aggregated figures across the instance. Admin only; a non-admin gets 403.",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window in days. Clamped to 1..365.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 365,
              "default": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Aggregated statistics.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsStats"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/analytics/page/{pageId}": {
      "get": {
        "operationId": "get-page-stats",
        "summary": "View statistics for one page",
        "tags": [
          "Analytics"
        ],
        "description": "Per-page view counts over a window. Any logged-in user may read these.",
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window in days. Clamped to 1..365.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 365,
              "default": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Statistics for the page.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsStats"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/analytics/settings": {
      "get": {
        "operationId": "get-analytics-settings",
        "summary": "Read analytics settings",
        "tags": [
          "Analytics"
        ],
        "description": "Admin only.",
        "responses": {
          "200": {
            "description": "The current settings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsSettings"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "operationId": "set-analytics-settings",
        "summary": "Update analytics settings",
        "tags": [
          "Analytics"
        ],
        "description": "Admin only. Values outside the accepted range are clamped, not rejected.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean",
                    "default": true
                  },
                  "retentionDays": {
                    "type": "integer",
                    "minimum": 7,
                    "maximum": 365,
                    "default": 90
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The settings as stored.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsSettings"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/analytics/top": {
      "get": {
        "operationId": "get-top-pages",
        "summary": "Most-viewed pages",
        "tags": [
          "Analytics"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many pages to return. Clamped to 1..50.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window in days. Clamped to 1..365.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 365,
              "default": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The most-viewed pages in the window.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopPages"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/analytics/track/{pageId}": {
      "post": {
        "operationId": "track-page-view",
        "summary": "Record a page view",
        "tags": [
          "Analytics"
        ],
        "description": "Rate limited to 60 per minute per user. Answers success even when collection is disabled, so a client need not branch on the setting.",
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recorded, or accepted and ignored when analytics is off.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Rate limit exceeded."
          }
        }
      }
    },
    "/api/bulk/delete": {
      "post": {
        "operationId": "bulk-delete",
        "summary": "Delete pages in bulk",
        "description": "Deletes up to 100 pages. Deleting a page that is already gone counts as success, which is what makes a retry safe.\n\nRETRY SAFETY. Each item is convergent, so re-sending the same request after a partial failure is safe: a page already deleted counts as deleted, and a page already under the target parent counts as moved. A client that retries the whole batch therefore converges rather than double-counting or erroring. There is no server-side ledger of what a previous call did — the guarantee comes from each item being idempotent, not from request de-duplication.\n\nAt most 100 page ids per call; more returns 400. This is a hard service limit, not a page size — there is no continuation token. A migration splits its own work into batches.\n\nAdministrators only.\n\nEvery call is written to the audit log with the caller, the ids and the counts.",
        "tags": [
          "Bulk"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pageIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 100,
                    "description": "Page unique ids. Must be non-empty."
                  },
                  "deleteChildren": {
                    "type": "boolean",
                    "default": true,
                    "description": "Whether to remove child pages along with each parent. Defaults to TRUE — omitting it deletes subtrees."
                  },
                  "dryRun": {
                    "type": "boolean",
                    "default": false,
                    "description": "When true nothing is changed and the response is a BulkValidation envelope instead of a BulkResult. Equivalent to calling /api/bulk/validate with the same ids."
                  }
                },
                "required": [
                  "pageIds"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Every page succeeded.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/BulkResult"
                    },
                    {
                      "$ref": "#/components/schemas/BulkValidation"
                    }
                  ],
                  "description": "BulkValidation when dryRun was true, BulkResult otherwise."
                }
              }
            }
          },
          "207": {
            "description": "Multi-Status: at least one page failed and at least the attempt was made. Read results[] for the per-page outcome. The overall HTTP call succeeded — do not treat this as an error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Administrator access required."
          },
          "429": {
            "description": "Rate limit exceeded (5 per minute per user)."
          },
          "500": {
            "description": "The operation failed as a whole. Nothing partial is reported."
          }
        }
      }
    },
    "/api/bulk/move": {
      "post": {
        "operationId": "bulk-move",
        "summary": "Move pages under a new parent",
        "description": "Re-parents up to 100 pages. A page already under the target counts as moved.\n\nRETRY SAFETY. Each item is convergent, so re-sending the same request after a partial failure is safe: a page already deleted counts as deleted, and a page already under the target parent counts as moved. A client that retries the whole batch therefore converges rather than double-counting or erroring. There is no server-side ledger of what a previous call did — the guarantee comes from each item being idempotent, not from request de-duplication.\n\nAt most 100 page ids per call; more returns 400. This is a hard service limit, not a page size — there is no continuation token. A migration splits its own work into batches.\n\nAdministrators only.\n\nEvery call is written to the audit log.\n\nThree moves are refused per page and reported as that page's failure, not as a request error:\n- into itself or one of its own descendants (it would detach the subtree),\n- across languages — language folders are independent content trees, so this would be a relocation between intranets rather than a translation,\n- the homepage, which is protected.\n\nIf the target parent itself is missing or not writable, EVERY page in the batch fails with that reason and nothing is attempted.\n\nAn empty targetParentId is rejected as a 400 here. Note that the underlying move treats an empty target as 'the root of the page's own language', but this endpoint requires an explicit parent.",
        "tags": [
          "Bulk"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pageIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 100,
                    "description": "Page unique ids. Must be non-empty."
                  },
                  "targetParentId": {
                    "type": "string",
                    "description": "Unique id of the new parent. Required and non-empty."
                  },
                  "dryRun": {
                    "type": "boolean",
                    "default": false,
                    "description": "When true nothing is changed and the response is a BulkValidation envelope instead of a BulkResult. Equivalent to calling /api/bulk/validate with the same ids."
                  }
                },
                "required": [
                  "pageIds",
                  "targetParentId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Every page succeeded.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/BulkResult"
                    },
                    {
                      "$ref": "#/components/schemas/BulkValidation"
                    }
                  ],
                  "description": "BulkValidation when dryRun was true, BulkResult otherwise."
                }
              }
            }
          },
          "207": {
            "description": "Multi-Status: at least one page failed and at least the attempt was made. Read results[] for the per-page outcome. The overall HTTP call succeeded — do not treat this as an error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Administrator access required."
          },
          "429": {
            "description": "Rate limit exceeded (5 per minute per user)."
          },
          "500": {
            "description": "The operation failed as a whole. Nothing partial is reported."
          }
        }
      }
    },
    "/api/bulk/update": {
      "post": {
        "operationId": "bulk-update",
        "summary": "Update page properties in bulk",
        "description": "Applies the same property changes to up to 100 pages.\n\nAt most 100 page ids per call; more returns 400. This is a hard service limit, not a page size — there is no continuation token. A migration splits its own work into batches.\n\nAdministrators only.\n\nUnlike delete and move this is not inherently convergent — re-sending applies the same values again, which is harmless for the absolute updates supported here but is not a general guarantee.\n\nEvery call is written to the audit log, including which fields were touched.",
        "tags": [
          "Bulk"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pageIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 100,
                    "description": "Page unique ids. Must be non-empty."
                  },
                  "updates": {
                    "type": "object",
                    "additionalProperties": true,
                    "minProperties": 1,
                    "description": "Properties to set on every listed page, e.g. {\"metadata\": {\"category\": \"news\"}}. Must be a non-empty object."
                  },
                  "dryRun": {
                    "type": "boolean",
                    "default": false,
                    "description": "When true nothing is changed and the response is a BulkValidation envelope instead of a BulkResult. Equivalent to calling /api/bulk/validate with the same ids."
                  }
                },
                "required": [
                  "pageIds",
                  "updates"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Every page succeeded.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/BulkResult"
                    },
                    {
                      "$ref": "#/components/schemas/BulkValidation"
                    }
                  ],
                  "description": "BulkValidation when dryRun was true, BulkResult otherwise."
                }
              }
            }
          },
          "207": {
            "description": "Multi-Status: at least one page failed and at least the attempt was made. Read results[] for the per-page outcome. The overall HTTP call succeeded — do not treat this as an error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Administrator access required."
          },
          "429": {
            "description": "Rate limit exceeded (5 per minute per user)."
          },
          "500": {
            "description": "The operation failed as a whole. Nothing partial is reported."
          }
        }
      }
    },
    "/api/bulk/validate": {
      "post": {
        "operationId": "bulk-validate",
        "summary": "Dry-run a bulk operation",
        "description": "Reports which of the submitted pages the caller may operate on, without changing anything. This IS the dry run — there is no separate mode; validate and execute are different endpoints.\n\nAt most 100 page ids per call; more returns 400. This is a hard service limit, not a page size — there is no continuation token. A migration splits its own work into batches.\n\nAdministrators only.\n\nRate limited to 20 per minute, deliberately looser than the mutating endpoints (5 per minute): checking before acting is behaviour worth keeping cheap.",
        "tags": [
          "Bulk"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pageIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 100
                  },
                  "operation": {
                    "type": "string",
                    "enum": [
                      "delete",
                      "move",
                      "update"
                    ],
                    "description": "Which permission to test: delete checks canDelete, move and update check canWrite."
                  }
                },
                "required": [
                  "pageIds",
                  "operation"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation outcome",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkValidation"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Administrator access required."
          },
          "429": {
            "description": "Rate limit exceeded (20 per minute per user)."
          },
          "500": {
            "description": "Validation failed."
          }
        }
      }
    },
    "/api/calendar/calendars": {
      "get": {
        "operationId": "get-calendars",
        "summary": "List available calendars",
        "description": "Returns all calendars available to the current user (personal + shared)",
        "tags": [
          "Calendar"
        ],
        "responses": {
          "200": {
            "description": "List of calendars",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "calendars": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Nextcloud calendar id. A STRING on the wire even though it is numeric."
                          },
                          "uri": {
                            "type": "string"
                          },
                          "displayName": {
                            "type": "string"
                          },
                          "color": {
                            "type": "string"
                          },
                          "isReadOnly": {
                            "type": "boolean"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "500": {
            "description": "Failed to get calendars"
          }
        }
      }
    },
    "/api/calendar/events": {
      "get": {
        "operationId": "get-calendar-events",
        "summary": "Get calendar events",
        "description": "Returns events from one or more calendars within a time range. Recurring events are expanded into individual occurrences. Private/confidential events are filtered out.",
        "tags": [
          "Calendar"
        ],
        "parameters": [
          {
            "name": "calendarIds",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated calendar IDs"
          },
          {
            "name": "rangeStart",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Start of date range (ISO 8601). Defaults to now"
          },
          {
            "name": "rangeEnd",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "End of date range (ISO 8601). Defaults to 30 days from now"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 5,
              "minimum": 1,
              "maximum": 20
            },
            "description": "Maximum events to return"
          }
        ],
        "responses": {
          "200": {
            "description": "List of events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "uid": {
                            "type": "string"
                          },
                          "summary": {
                            "type": "string"
                          },
                          "location": {
                            "type": "string"
                          },
                          "start": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "end": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "isAllDay": {
                            "type": "boolean"
                          },
                          "calendarColor": {
                            "type": "string"
                          },
                          "calendarName": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid date format"
          },
          "401": {
            "description": "Authentication required"
          },
          "500": {
            "description": "Failed to get calendar events"
          }
        }
      }
    },
    "/api/comments/{commentId}": {
      "put": {
        "operationId": "update-comment",
        "summary": "Update comment",
        "tags": [
          "Comments"
        ],
        "parameters": [
          {
            "name": "commentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content": {
                    "type": "string"
                  }
                },
                "required": [
                  "content"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated comment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Comment"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not the comment's author, and not an administrator. Message is specific and safe to display."
          },
          "404": {
            "description": "No such comment, or no access to its page. Message is specific and safe to display."
          },
          "500": {
            "description": "Something went wrong. The body carries a generic message plus an errorId that correlates with the server log.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SafeError"
                }
              }
            }
          }
        },
        "description": "\n\nOne deliberate exception to the generic-error rule: 404 and 403 here carry a specific message ('Comment not found', 'Not authorized to edit this comment'). Those are strings this app throws itself, never an underlying error, and clients route on them — so they stay verbatim while everything else is generic."
      },
      "delete": {
        "operationId": "delete-comment",
        "summary": "Delete comment",
        "tags": [
          "Comments"
        ],
        "parameters": [
          {
            "name": "commentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessAck"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not the comment's author, and not an administrator. Message is specific and safe to display."
          },
          "404": {
            "description": "No such comment, or no access to its page. Message is specific and safe to display."
          },
          "500": {
            "description": "Something went wrong. The body carries a generic message plus an errorId that correlates with the server log.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SafeError"
                }
              }
            }
          }
        },
        "description": "\n\nOne deliberate exception to the generic-error rule: 404 and 403 here carry a specific message ('Comment not found', 'Not authorized to edit this comment'). Those are strings this app throws itself, never an underlying error, and clients route on them — so they stay verbatim while everything else is generic."
      }
    },
    "/api/comments/{commentId}/reactions": {
      "get": {
        "operationId": "get-comment-reactions",
        "summary": "Reactions on a comment",
        "description": "The complete reaction state for one comment.\n\nAccess is checked against the PAGE the comment belongs to, not the comment itself. A comment on a page the caller may not read answers 404 — the same response as a comment that does not exist, deliberately, so the endpoint cannot be used to probe which comment ids are real.",
        "tags": [
          "Comments"
        ],
        "parameters": [
          {
            "name": "commentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Numeric id of the comment, as a string."
          }
        ],
        "responses": {
          "200": {
            "description": "The complete reaction state after the call.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reactions"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such comment, or no access to its page. The two are indistinguishable by design."
          },
          "500": {
            "description": "Something went wrong. The body carries a generic message plus an errorId that correlates with the server log.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SafeError"
                }
              }
            }
          }
        }
      }
    },
    "/api/comments/{commentId}/reactions/{emoji}": {
      "post": {
        "operationId": "add-comment-reaction",
        "summary": "React to a comment",
        "description": "Adds the calling user's reaction and returns the complete new state.\n\nIdempotent: adding a reaction the user already has, or removing one they never had, succeeds and returns the unchanged state. Safe to retry, and safe to fire from an optimistic UI.\n\nAccess is checked against the PAGE the comment belongs to, not the comment itself. A comment on a page the caller may not read answers 404 — the same response as a comment that does not exist, deliberately, so the endpoint cannot be used to probe which comment ids are real.\n\nRate limited to 30 per minute per user.\n\nONE REACTION PER USER, ALWAYS. Adding a reaction silently WITHDRAWS the user's previous one — this is not a configurable mode, it is unconditional. A client that treats this as purely additive will show a stale count for the emoji that was just removed, which is why every reaction endpoint returns the complete state instead of a delta: replace your local state, never increment it.",
        "tags": [
          "Comments"
        ],
        "parameters": [
          {
            "name": "commentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Numeric id of the comment, as a string."
          },
          {
            "name": "emoji",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The emoji itself, URL-encoded. Stored verbatim as the reaction's message — there is no server-side allowlist, so what you send is what every reader sees."
          }
        ],
        "responses": {
          "200": {
            "description": "The complete reaction state after the call.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reactions"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such comment, or no access to its page. The two are indistinguishable by design."
          },
          "429": {
            "description": "Rate limit exceeded (30 per minute per user)."
          },
          "500": {
            "description": "Something went wrong. The body carries a generic message plus an errorId that correlates with the server log.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SafeError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "remove-comment-reaction",
        "summary": "Withdraw a reaction from a comment",
        "description": "Removes the calling user's reaction and returns the complete new state. Only ever affects the caller's own reaction.\n\nIdempotent: adding a reaction the user already has, or removing one they never had, succeeds and returns the unchanged state. Safe to retry, and safe to fire from an optimistic UI.\n\nAccess is checked against the PAGE the comment belongs to, not the comment itself. A comment on a page the caller may not read answers 404 — the same response as a comment that does not exist, deliberately, so the endpoint cannot be used to probe which comment ids are real.\n\nNOT rate limited, unlike its POST counterpart — withdrawing is always allowed.",
        "tags": [
          "Comments"
        ],
        "parameters": [
          {
            "name": "commentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Numeric id of the comment, as a string."
          },
          {
            "name": "emoji",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The emoji itself, URL-encoded. Stored verbatim as the reaction's message — there is no server-side allowlist, so what you send is what every reader sees."
          }
        ],
        "responses": {
          "200": {
            "description": "The complete reaction state after the call.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reactions"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such comment, or no access to its page. The two are indistinguishable by design."
          },
          "500": {
            "description": "Something went wrong. The body carries a generic message plus an errorId that correlates with the server log.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SafeError"
                }
              }
            }
          }
        }
      }
    },
    "/api/demo-data/clean-start": {
      "post": {
        "operationId": "demo-data-clean-start",
        "summary": "Delete all content for a language and start fresh",
        "description": "DESTRUCTIVE AND IRREVERSIBLE. Deletes every page, the navigation and the footer for one language, then creates a fresh homepage with a NEW uniqueId. Comments are deleted too.\n\nThere is no dry run, no confirmation parameter and no undo. The new homepage id differs from the old one, so any external deep link into the old homepage breaks.\n\nAdministrators only. Scoped to a single language: other languages are untouched.",
        "tags": [
          "Demo Data"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "language": {
                    "type": "string",
                    "default": "nl",
                    "description": "The language to wipe. Must be enabled."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Language wiped and a fresh homepage created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DemoDataOperationResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Administrator access required."
          },
          "500": {
            "description": "Failed, or refused (for example the language is not enabled). Read success and message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DemoDataOperationResult"
                }
              }
            }
          }
        }
      }
    },
    "/api/demo-data/import": {
      "post": {
        "operationId": "import-demo-data",
        "summary": "Install demo content for a language",
        "description": "Installs the bundled demo pages for one language. Administrators only.\n\nThe source is chosen automatically: bundled demo data if this build ships it for the language, otherwise a remote download. The two paths do not honour the same options — mode is applied only on the bundled path; a remote import always behaves as overwrite.\n\nAn unrecognised mode is silently coerced to 'overwrite' rather than rejected. Given that overwrite is the destructive one, a typo in this field costs content.",
        "tags": [
          "Demo Data"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "language": {
                    "type": "string",
                    "default": "nl",
                    "description": "Content language code. Must be enabled, or the call fails with success:false."
                  },
                  "mode": {
                    "type": "string",
                    "default": "overwrite",
                    "enum": [
                      "overwrite",
                      "skip_existing"
                    ],
                    "description": "overwrite deletes the language folder first. skip_existing leaves existing pages untouched. Applied on the bundled path only."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Imported",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DemoDataOperationResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Administrator access required."
          },
          "500": {
            "description": "Import failed, OR was refused for an ordinary reason such as the language not being enabled. Read success and message rather than the status code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DemoDataOperationResult"
                }
              }
            }
          }
        }
      }
    },
    "/api/demo-data/languages": {
      "get": {
        "operationId": "get-demo-data-languages",
        "summary": "Languages available for demo content",
        "description": "The enabled content languages. This is the same list as available_languages in GET /api/demo-data/status, without the per-language install state — prefer the status endpoint if you need both.\n\nReadable by any user with IntraVox access.",
        "tags": [
          "Demo Data"
        ],
        "responses": {
          "200": {
            "description": "Enabled languages",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "languages": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "languages"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "No IntraVox access."
          },
          "500": {
            "description": "Languages could not be read."
          }
        }
      }
    },
    "/api/demo-data/status": {
      "get": {
        "operationId": "get-demo-data-status",
        "summary": "Demo content status per language",
        "description": "Reports whether demo content is installed, for every enabled language.\n\nReadable by any user with IntraVox access — not just administrators — because the setup wizard shows this before an admin decides anything.",
        "tags": [
          "Demo Data"
        ],
        "responses": {
          "200": {
            "description": "Status per language",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DemoDataStatus"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "No IntraVox access."
          },
          "500": {
            "description": "Status could not be determined."
          }
        }
      }
    },
    "/api/export/language/{language}": {
      "get": {
        "operationId": "export-language",
        "summary": "Download a whole language as JSON",
        "description": "Returns every page in one language, plus its navigation and footer, as a JSON file download.\n\nThis is a DOWNLOAD, not a JSON API response: the body arrives with Content-Disposition and a generated filename (intravox-export-<language>-<date>.json). A client wanting the data rather than a file should read the body and ignore the disposition.\n\nThere is no pagination, no cap and no streaming — the whole language is built in memory and serialised at once. On a large intranet this is the heaviest endpoint in the API, and there is no way to ask for part of it.\n\nACCESS MODEL, stated exactly because 'export everything' deserves it. These endpoints are available to any logged-in user, not just administrators. The content is read through the caller's OWN mounted view of the IntraVox group folder, so group membership gates what can be exported and a user outside the group gets nothing.\n\nWhat is NOT separately re-checked is per-page advanced ACLs: the walk lists directories through that mounted view and relies on the mount to hide what the user may not see. There is also a legacy fallback that resolves the folder by raw storage path when no mounted view is available, and that fallback does not carry the same guarantees. Treat an export as 'everything this user's mount exposes', not as 'everything this user may read page by page'.",
        "tags": [
          "Export"
        ],
        "parameters": [
          {
            "name": "language",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "includeComments",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "1",
              "enum": [
                "0",
                "1"
              ]
            },
            "description": "Compared as the STRING '1' — send 1 or 0, not true/false. Anything other than '1' is treated as off, so a boolean true in JSON disables comments rather than enabling them."
          }
        ],
        "responses": {
          "200": {
            "description": "The export, as a file download. A language that does not exist yields an envelope with an empty pages array rather than a 404.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LanguageExport"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/export/language/{language}/zip": {
      "get": {
        "operationId": "export-language-zip",
        "summary": "Export language as ZIP",
        "tags": [
          "Export"
        ],
        "parameters": [
          {
            "name": "language",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ZIP file",
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/export/languages": {
      "get": {
        "operationId": "get-exportable-languages",
        "summary": "Get exportable languages",
        "tags": [
          "Export"
        ],
        "responses": {
          "200": {
            "description": "Exportable languages, as a BARE ARRAY — not wrapped in an object.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ExportableLanguage"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/export/page/{uniqueId}": {
      "get": {
        "operationId": "export-page",
        "summary": "Download one page as JSON",
        "description": "Returns a single page with its comments and reactions, as a JSON file download named intravox-page-<id>-<date>.json.\n\nThe page is looked up across EVERY enabled language, so the caller does not need to know which language it lives in — and a uniqueId is expected to be unique across languages for that reason.\n\nNote the response-type switch: success is a file download, failure is an ordinary JSON error body. A client must branch on the status code, not on the content type.\n\nACCESS MODEL, stated exactly because 'export everything' deserves it. These endpoints are available to any logged-in user, not just administrators. The content is read through the caller's OWN mounted view of the IntraVox group folder, so group membership gates what can be exported and a user outside the group gets nothing.\n\nWhat is NOT separately re-checked is per-page advanced ACLs: the walk lists directories through that mounted view and relies on the mount to hide what the user may not see. There is also a legacy fallback that resolves the folder by raw storage path when no mounted view is available, and that fallback does not carry the same guarantees. Treat an export as 'everything this user's mount exposes', not as 'everything this user may read page by page'.",
        "tags": [
          "Export"
        ],
        "parameters": [
          {
            "name": "uniqueId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "includeComments",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "1",
              "enum": [
                "0",
                "1"
              ]
            },
            "description": "Compared as the STRING '1' — send 1 or 0, not true/false. Anything other than '1' is treated as off, so a boolean true in JSON disables comments rather than enabling them."
          }
        ],
        "responses": {
          "200": {
            "description": "The page, as a file download.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageExport"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No page with this uniqueId in any enabled language — which also covers a page the caller's mount does not expose."
          }
        }
      }
    },
    "/api/feed/article": {
      "get": {
        "operationId": "get-feed-article",
        "summary": "Read one feed item's article body",
        "description": "Returns the article that came with the feed item, sanitized and cached server-side by the list fetch. Nothing is fetched from the source: a miss means the cache entry expired with its feed, or the item never carried a body.\n\nRate limited to 60 requests per minute per user. The limit guards enumeration rather than load — the response is served from cache.",
        "tags": [
          "Feeds"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/FeedSourceType"
          },
          {
            "$ref": "#/components/parameters/FeedUrl"
          },
          {
            "$ref": "#/components/parameters/FeedConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/FeedCourseId"
          },
          {
            "$ref": "#/components/parameters/FeedContentType"
          },
          {
            "$ref": "#/components/parameters/FeedJiraProject"
          },
          {
            "$ref": "#/components/parameters/FeedMoodleForumId"
          },
          {
            "$ref": "#/components/parameters/FeedListId"
          },
          {
            "$ref": "#/components/parameters/FeedSortBy"
          },
          {
            "$ref": "#/components/parameters/FeedSortOrder"
          },
          {
            "$ref": "#/components/parameters/FeedFilterKeyword"
          },
          {
            "name": "itemId",
            "in": "query",
            "required": true,
            "description": "The item's id as returned in the feed list.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The sanitized article body.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "content": {
                      "type": "string",
                      "nullable": true,
                      "description": "Sanitized HTML, or null when nothing is stored."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Not logged in."
          },
          "404": {
            "description": "No article stored for this item. The entry expires with the feed it came from; clients link out instead."
          },
          "429": {
            "description": "Rate limit exceeded."
          }
        }
      }
    },
    "/api/feed/batch": {
      "post": {
        "operationId": "get-feed-batch",
        "summary": "Fetch several feeds in one request",
        "description": "A page carries one feed widget per block and each used to fetch on its own, so a page cost one round trip per widget and counted that often against the rate limit. Each entry is validated exactly as a single request is.\n\nAt most 20 feeds per request. Rate limited to 30 requests per minute per user.",
        "tags": [
          "Feeds"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "feeds"
                ],
                "properties": {
                  "feeds": {
                    "type": "object",
                    "maxProperties": 20,
                    "description": "Feed specifications keyed by a caller-chosen slot id. Each value takes the same selectors a single fetch does (sourceType, url or connectionId, plus the source-specific filters), with limit, sortBy, sortOrder and filterKeyword.",
                    "additionalProperties": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One result per slot, keyed as sent. A feed that failed carries its own error and does not fail the others.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "feeds": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing feeds, or more than 20."
          },
          "401": {
            "description": "Not logged in."
          },
          "429": {
            "description": "Rate limit exceeded."
          }
        }
      }
    },
    "/api/feed/config": {
      "put": {
        "operationId": "update-feed-config",
        "summary": "Update feed configuration",
        "description": "Updates feed scope and item limit without changing the token.",
        "tags": [
          "RSS Feed"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scope": {
                    "type": "string",
                    "enum": [
                      "all",
                      "language"
                    ]
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Configuration updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "config": {
                      "type": "object",
                      "properties": {
                        "scope": {
                          "type": "string"
                        },
                        "limit": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/feed/courses/{connectionId}": {
      "get": {
        "operationId": "get-feed-courses",
        "summary": "List courses available through a connection",
        "description": "Lists the courses the CURRENT USER can see through an LMS connection (Moodle, Canvas or Brightspace), resolved with that user's own stored token. Two users therefore get different lists from the same connection.\n\nNote the failure convention: this endpoint answers 200 with an empty list when the connection is missing, the token is absent or the upstream call fails. It never distinguishes those cases, because doing so would let any logged-in user probe which connections exist and whether their credentials still work.",
        "tags": [
          "Feeds"
        ],
        "parameters": [
          {
            "name": "connectionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Available entries, or an empty list. Always 200.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "courses": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NamedRef"
                      }
                    }
                  },
                  "required": [
                    "courses"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/feed/external": {
      "get": {
        "operationId": "get-external-feed",
        "summary": "Fetch items from an external feed or connection",
        "description": "Fetches and normalises a feed. Which parameters matter depends on sourceType: 'rss' reads url, everything else reads connectionId plus the source-specific filters.\n\nRate limited to 30 requests per minute per user, because each call makes an outbound HTTP request on the server's behalf.\n\nFailure is soft: a source that is unreachable, malformed or refuses the stored credentials returns 500 with an empty items array and a generic error string. The specific cause is logged server-side, never returned — it would disclose internal hostnames and credential state.",
        "tags": [
          "Feeds"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/FeedSourceType"
          },
          {
            "$ref": "#/components/parameters/FeedUrl"
          },
          {
            "$ref": "#/components/parameters/FeedConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/FeedCourseId"
          },
          {
            "$ref": "#/components/parameters/FeedContentType"
          },
          {
            "$ref": "#/components/parameters/FeedJiraProject"
          },
          {
            "$ref": "#/components/parameters/FeedMoodleForumId"
          },
          {
            "$ref": "#/components/parameters/FeedListId"
          },
          {
            "$ref": "#/components/parameters/FeedSortBy"
          },
          {
            "$ref": "#/components/parameters/FeedSortOrder"
          },
          {
            "$ref": "#/components/parameters/FeedFilterKeyword"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 5,
              "minimum": 1,
              "maximum": 50
            },
            "description": "Clamped into 1..50; the result is capped at 50 regardless."
          }
        ],
        "responses": {
          "200": {
            "description": "Normalised feed items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Rate limit exceeded (30 per minute per user)."
          },
          "500": {
            "description": "Fetch failed. Body carries a generic error string and an empty items array.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedResult"
                }
              }
            }
          }
        }
      }
    },
    "/api/feed/image": {
      "get": {
        "operationId": "proxy-feed-image",
        "summary": "Serve a signed external image",
        "description": "Serves an external image through the server so the page CSP does not have to allow third-party hosts.\n\nThis is NOT an open proxy. Both url and sig are required, and sig must be the HMAC this backend produced when it rewrote the image URL into a feed result. An unsigned or mis-signed URL is refused with 403 before any outbound request is made. Clients therefore never construct this URL themselves — they use the value already present in FeedItem.image.\n\nResponses are served inline with a one-day immutable cache, nosniff, no referrer and a default-src 'none' CSP.",
        "tags": [
          "Feeds"
        ],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "The image URL, exactly as it appeared in the signed link."
          },
          {
            "name": "sig",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "HMAC produced by this backend. Bound to the url; not transferable."
          }
        ],
        "responses": {
          "200": {
            "description": "The image, served inline.",
            "content": {
              "image/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "url or sig missing."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Signature absent or invalid — the URL was not signed by this backend."
          },
          "502": {
            "description": "The upstream host could not be reached or returned something unusable."
          }
        }
      }
    },
    "/api/feed/jira-projects/{connectionId}": {
      "get": {
        "operationId": "get-feed-jira-projects",
        "summary": "List Jira projects available through a connection",
        "description": "Lists projects on the Jira instance behind a connection, sorted by name.\n\nNote the shape difference from the other pickers: a Jira project is identified by its KEY, not an id, so entries are {key, name} rather than {id, name}.\n\nAs with the other pickers, any failure answers 200 with an empty list.",
        "tags": [
          "Feeds"
        ],
        "parameters": [
          {
            "name": "connectionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Available projects, or an empty list. Always 200.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "projects": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string",
                            "description": "Jira project key, e.g. INTRA."
                          },
                          "name": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "key",
                          "name"
                        ]
                      }
                    }
                  },
                  "required": [
                    "projects"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/feed/moodle-forums/{connectionId}": {
      "get": {
        "operationId": "get-feed-moodle-forums",
        "summary": "List forums in a Moodle course",
        "description": "Lists the discussion forums in one Moodle course. A courseId that is missing or malformed yields an empty list rather than an error.\n\nNote the failure convention: this endpoint answers 200 with an empty list when the connection is missing, the token is absent or the upstream call fails. It never distinguishes those cases, because doing so would let any logged-in user probe which connections exist and whether their credentials still work.",
        "tags": [
          "Feeds"
        ],
        "parameters": [
          {
            "name": "connectionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "courseId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]{1,64}$"
            },
            "description": "Required in practice: absent or malformed returns an empty list."
          }
        ],
        "responses": {
          "200": {
            "description": "Available entries, or an empty list. Always 200.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "forums": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NamedRef"
                      }
                    }
                  },
                  "required": [
                    "forums"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/feed/preview": {
      "get": {
        "operationId": "get-feed-preview",
        "summary": "Fetch a three-item preview while editing a widget",
        "description": "Identical to GET /api/feed/external but hard-limited to three items and with no limit parameter. Intended for the widget editor, so an author can confirm a source works before saving.\n\nUnlike the other feed reads this route requires a CSRF token: it is only ever called from the editor, and every in-app caller sends one already. A failed fetch returns 400 (not 500) with an empty items array.",
        "tags": [
          "Feeds"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/FeedSourceType"
          },
          {
            "$ref": "#/components/parameters/FeedUrl"
          },
          {
            "$ref": "#/components/parameters/FeedConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/FeedCourseId"
          },
          {
            "$ref": "#/components/parameters/FeedContentType"
          },
          {
            "$ref": "#/components/parameters/FeedJiraProject"
          },
          {
            "$ref": "#/components/parameters/FeedMoodleForumId"
          },
          {
            "$ref": "#/components/parameters/FeedListId"
          },
          {
            "$ref": "#/components/parameters/FeedSortBy"
          },
          {
            "$ref": "#/components/parameters/FeedSortOrder"
          },
          {
            "$ref": "#/components/parameters/FeedFilterKeyword"
          }
        ],
        "responses": {
          "200": {
            "description": "Up to three normalised items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedResult"
                }
              }
            }
          },
          "400": {
            "description": "The source could not be fetched. Empty items array with a generic error string.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Rate limit exceeded (30 per minute per user)."
          }
        }
      }
    },
    "/api/feed/sharepoint-lists/{connectionId}": {
      "get": {
        "operationId": "get-feed-sharepoint-lists",
        "summary": "List SharePoint lists and document libraries",
        "description": "Enumerates the visible lists on the SharePoint site behind a connection, split by kind: document libraries are returned separately from ordinary lists, because the widget offers different content types for each. Hidden lists are omitted.\n\nFailure answers 200 with both arrays empty and a generic error string.",
        "tags": [
          "Feeds"
        ],
        "parameters": [
          {
            "name": "connectionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lists and libraries, or both empty. Always 200.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "libraries": {
                      "type": "array",
                      "description": "Lists whose template is documentLibrary.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "template": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "id",
                          "name"
                        ]
                      }
                    },
                    "lists": {
                      "type": "array",
                      "description": "Every other visible list.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "template": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "id",
                          "name"
                        ]
                      }
                    },
                    "error": {
                      "type": "string",
                      "description": "Present only on failure."
                    }
                  },
                  "required": [
                    "libraries",
                    "lists"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/feed/token": {
      "get": {
        "operationId": "get-feed-token",
        "summary": "Get current user's feed token",
        "description": "Returns the user's feed token information including the feed URL, configuration, and last accessed timestamp.",
        "tags": [
          "RSS Feed"
        ],
        "responses": {
          "200": {
            "description": "Feed token info",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "hasToken": {
                      "type": "boolean"
                    },
                    "linkSharingDisabled": {
                      "type": "boolean"
                    },
                    "feedUrl": {
                      "type": "string"
                    },
                    "last_accessed": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "config": {
                      "type": "object",
                      "properties": {
                        "scope": {
                          "type": "string",
                          "enum": [
                            "all",
                            "language"
                          ]
                        },
                        "limit": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 50
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "operationId": "regenerate-feed-token",
        "summary": "Generate or regenerate feed token",
        "description": "Creates a new feed token (or replaces the existing one). The old feed URL stops working immediately.",
        "tags": [
          "RSS Feed"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scope": {
                    "type": "string",
                    "enum": [
                      "all",
                      "language"
                    ],
                    "default": "language"
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50,
                    "default": 20
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "New feed token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "feedUrl": {
                      "type": "string"
                    },
                    "config": {
                      "type": "object",
                      "properties": {
                        "scope": {
                          "type": "string"
                        },
                        "limit": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Link sharing is disabled by the administrator"
          }
        }
      },
      "delete": {
        "operationId": "revoke-feed-token",
        "summary": "Revoke feed token",
        "description": "Deletes the user's feed token. The feed URL becomes invalid immediately.",
        "tags": [
          "RSS Feed"
        ],
        "responses": {
          "200": {
            "description": "Token revoked; hasToken is now false.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedTokenState"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/file-story/capabilities": {
      "get": {
        "summary": "Server-side capabilities for the File Story widget (incl. federated-share detection)",
        "parameters": [
          {
            "name": "folder",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "When provided, response includes sourceIsFederated + sourceFederatedInfo"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "What the server can do for this source.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoryCapabilitiesResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Unable to load capabilities"
          }
        },
        "operationId": "file-story-capabilities",
        "tags": [
          "File Story"
        ]
      }
    },
    "/api/file-story/files": {
      "get": {
        "summary": "List documents in a folder (paged, mode-aware)",
        "description": "Mirrors the Photo Story photos endpoint but constrained to document mimetypes. Supports timeline/list/tiles/grouped modes and federated-share-aware MetaVox handling.",
        "parameters": [
          {
            "name": "folder",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mode",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "timeline",
                "tiles",
                "list",
                "grouped"
              ]
            }
          },
          {
            "name": "filters",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "JSON-encoded filter array (max 16 KB)"
            }
          },
          {
            "name": "groupBy",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "granularity",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "day",
                "month",
                "year"
              ]
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            }
          },
          {
            "name": "sortOrder",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          },
          {
            "name": "sortBy",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of documents, with the mode-specific extras.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileStoryListing"
                }
              }
            }
          },
          "304": {
            "description": "Not Modified"
          },
          "400": {
            "description": "Invalid mode / filter payload too large / folder required"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Folder not found for this user"
          },
          "500": {
            "description": "Unable to load files"
          }
        },
        "operationId": "list-story-files",
        "tags": [
          "File Story"
        ]
      }
    },
    "/api/file-story/metavox-fields": {
      "get": {
        "summary": "MetaVox field discovery for File Story filter-builder / sort / group-by",
        "responses": {
          "200": {
            "description": "MetaVox fields, or an empty list when MetaVox is absent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetaVoxFieldList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "operationId": "file-story-metavox-fields",
        "tags": [
          "File Story"
        ]
      }
    },
    "/api/footer": {
      "get": {
        "operationId": "get-footer",
        "summary": "Get footer",
        "description": "Returns the footer configuration",
        "tags": [
          "Navigation"
        ],
        "responses": {
          "200": {
            "description": "Footer data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Footer"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "operationId": "save-footer",
        "summary": "Save footer",
        "description": "Saves the footer configuration",
        "tags": [
          "Navigation"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Footer"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The stored footer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Footer"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "health",
        "summary": "Liveness probe",
        "description": "Confirms the app is installed and responding, and reports its version. The only unauthenticated JSON endpoint in the API that is not gated by a share token.\n\nAPP MOUNT ONLY. This route is not in the OCS block, so /ocs/v2.php/apps/intravox/api/health returns 404 with an OCS error envelope. Probe https://{host}/apps/intravox/api/health instead.\n\nDeliberately minimal: it reports nothing about the database, the group folder or configuration, so it cannot be used to fingerprint an instance beyond the app version. Rate limited to 60 per minute per client.",
        "tags": [
          "Settings"
        ],
        "security": [
          {}
        ],
        "responses": {
          "200": {
            "description": "The app is responding.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    },
                    "app": {
                      "type": "string",
                      "enum": [
                        "intravox"
                      ]
                    },
                    "version": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "status",
                    "app",
                    "version"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (60 per minute per client)."
          }
        }
      }
    },
    "/api/homepage": {
      "post": {
        "operationId": "set-homepage",
        "summary": "Promote a page to homepage",
        "description": "Makes an existing page the homepage of its language. Requires write permission on the page, not administrator rights.\n\nScoped to one language: each language has its own homepage and this never touches the others.",
        "tags": [
          "Pages"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pageUniqueId": {
                    "type": "string",
                    "description": "Unique id of the page to promote. Required and non-empty."
                  }
                },
                "required": [
                  "pageUniqueId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Promoted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessAck"
                }
              }
            }
          },
          "400": {
            "description": "pageUniqueId missing, or the page cannot be a homepage."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "No write permission on that page."
          },
          "500": {
            "description": "The homepage could not be set."
          }
        }
      }
    },
    "/api/import/confluence/html": {
      "post": {
        "operationId": "import-confluence-html",
        "summary": "Import a Confluence HTML export",
        "description": "Converts a Confluence HTML space export into IntraVox pages, preserving the page hierarchy. Administrators only.\n\nUnlike the ZIP import this one always imports comments and NEVER overwrites — there are no flags for either. Re-running it on the same export therefore skips what already exists.\n\nparentPageId grafts the whole imported tree under an existing page, which is how you import several spaces without them colliding at the root.\n\nThe upload is checked three ways before anything is read: the MIME type must be a ZIP type, the first two bytes must be PK, and the archive is expanded through a guarded extractor rather than a plain unzip. A file that merely ends in .zip does not get through.\n\nTHREE DISTINCT FAILURE SHAPES, and a migration tool should treat them differently:\n- 400 with errorCode and params: the archive was rejected during validation. These messages are safe to show a user verbatim — they describe the upload, never internal paths. errorCode is stable and translatable; error is an English fallback for scripts.\n- 500 with errorId: something went wrong inside. The message is deliberately generic; the errorId correlates with the server log, so quote it in a bug report rather than the message.\n- 403: not an administrator.",
        "tags": [
          "Export"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The Confluence HTML export ZIP. Field name must be 'file'."
                  },
                  "language": {
                    "type": "string",
                    "default": "nl",
                    "description": "Target content language."
                  },
                  "parentPageId": {
                    "type": "string",
                    "description": "Optional. Import the tree under this page instead of at the language root."
                  }
                },
                "required": [
                  "file"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Imported",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "stats": {
                      "$ref": "#/components/schemas/ImportStats"
                    },
                    "pages": {
                      "type": "integer",
                      "description": "Pages found in the export — not necessarily the number imported. Compare with stats.pagesImported."
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "success",
                    "stats"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Rejected during validation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "errorCode": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Administrator access required."
          },
          "500": {
            "description": "Import failed internally."
          }
        }
      }
    },
    "/api/import/zip": {
      "post": {
        "operationId": "import-zip",
        "summary": "Import an IntraVox export archive",
        "description": "Restores pages, media, comments, navigation and footer from an archive produced by the export endpoints. Administrators only.\n\nThis is the ingest path a migration uses. Note what it does NOT have: no dryRun, no idempotency key, and no resume. Re-running it is governed entirely by the overwrite flag — off, existing pages are skipped and counted; on, they are replaced. A partial import leaves what it managed to write.\n\nThe upload is checked three ways before anything is read: the MIME type must be a ZIP type, the first two bytes must be PK, and the archive is expanded through a guarded extractor rather than a plain unzip. A file that merely ends in .zip does not get through.\n\nTHREE DISTINCT FAILURE SHAPES, and a migration tool should treat them differently:\n- 400 with errorCode and params: the archive was rejected during validation. These messages are safe to show a user verbatim — they describe the upload, never internal paths. errorCode is stable and translatable; error is an English fallback for scripts.\n- 500 with errorId: something went wrong inside. The message is deliberately generic; the errorId correlates with the server log, so quote it in a bug report rather than the message.\n- 403: not an administrator.",
        "tags": [
          "Export"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The ZIP archive. Field name must be 'file'."
                  },
                  "importComments": {
                    "type": "string",
                    "default": "1",
                    "enum": [
                      "0",
                      "1"
                    ],
                    "description": "Compared as the STRING '1'. A JSON boolean will not work — this is a multipart form."
                  },
                  "overwrite": {
                    "type": "string",
                    "default": "0",
                    "enum": [
                      "0",
                      "1"
                    ],
                    "description": "Off by default: existing pages are SKIPPED, not replaced. Turn on only when replacing is intended."
                  },
                  "autoCreateMetaVoxFields": {
                    "type": "string",
                    "default": "0",
                    "enum": [
                      "0",
                      "1"
                    ],
                    "description": "Create MetaVox field definitions the archive references but the instance lacks."
                  }
                },
                "required": [
                  "file"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Imported. Read stats to see what actually happened — a run that skipped everything also lands here.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "stats": {
                      "$ref": "#/components/schemas/ImportStats"
                    }
                  },
                  "required": [
                    "success",
                    "stats"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The archive was rejected during validation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "English fallback, safe to display."
                    },
                    "errorCode": {
                      "type": "string",
                      "description": "Stable code for translation."
                    },
                    "params": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "Substitution values for the translated message."
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Administrator access required."
          },
          "500": {
            "description": "Import failed internally.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Generic by design."
                    },
                    "errorId": {
                      "type": "string",
                      "description": "Correlates with the server log. Quote this, not the message."
                    }
                  },
                  "required": [
                    "error",
                    "errorId"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/languages": {
      "get": {
        "operationId": "list-languages",
        "summary": "Enabled and available languages",
        "tags": [
          "Languages"
        ],
        "description": "Admin only. Nextcloud enforces this by default for any controller method without #[NoAdminRequired], which this controller deliberately relies on rather than checking in the body.",
        "responses": {
          "200": {
            "description": "The language sets.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LanguageList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/languages/content-status": {
      "get": {
        "operationId": "get-language-content-status",
        "summary": "Which languages have content",
        "tags": [
          "Languages"
        ],
        "description": "The one endpoint here that any logged-in user may call: the editor needs it to decide whether to offer a language switch.",
        "responses": {
          "200": {
            "description": "Per language, whether content exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LanguageContentStatus"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/languages/enabled": {
      "post": {
        "operationId": "set-enabled-languages",
        "summary": "Replace the enabled set",
        "tags": [
          "Languages"
        ],
        "description": "Admin only. Nextcloud enforces this by default for any controller method without #[NoAdminRequired], which this controller deliberately relies on rather than checking in the body. Enabling a language also creates its homepage; a failure there is reported per language rather than failing the whole call.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "codes"
                ],
                "properties": {
                  "codes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The enabled set, plus per-language homepage results.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LanguageEnableResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/languages/primary": {
      "post": {
        "operationId": "set-primary-language",
        "summary": "Set the primary language",
        "tags": [
          "Languages"
        ],
        "description": "Admin only. Nextcloud enforces this by default for any controller method without #[NoAdminRequired], which this controller deliberately relies on rather than checking in the body.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The primary language as stored.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "primaryLanguage": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/languages/{code}": {
      "delete": {
        "operationId": "remove-language",
        "summary": "Disable one language",
        "tags": [
          "Languages"
        ],
        "description": "Admin only. Nextcloud enforces this by default for any controller method without #[NoAdminRequired], which this controller deliberately relies on rather than checking in the body. Disabling does not delete the pages in that language.",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "Language code, e.g. \"nl\".",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Disabled.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/languages/{code}/add": {
      "post": {
        "operationId": "add-language",
        "summary": "Enable one language",
        "tags": [
          "Languages"
        ],
        "description": "Admin only. Nextcloud enforces this by default for any controller method without #[NoAdminRequired], which this controller deliberately relies on rather than checking in the body.",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "Language code, e.g. \"nl\".",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Enabled.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/languages/{code}/empty-homepage": {
      "post": {
        "operationId": "create-language-homepage",
        "summary": "Create an empty homepage for a language",
        "tags": [
          "Languages"
        ],
        "description": "Admin only. Nextcloud enforces this by default for any controller method without #[NoAdminRequired], which this controller deliberately relies on rather than checking in the body. Idempotent: a language that already has a homepage is left alone.",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "Language code, e.g. \"nl\".",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Created, or already present.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/license/instance": {
      "get": {
        "operationId": "get-instance-info",
        "summary": "How this instance identifies itself",
        "tags": [
          "Licensing"
        ],
        "description": "Admin only. The instance is identified to the licence server by a hash, never by its URL in the clear.",
        "responses": {
          "200": {
            "description": "Instance identification.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/license/stats": {
      "get": {
        "operationId": "get-license-stats",
        "summary": "Subscription state and page usage",
        "tags": [
          "Licensing"
        ],
        "description": "Admin only. Reads the cached verdict; it never blocks on the licence server.",
        "responses": {
          "200": {
            "description": "Subscription state and usage.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LicenseStats"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/license/telemetry": {
      "post": {
        "operationId": "send-telemetry",
        "summary": "Send telemetry now",
        "tags": [
          "Licensing"
        ],
        "description": "Admin only. Answers success:false with a reason when telemetry is switched off, rather than failing.",
        "responses": {
          "200": {
            "description": "Sent, or declined with a reason.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    },
                    "reason": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/license/update-usage": {
      "post": {
        "operationId": "update-license-usage",
        "summary": "Report usage to the licence server",
        "tags": [
          "Licensing"
        ],
        "description": "Admin only. Normally driven by a daily background job; this endpoint exists so an admin can force a report.",
        "responses": {
          "200": {
            "description": "The report result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/license/validate": {
      "post": {
        "operationId": "validate-license",
        "summary": "Check the key against the licence server",
        "tags": [
          "Licensing"
        ],
        "description": "Admin only. Contacts the licence server and caches the verdict, which is what the stats endpoint then reads.",
        "responses": {
          "200": {
            "description": "The verdict, valid or refused with a reason.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LicenseValidation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/lms/connect/{connectionId}": {
      "post": {
        "operationId": "start-lms-oauth",
        "summary": "Begin an OAuth2 link for a connection",
        "description": "Returns the authorisation URL the browser must be sent to. This endpoint does NOT redirect — it hands back a URL and the caller navigates or opens a popup.\n\nThe URL carries a signed state parameter: an HMAC over the connection id, the user id, a timestamp and a 16-character nonce, valid for 10 minutes and accepted once. That binding is what stops an authorisation code from being replayed or attached to a different user, so the URL must be used as given — altering the state invalidates it.\n\nThe flow completes at GET /api/lms/callback, which is a browser redirect target rather than an API endpoint: it returns an HTML page that postMessages the opener and is therefore not documented here.\n\nOnly for connections whose authMode is not 'token'; a token-mode connection returns 400 and should use POST /api/lms/token/{connectionId} instead.",
        "tags": [
          "LMS"
        ],
        "parameters": [
          {
            "name": "connectionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Authorisation URL to send the browser to.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "authUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Use verbatim; the state parameter is signed."
                    }
                  },
                  "required": [
                    "authUrl"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The connection uses authMode 'token' and has no OAuth2 flow, or its client id and secret are not configured."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such connection."
          },
          "500": {
            "description": "The flow could not be started."
          }
        }
      }
    },
    "/api/lms/connections": {
      "get": {
        "operationId": "get-lms-user-connections",
        "summary": "LMS connections and this user's link status",
        "description": "Lists the configured LMS connections together with whether the CALLING USER has linked their own account to each one. Per-user, not global.\n\nNo credentials are returned — only the 'connected' flag, the token type and when it was linked.",
        "tags": [
          "LMS"
        ],
        "responses": {
          "200": {
            "description": "Connections with per-user status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connections": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/LmsUserConnection"
                      }
                    }
                  },
                  "required": [
                    "connections"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Connections could not be read."
          }
        }
      }
    },
    "/api/lms/token/{connectionId}": {
      "post": {
        "operationId": "save-lms-manual-token",
        "summary": "Store a manually issued API token",
        "description": "Stores an API token the user obtained from the LMS themselves — a Moodle web-service token, for example. The alternative to the OAuth2 flow, for connections whose authMode is 'token'.\n\nThe token is VALIDATED BEFORE IT IS STORED by making a live test call against the LMS. A token that does not work, or lacks the required permissions, is rejected with 400 and nothing is saved — so a success here means the token actually functioned at least once.\n\nThe token is stored per user and is never returned by any endpoint afterwards; GET /api/lms/connections only reports that one exists.",
        "tags": [
          "LMS"
        ],
        "parameters": [
          {
            "name": "connectionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "The API token. Write-only; never echoed back."
                  }
                },
                "required": [
                  "token"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token validated and stored.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusOk"
                }
              }
            }
          },
          "400": {
            "description": "Token missing, or the live validation call failed."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such connection."
          },
          "500": {
            "description": "The token could not be stored."
          }
        }
      },
      "delete": {
        "operationId": "disconnect-lms",
        "summary": "Remove this user's token for a connection",
        "description": "Deletes the calling user's stored token. Affects only that user — the connection itself stays configured and other users keep their links.\n\nConvergent: disconnecting a connection the user was never linked to succeeds rather than erroring, so a retry is safe.",
        "tags": [
          "LMS"
        ],
        "parameters": [
          {
            "name": "connectionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Disconnected, or was already not connected.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusOk"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "The token could not be removed."
          }
        }
      }
    },
    "/api/metavox/fields": {
      "get": {
        "operationId": "get-metavox-fields",
        "summary": "MetaVox field definitions for the IntraVox folder",
        "description": "The custom metadata fields MetaVox defines for the IntraVox group folder.\n\nALWAYS 200, even when it cannot answer. MetaVox not installed, not enabled for this user, or no IntraVox group folder each yield an empty fields array plus an error string — the integration is optional, so a missing dependency must not break the page. Check whether fields is empty, not the status code.",
        "tags": [
          "Pages"
        ],
        "responses": {
          "200": {
            "description": "Field definitions, or an empty list with an explanation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "fields": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field_name": {
                            "type": "string"
                          },
                          "field_label": {
                            "type": "string"
                          },
                          "field_type": {
                            "type": "string"
                          },
                          "options": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    },
                    "groupfolderId": {
                      "type": "integer",
                      "description": "Present only on success."
                    },
                    "error": {
                      "type": "string",
                      "description": "Present when MetaVox is unavailable or the folder was not found."
                    }
                  },
                  "required": [
                    "fields"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/metavox/status": {
      "get": {
        "operationId": "get-metavox-status",
        "summary": "Get MetaVox status",
        "description": "Check if MetaVox app is installed and enabled",
        "tags": [
          "Settings"
        ],
        "responses": {
          "200": {
            "description": "MetaVox status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "installed": {
                      "type": "boolean"
                    },
                    "enabled": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/navigation": {
      "get": {
        "operationId": "get-navigation",
        "summary": "Get navigation",
        "description": "Returns the navigation structure",
        "tags": [
          "Navigation"
        ],
        "responses": {
          "200": {
            "description": "Navigation data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Navigation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "operationId": "save-navigation",
        "summary": "Save navigation",
        "description": "Saves the navigation structure",
        "tags": [
          "Navigation"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Navigation"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The stored navigation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "navigation"
                  ],
                  "properties": {
                    "navigation": {
                      "$ref": "#/components/schemas/Navigation"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/news": {
      "get": {
        "operationId": "get-news",
        "summary": "Get news items",
        "description": "Returns news items for the News widget with optional filtering",
        "tags": [
          "News"
        ],
        "parameters": [
          {
            "name": "sourcePath",
            "in": "query",
            "description": "Source folder path (relative to language folder)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "filters",
            "in": "query",
            "description": "JSON array of MetaVox filters",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "filterOperator",
            "in": "query",
            "description": "How to combine filters",
            "schema": {
              "type": "string",
              "enum": [
                "AND",
                "OR"
              ],
              "default": "AND"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of items to return",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 5
            }
          },
          {
            "name": "sortBy",
            "in": "query",
            "description": "Field to sort by",
            "schema": {
              "type": "string",
              "enum": [
                "modified",
                "title"
              ],
              "default": "modified"
            }
          },
          {
            "name": "sortOrder",
            "in": "query",
            "description": "Sort direction",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            }
          },
          {
            "name": "sourcePageId",
            "in": "query",
            "required": false,
            "description": "uniqueId of the page whose subtree supplies the news items. Takes precedence over sourcePath.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "filterPublished",
            "in": "query",
            "required": false,
            "description": "When \"true\", only published items are returned regardless of the caller's write permission.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "News items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NewsItem"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "metavoxAvailable": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/orphaned/scan": {
      "get": {
        "operationId": "scan-orphaned-data",
        "summary": "Find orphaned GroupFolder directories",
        "description": "Compares the directories physically present under __groupfolders/ against the GroupFolders registered in the database, and reports the ones with no owner.\n\nThis walks the data directory and sizes each candidate, so it is proportional to what is on disk rather than to the number of orphans found.\n\nAdministrators only, and deliberately so: these endpoints read and write the raw data directory outside any GroupFolder permission model.",
        "tags": [
          "Orphaned Data"
        ],
        "responses": {
          "200": {
            "description": "Orphans found (possibly none).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "folders": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OrphanedFolder"
                      }
                    },
                    "count": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "success",
                    "folders",
                    "count"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Administrator access required."
          },
          "500": {
            "description": "Scan failed."
          }
        }
      }
    },
    "/api/orphaned/{id}": {
      "delete": {
        "operationId": "cleanup-orphaned-folder",
        "summary": "Delete an orphaned folder and everything in it",
        "description": "DESTRUCTIVE AND IRREVERSIBLE. Recursively deletes the directory and its contents from disk. There is no trash, no dry run and no undo.\n\nThe one safety net is that the service re-checks the folder is genuinely orphaned before deleting; a registered folder is refused with success:false rather than removed. Inspect with GET /api/orphaned/{id}/details first — that is the only way to see what you are about to destroy.\n\nAdministrators only, and deliberately so: these endpoints read and write the raw data directory outside any GroupFolder permission model.",
        "tags": [
          "Orphaned Data"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    },
                    "deletedItems": {
                      "type": "integer"
                    },
                    "freedSpace": {
                      "type": "integer",
                      "description": "Bytes."
                    },
                    "freedSpaceFormatted": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "success",
                    "message"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "id must be a positive integer."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Administrator access required."
          },
          "500": {
            "description": "Deletion failed, or was refused because the folder is not orphaned. Read success and message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "success"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/orphaned/{id}/details": {
      "get": {
        "operationId": "get-orphaned-details",
        "summary": "Inspect one orphaned folder",
        "description": "Everything the scan returns for this folder, plus a per-language breakdown in languageDetails.\n\n404 means the id is not orphaned — which includes the case of a folder that is perfectly healthy and still registered. It is a refusal to operate on live data, not only a 'not found'.\n\nAdministrators only, and deliberately so: these endpoints read and write the raw data directory outside any GroupFolder permission model.",
        "tags": [
          "Orphaned Data"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Folder details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "folder": {
                      "$ref": "#/components/schemas/OrphanedFolder"
                    }
                  },
                  "required": [
                    "success",
                    "folder"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "id must be a positive integer."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Administrator access required."
          },
          "404": {
            "description": "Not orphaned, or not accessible. A registered, in-use folder also lands here."
          },
          "500": {
            "description": "Lookup failed."
          }
        }
      }
    },
    "/api/orphaned/{id}/migrate": {
      "post": {
        "operationId": "migrate-orphaned-folder",
        "summary": "Copy content out of an orphaned folder into the live one",
        "description": "Copies one language's content from an orphaned folder into the active IntraVox GroupFolder. The source is left in place, so this is a recovery step rather than a move — run the cleanup endpoint afterwards if you want the orphan gone.\n\nAccepts any language this site treats as IntraVox content: the discovered translations, whatever an administrator has enabled, and the legacy nl/en/de/fr defaults. A language folder from a language that was later disabled stays recoverable, which is the point — otherwise content would be stranded on disk by a setting changed after the fact.\n\nsuccess:false with errors > 0 means a partial copy: some files landed, some did not. Nothing is rolled back.\n\nAdministrators only, and deliberately so: these endpoints read and write the raw data directory outside any GroupFolder permission model.",
        "tags": [
          "Orphaned Data"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "The orphaned source folder."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "language": {
                    "type": "string",
                    "default": "nl",
                    "description": "Which language folder to copy. Must be one this site recognises as IntraVox content — the enabled and discovered languages plus the nl/en/de/fr legacy set. Anything else is a 400."
                  },
                  "mode": {
                    "type": "string",
                    "default": "merge",
                    "enum": [
                      "merge",
                      "replace"
                    ],
                    "description": "merge skips files that already exist in the target. replace overwrites them."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Copied",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    },
                    "migratedFiles": {
                      "type": "integer"
                    },
                    "skippedExisting": {
                      "type": "integer"
                    },
                    "errors": {
                      "type": "integer",
                      "description": "success is true only when this is 0."
                    }
                  },
                  "required": [
                    "success",
                    "message"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid id, a language this site does not recognise, or invalid mode."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Administrator access required."
          },
          "500": {
            "description": "Migration failed or completed with errors. Read success, errors and message.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    },
                    "errors": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "success"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/page/{pageId}/cache-status": {
      "get": {
        "operationId": "get-page-cache-status",
        "summary": "Whether a page is indexed in the Files cache yet",
        "description": "Reports whether a page's file has been picked up by the Nextcloud file cache.\n\nThis exists for one situation: immediately after creating a page, the file is on disk but may not yet be indexed, so it does not appear in the Files app. Poll this rather than concluding the create failed.",
        "tags": [
          "Pages"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Index status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "visible": {
                      "type": "boolean",
                      "description": "Whether the page is visible in the Files app."
                    },
                    "inCache": {
                      "type": "boolean",
                      "description": "Same signal; both reflect the presence of a filecache entry."
                    },
                    "fileId": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "path": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string",
                      "description": "Human explanation, e.g. 'Page created but waiting for indexing'."
                    }
                  },
                  "required": [
                    "visible",
                    "inCache"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Status could not be determined."
          }
        }
      }
    },
    "/api/pages": {
      "get": {
        "operationId": "list-pages",
        "summary": "List all pages",
        "description": "Returns the pages the current user may read, ordered by title then uniqueId.\n\n**Response shape depends on the request.** Without `limit` or `cursor` the response is a bare array — unchanged from earlier versions — capped at 2000 entries. Send either parameter and the response becomes a paged envelope instead.\n\n**Pagination is keyset, not offset.** The cursor encodes the sort key of the last row served, so a page created or deleted mid-walk cannot make the caller skip or repeat a row. There is deliberately no `offset` parameter.",
        "tags": [
          "Pages"
        ],
        "responses": {
          "200": {
            "description": "A bare array by default, or a paged envelope when limit or cursor is sent.",
            "headers": {
              "X-IntraVox-Cap": {
                "description": "The ceiling applied to an unpaginated response.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-IntraVox-Truncated": {
                "description": "`true` when the listing was cut off at the cap. Sent on unpaginated responses so a truncated answer can say so without changing shape.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PageSummary"
                      }
                    },
                    {
                      "$ref": "#/components/schemas/PagedPageSummaries"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Sending this switches the response to the paged envelope. Values above 500 are clamped, so paging cannot be used to exceed the listing cap.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque cursor from a previous response's `nextCursor`. Also switches the response to the paged envelope. A cursor this server did not issue is rejected with 400.",
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "post": {
        "operationId": "create-page",
        "summary": "Create a new page",
        "description": "Creates a new page with the given data",
        "tags": [
          "Pages"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PageCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Page created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "description": "Rate limit exceeded (10 per minute per user)."
          }
        }
      }
    },
    "/api/pages/copy": {
      "post": {
        "operationId": "copy-page",
        "summary": "Duplicate a page",
        "description": "Copies a page to a new location. TWO permissions are checked, not one: read on the source and create on the destination folder — so copying out of a page you may read into a folder you may not write is refused.\n\nReturns 201 with the new page, not 200.",
        "tags": [
          "Pages"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sourceId": {
                    "type": "string",
                    "description": "Page to copy. Required and non-empty."
                  },
                  "targetParentId": {
                    "type": "string",
                    "description": "New parent. Omit or leave empty for the language root."
                  },
                  "title": {
                    "type": "string",
                    "description": "Title for the copy. Omit to derive one from the source."
                  }
                },
                "required": [
                  "sourceId"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "page": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "The newly created page."
                    }
                  },
                  "required": [
                    "success",
                    "page"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "sourceId missing."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "No read permission on the source, or no create permission at the destination."
          },
          "500": {
            "description": "The copy failed."
          }
        }
      }
    },
    "/api/pages/from-template": {
      "post": {
        "operationId": "create-page-from-template",
        "summary": "Create page from template",
        "description": "Creates a new page based on an existing template. Clones the template's layout, widgets, and media files.",
        "tags": [
          "Templates"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TemplateCreateFromRequest"
              },
              "examples": {
                "department": {
                  "summary": "Create HR department page",
                  "value": {
                    "templateId": "department",
                    "pageTitle": "HR Department",
                    "parentPath": "/teams"
                  }
                },
                "event": {
                  "summary": "Create company event page",
                  "value": {
                    "templateId": "event",
                    "pageTitle": "Annual Conference 2026"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Page created from template successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "page": {
                      "$ref": "#/components/schemas/Page"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid template ID or missing parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/pages/move": {
      "post": {
        "operationId": "move-page",
        "summary": "Move a page to a new parent",
        "description": "Re-parents one page. The single-page counterpart of POST /api/bulk/move, and it enforces the same refusals: not into itself or a descendant, not across languages (language folders are independent content trees), and not the homepage.\n\nTwo permissions are checked: write on the page and create on the destination folder.\n\nIdempotent — a page already directly under the target is a no-op that reports success. Rate limited to 20 per minute per user.",
        "tags": [
          "Pages"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pageId": {
                    "type": "string",
                    "description": "Page to move. Required and non-empty."
                  },
                  "targetParentId": {
                    "type": "string",
                    "description": "New parent. Omit or leave empty to move to the root of the page's OWN language — never the caller's."
                  }
                },
                "required": [
                  "pageId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Moved, or already there.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessAck"
                }
              }
            }
          },
          "400": {
            "description": "pageId missing, or the move is into the page itself or a descendant."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "No write permission on the page, or no create permission at the destination."
          },
          "429": {
            "description": "Rate limit exceeded (20 per minute per user)."
          },
          "500": {
            "description": "The move failed."
          }
        }
      }
    },
    "/api/pages/reorder": {
      "post": {
        "operationId": "reorder-pages",
        "summary": "Set the sibling order under a parent",
        "description": "Rewrites the order of children under one parent. The list is a COMPLETE ordering, not a delta: send every child in the order you want them.\n\nPermission is checked on the PARENT folder, not on each child — reordering rearranges the container.\n\nRate limited to 20 per minute per user.",
        "tags": [
          "Pages"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "parentId": {
                    "type": "string",
                    "description": "The parent whose children are being ordered. Omit or leave empty for the language root."
                  },
                  "orderedIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "description": "Every child, in the desired order. Must be non-empty and contain only non-empty strings."
                  }
                },
                "required": [
                  "orderedIds"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reordered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessAck"
                }
              }
            }
          },
          "400": {
            "description": "orderedIds empty, or an entry is not a non-empty string."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "No write permission on the parent folder."
          },
          "429": {
            "description": "Rate limit exceeded (20 per minute per user)."
          },
          "500": {
            "description": "The reorder failed."
          }
        }
      }
    },
    "/api/pages/tree": {
      "get": {
        "operationId": "get-page-tree",
        "summary": "Get page tree",
        "description": "Returns the hierarchical page tree structure",
        "tags": [
          "Pages"
        ],
        "responses": {
          "200": {
            "description": "Page tree",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tree": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PageTreeNode"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/pages/{id}": {
      "get": {
        "operationId": "get-page",
        "summary": "Get a page",
        "description": "Returns a single page by its unique ID\n\nThe response carries `baseVersion`; send it back on PUT to avoid overwriting a concurrent edit.",
        "tags": [
          "Pages"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Page unique ID (e.g., page-abc123)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "operationId": "update-page",
        "summary": "Update a page",
        "description": "Updates an existing page\n\nCONCURRENCY. A read returns `baseVersion`, the file's modification time at that moment. Send it back in the PUT body and a write that started from an older copy is refused with 409 instead of silently overwriting the other edit.\n\nOmitting it is allowed and is NOT treated as a conflict — an importer or a script that never read the page has nothing to compare. That is a deliberate choice with a consequence worth knowing: a client that leaves `baseVersion` out gets last-write-wins. Interactive editors should always send it.\n\nThe value is never persisted; it is stripped from the payload before the page is written.",
        "tags": [
          "Pages"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Page unique ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PageUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Page updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Conflict: the submitted baseVersion predates the stored file, so someone else saved while this copy was being edited. Re-read the page and re-apply the change; retrying the same body will keep failing."
          }
        }
      },
      "delete": {
        "operationId": "delete-page",
        "summary": "Delete a page",
        "description": "Deletes a page and all its children",
        "tags": [
          "Pages"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Page unique ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessAck"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limit exceeded (10 per minute per user)."
          }
        }
      }
    },
    "/api/pages/{id}/breadcrumb": {
      "get": {
        "operationId": "get-breadcrumb",
        "summary": "Get page breadcrumb",
        "description": "Returns the breadcrumb path for a page",
        "tags": [
          "Pages"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Breadcrumb path",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "breadcrumb": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BreadcrumbItem"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/pages/{pageId}/comments": {
      "get": {
        "operationId": "get-comments",
        "summary": "Get page comments",
        "description": "Returns comments for a page",
        "tags": [
          "Comments"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Comment list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "comments": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Comment"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Something went wrong. The body carries a generic message plus an errorId that correlates with the server log.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SafeError"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "create-comment",
        "summary": "Create comment",
        "description": "Creates a new comment on a page\n\nRate limited to 20 per minute per user.",
        "tags": [
          "Comments"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content": {
                    "type": "string",
                    "description": "Comment content"
                  },
                  "parentId": {
                    "type": "integer",
                    "description": "Parent comment ID for replies"
                  }
                },
                "required": [
                  "content"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Comment created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Comment"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Rate limit exceeded (20 per minute per user)."
          },
          "500": {
            "description": "Something went wrong. The body carries a generic message plus an errorId that correlates with the server log.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SafeError"
                }
              }
            }
          }
        }
      }
    },
    "/api/pages/{pageId}/content": {
      "get": {
        "operationId": "get-current-page-content",
        "summary": "Raw stored document for a page",
        "description": "The page document exactly as stored, without the permissions and metadata wrapper that GET /api/pages/{id} adds. Intended for diffing against a version: this and the version-content endpoint return the same shape, so the two can be compared directly.",
        "tags": [
          "Pages"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The stored document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "No read permission on this page."
          },
          "500": {
            "description": "The content could not be read."
          }
        }
      }
    },
    "/api/pages/{pageId}/lock": {
      "get": {
        "operationId": "get-page-lock",
        "summary": "Who holds the lock",
        "tags": [
          "Page Locks"
        ],
        "description": "Reading is free of side effects; the lock is not taken or extended.",
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The current lock, or null when the page is free.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "lock"
                  ],
                  "properties": {
                    "lock": {
                      "$ref": "#/components/schemas/PageLock"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "operationId": "acquire-page-lock",
        "summary": "Take the lock before editing",
        "tags": [
          "Page Locks"
        ],
        "description": "Answers 409 when another user already holds it. Taking a lock you already hold succeeds rather than conflicting.",
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lock acquired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageLockResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "description": "The page is locked by someone else. The body names the holder, so the caller can say who rather than just \"locked\".",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageLockResult"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "refresh-page-lock",
        "summary": "Keep the lock alive",
        "tags": [
          "Page Locks"
        ],
        "description": "The heartbeat. Without it a lock goes stale and another user may take over, so an editor that stops calling this releases the page by itself.",
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lock extended.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageLockResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "description": "The page is locked by someone else. The body names the holder, so the caller can say who rather than just \"locked\".",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageLockResult"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "release-page-lock",
        "summary": "Release your own lock",
        "tags": [
          "Page Locks"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Released.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageLockResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/pages/{pageId}/lock/force-release": {
      "post": {
        "operationId": "force-release-page-lock",
        "summary": "Break someone else's lock",
        "tags": [
          "Page Locks"
        ],
        "description": "Admin only. For the case where an editor left a page open and went home; the action is logged with both accounts.",
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lock broken.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageLockResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/pages/{pageId}/media": {
      "post": {
        "operationId": "upload-media",
        "summary": "Upload media file",
        "description": "Uploads a media file to a page",
        "tags": [
          "Media"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "File to upload"
                  }
                },
                "required": [
                  "file"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "File uploaded successfully (201 Created)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "filename": {
                      "type": "string"
                    },
                    "path": {
                      "type": "string"
                    },
                    "size": {
                      "type": "integer"
                    },
                    "mimeType": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "description": "File too large"
          }
        }
      }
    },
    "/api/pages/{pageId}/media/check": {
      "post": {
        "operationId": "check-media-duplicate",
        "summary": "Would this upload overwrite something?",
        "description": "Asks whether a file of that name already exists, so a client can warn before uploading rather than after.\n\nSEND THE RAW FILENAME, exactly as the user picked it. The check sanitises it the same way the upload will before comparing — asking about an already-sanitised name answers a question nobody asked. This matters because two different names can sanitise to the same one: checking them raw is what catches that collision, and checking them pre-sanitised reported 'no duplicate' and then collided on write.",
        "tags": [
          "Media"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "filename": {
                    "type": "string",
                    "description": "The raw filename as chosen. Do not sanitise it first."
                  },
                  "target": {
                    "type": "string",
                    "default": "page",
                    "enum": [
                      "page",
                      "resources"
                    ]
                  }
                },
                "required": [
                  "filename"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Whether the sanitised name is taken.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "exists": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "exists"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "filename missing, or its extension is not allowed."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/pages/{pageId}/media/list": {
      "get": {
        "operationId": "list-media",
        "summary": "List media files",
        "description": "Lists the media in a page's `_media` folder, or in the shared resources folder.\n\nThe response is capped at 1000 entries; the headers say which ceiling applied and whether it was reached.",
        "tags": [
          "Media"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "folder",
            "in": "query",
            "required": false,
            "description": "`page` (default) lists the page's own `_media` folder; `resources` lists the instance-wide resources folder, which grows with the instance rather than the page.",
            "schema": {
              "type": "string",
              "enum": [
                "page",
                "resources"
              ],
              "default": "page"
            }
          },
          {
            "name": "path",
            "in": "query",
            "required": false,
            "description": "Subfolder within the resources folder. Path traversal is rejected with 400.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The media entries, capped.",
            "headers": {
              "X-IntraVox-Cap": {
                "description": "The ceiling applied.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-IntraVox-Truncated": {
                "description": "`true` when entries were cut off at the cap.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "media"
                  ],
                  "properties": {
                    "media": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MediaFile"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/pages/{pageId}/media/upload": {
      "post": {
        "operationId": "upload-media-with-name",
        "summary": "Upload a media file, keeping its name",
        "description": "Uploads a file and stores it under its own (sanitised) name rather than a generated one, which is what makes the duplicate check meaningful.\n\nThe file may be sent as 'media' or as 'file' — both field names are accepted.\n\nWithout overwrite an existing name is refused; the response's 'exists' flag tells you which happened. Requires write permission on the page. Returns 201.",
        "tags": [
          "Media"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "media": {
                    "type": "string",
                    "format": "binary",
                    "description": "The file. May also be sent as 'file'."
                  },
                  "target": {
                    "type": "string",
                    "default": "page",
                    "enum": [
                      "page",
                      "resources"
                    ]
                  },
                  "overwrite": {
                    "type": "string",
                    "enum": [
                      "0",
                      "1"
                    ],
                    "description": "Replace an existing file of the same name."
                  }
                },
                "required": [
                  "media"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Stored.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "filename": {
                      "type": "string",
                      "description": "The name actually written, after sanitising. May differ from what you sent."
                    },
                    "exists": {
                      "type": "boolean",
                      "description": "Whether a file of that name was already there."
                    }
                  },
                  "required": [
                    "filename"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "No file, or a disallowed type."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "No write permission on this page."
          },
          "404": {
            "description": "No such page."
          }
        }
      }
    },
    "/api/pages/{pageId}/media/{filename}": {
      "get": {
        "operationId": "get-media",
        "summary": "Get media file",
        "description": "Returns a media file",
        "tags": [
          "Media"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "filename",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Media file content",
            "content": {
              "image/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "video/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/pages/{pageId}/metadata": {
      "get": {
        "operationId": "get-page-metadata",
        "summary": "Get page metadata",
        "description": "Returns the page's metadata (title, modified/created timestamps, path, permissions). Does not return the page layout. Includes folderName (2.0.1): the folder the rename dialog may offer to rename, or null when the page has no renamable folder/JSON pair (homepage, loose legacy file).",
        "tags": [
          "Pages"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The stored MetaVox values.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageMetadata"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "put": {
        "operationId": "update-page-metadata",
        "summary": "Update page metadata (rename)",
        "description": "Updates page metadata without touching the layout. Currently the title — this is what the \"Rename page\" action calls. Requires write permission. The page's uniqueId never changes. Optionally (2.0.1, #95) the page's folder and its paired .json can be renamed along with the title by passing folderName; on a name collision a -2/-3 suffix is applied. The homepage and loose legacy files are never folder-renamed. If the navigation menu label still matched the old title it is updated too.",
        "tags": [
          "Pages"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "New page title."
                  },
                  "folderName": {
                    "type": "string",
                    "description": "Optional new folder slug (lowercase, a-z0-9-). When present, the page's folder and paired .json are renamed as a pair — or not at all. The response reports the outcome in folderRename; a failed folder rename never fails the title rename."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The values as stored after validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageMetadata"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Permission denied"
          }
        }
      }
    },
    "/api/pages/{pageId}/reactions": {
      "get": {
        "operationId": "get-page-reactions",
        "summary": "Reactions on a page",
        "tags": [
          "Comments"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The complete reaction state.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reactions"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such page, or no access."
          },
          "500": {
            "description": "Something went wrong. The body carries a generic message plus an errorId that correlates with the server log.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SafeError"
                }
              }
            }
          }
        },
        "description": "The complete reaction state for one page.\n\n404 covers both 'no such page' and 'no access to it', deliberately indistinguishable."
      }
    },
    "/api/pages/{pageId}/reactions/{emoji}": {
      "post": {
        "operationId": "add-page-reaction",
        "summary": "React to a page",
        "tags": [
          "Comments"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "emoji",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The emoji itself, URL-encoded. Stored verbatim as the reaction's message — there is no server-side allowlist, so what you send is what every reader sees."
          }
        ],
        "responses": {
          "200": {
            "description": "The complete reaction state after adding.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reactions"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such page, or no access."
          },
          "429": {
            "description": "Rate limit exceeded (30 per minute per user)."
          },
          "500": {
            "description": "Something went wrong. The body carries a generic message plus an errorId that correlates with the server log.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SafeError"
                }
              }
            }
          }
        },
        "description": "Adds the calling user's reaction and returns the complete new state.\n\nIdempotent: adding a reaction the user already has, or removing one they never had, succeeds and returns the unchanged state. Safe to retry, and safe to fire from an optimistic UI.\n\n404 covers both 'no such page' and 'no access to it', deliberately indistinguishable.\n\nRate limited to 30 per minute per user.\n\nONE REACTION PER USER, ALWAYS. Adding a reaction silently WITHDRAWS the user's previous one — this is not a configurable mode, it is unconditional. A client that treats this as purely additive will show a stale count for the emoji that was just removed, which is why every reaction endpoint returns the complete state instead of a delta: replace your local state, never increment it."
      },
      "delete": {
        "operationId": "remove-page-reaction",
        "summary": "Withdraw a reaction from a page",
        "tags": [
          "Comments"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "emoji",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The emoji itself, URL-encoded. Stored verbatim as the reaction's message — there is no server-side allowlist, so what you send is what every reader sees."
          }
        ],
        "responses": {
          "200": {
            "description": "The complete reaction state after removing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reactions"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such page, or no access."
          },
          "500": {
            "description": "Something went wrong. The body carries a generic message plus an errorId that correlates with the server log.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SafeError"
                }
              }
            }
          }
        },
        "description": "Removes the calling user's reaction and returns the complete new state.\n\nIdempotent: adding a reaction the user already has, or removing one they never had, succeeds and returns the unchanged state. Safe to retry, and safe to fire from an optimistic UI.\n\n404 covers both 'no such page' and 'no access to it', deliberately indistinguishable.\n\nNOT rate limited, unlike its POST counterpart."
      }
    },
    "/api/pages/{pageId}/translatable-languages": {
      "get": {
        "operationId": "get-translatable-languages",
        "summary": "Languages this page can still be created in",
        "description": "Languages with a content folder, excluding the page's own language and languages that already hold a version of this page.",
        "tags": [
          "Translations"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Languages",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "languages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string",
                            "example": "de"
                          },
                          "name": {
                            "type": "string",
                            "example": "Deutsch"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Page not found"
          }
        }
      }
    },
    "/api/pages/{pageId}/translation-candidates": {
      "get": {
        "operationId": "get-translation-candidates",
        "summary": "Pages that could be linked as a translation",
        "description": "Pages in other languages that are not already a member of a different translation group. Languages the caller's mount does not grant are excluded.",
        "tags": [
          "Translations"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidates",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "candidates": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Translation"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Page not found"
          }
        }
      }
    },
    "/api/pages/{pageId}/translations": {
      "post": {
        "operationId": "link-translation",
        "summary": "Link an existing page as a translation",
        "description": "Joins two pages (in different languages) into one translation group. Requires edit permission on BOTH pages, checked before anything is written. Adopts an existing group when either side has one.",
        "tags": [
          "Translations"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "targetUniqueId"
                ],
                "properties": {
                  "targetUniqueId": {
                    "type": "string",
                    "description": "uniqueId of the page in the other language"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Linked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "translationGroup": {
                      "type": "string",
                      "example": "tg-..."
                    },
                    "translations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Translation"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "No edit permission"
          },
          "404": {
            "description": "Page not found"
          }
        }
      },
      "delete": {
        "operationId": "unlink-translation",
        "summary": "Unlink this page from its translation group",
        "description": "Gives this page a fresh group of its own; the other members keep theirs. Symmetric model: unlinking one member shrinks the group, nothing dangles.",
        "tags": [
          "Translations"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Unlinked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "translations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Translation"
                      },
                      "description": "Always empty after unlink"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "No edit permission"
          },
          "404": {
            "description": "Page not found"
          }
        }
      }
    },
    "/api/pages/{pageId}/translations/create": {
      "post": {
        "operationId": "create-translation",
        "summary": "Create this page in another language",
        "description": "Copies the page (content, layout and its media files) into the target language folder as a DRAFT, mirrors its position in that language's tree, and links both pages in one translation group. The target language folder must already exist.",
        "tags": [
          "Translations"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "language"
                ],
                "properties": {
                  "language": {
                    "type": "string",
                    "pattern": "^[a-z]{2,3}$",
                    "example": "de"
                  },
                  "title": {
                    "type": "string",
                    "description": "Optional title for the new page; defaults to the source title"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "page": {
                      "type": "object",
                      "description": "The created page"
                    },
                    "translations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Translation"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "No edit permission"
          },
          "404": {
            "description": "Page not found"
          }
        }
      }
    },
    "/api/pages/{pageId}/versions": {
      "get": {
        "operationId": "get-page-versions",
        "summary": "Get page versions",
        "description": "Returns version history for a page",
        "tags": [
          "Pages"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Version list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "versions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PageVersion"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/pages/{pageId}/versions/{timestamp}": {
      "post": {
        "operationId": "restore-page-version",
        "summary": "Restore page version",
        "description": "Restores a page to a previous version",
        "tags": [
          "Pages"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "timestamp",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The page as restored.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/pages/{pageId}/versions/{timestamp}/content": {
      "get": {
        "operationId": "get-version-content",
        "summary": "Raw stored document for one version",
        "description": "The page document as it was at that version, in the same shape as GET /api/pages/{pageId}/content — which is what makes a client-side diff between the two possible.\n\nReading a version needs only READ permission on the page. Restoring one needs write.",
        "tags": [
          "Pages"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "timestamp",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The version's timestamp, as returned by the versions listing."
          }
        ],
        "responses": {
          "200": {
            "description": "The document at that version.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "No read permission on this page."
          },
          "500": {
            "description": "No such version, or it could not be read."
          }
        }
      }
    },
    "/api/pages/{pageId}/versions/{timestamp}/label": {
      "put": {
        "operationId": "update-version-label",
        "summary": "Name a version",
        "description": "Attaches a human label to a stored version, so it can be recognised later without opening it. Requires WRITE permission on the page, unlike reading versions.\n\nThe label replaces any previous one; sending an empty label clears it.",
        "tags": [
          "Pages"
        ],
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "timestamp",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The version's timestamp, as returned by the versions listing."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string",
                    "description": "The label. Empty clears it."
                  }
                },
                "required": [
                  "label"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Labelled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessAck"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "No write permission on this page."
          },
          "500": {
            "description": "No such version, or the label could not be stored."
          }
        }
      }
    },
    "/api/pages/{uniqueId}/share-info": {
      "get": {
        "operationId": "get-share-info",
        "summary": "Get share info for a page",
        "description": "Returns information about whether and how a page is shared via Nextcloud share links. Includes scope, password status, and public URL.",
        "tags": [
          "Public Share"
        ],
        "parameters": [
          {
            "name": "uniqueId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Unique ID of the page"
          }
        ],
        "responses": {
          "200": {
            "description": "Share information",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "hasShare": {
                      "type": "boolean"
                    },
                    "scope": {
                      "type": "string",
                      "enum": [
                        "page",
                        "folder"
                      ]
                    },
                    "scopeName": {
                      "type": "string"
                    },
                    "scopeLabel": {
                      "type": "string"
                    },
                    "isLanguageRoot": {
                      "type": "boolean"
                    },
                    "hasPassword": {
                      "type": "boolean"
                    },
                    "publicUrl": {
                      "type": "string"
                    },
                    "filesUrl": {
                      "type": "string"
                    },
                    "navigation": {
                      "type": "array"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/people": {
      "get": {
        "operationId": "get-people",
        "summary": "Get people for a People widget",
        "description": "Returns the users a People widget shows. Without refine/facets/q this is the plain editor-configured list. With them, viewer-side faceted filtering applies: refinements are ANDed with the editor's filters and can only narrow the result, never widen it.",
        "tags": [
          "People"
        ],
        "parameters": [
          {
            "name": "userIds",
            "in": "query",
            "description": "Comma-separated user IDs (manual selection mode).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "filters",
            "in": "query",
            "description": "JSON array of editor filter rows.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "filterOperator",
            "in": "query",
            "description": "How editor filters combine.",
            "schema": {
              "type": "string",
              "enum": [
                "AND",
                "OR"
              ],
              "default": "AND"
            }
          },
          {
            "name": "sortBy",
            "in": "query",
            "description": "Field to sort by.",
            "schema": {
              "type": "string",
              "default": "displayName"
            }
          },
          {
            "name": "sortOrder",
            "in": "query",
            "description": "Sort direction.",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum users to return.",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset.",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "refine",
            "in": "query",
            "description": "JSON array of viewer refinement rows ({field, op, value}). ANDed with `filters`; max 12 rows.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Free-text term matched against searchFields.",
            "schema": {
              "type": "string",
              "maxLength": 128
            }
          },
          {
            "name": "facets",
            "in": "query",
            "description": "Comma-separated field names to compute facets for. Fields already present in `filters` are dropped, since they could only yield empty options.",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "name": "searchFields",
            "in": "query",
            "description": "Comma-separated fields the free-text term searches.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "facetLimit",
            "in": "query",
            "description": "Values per facet.",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching users, plus facets when requested",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "users": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "hasMore": {
                      "type": "boolean"
                    },
                    "facets": {
                      "type": "array",
                      "description": "Facet groups with live counts. A facet is counted excluding its own selections, so sibling values stay selectable.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "values": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "value": {
                                  "type": "string"
                                },
                                "label": {
                                  "type": "string"
                                },
                                "count": {
                                  "type": "integer",
                                  "description": "Matches for this value. Approximate when meta.approximate is true."
                                },
                                "selected": {
                                  "type": "boolean"
                                }
                              }
                            }
                          },
                          "truncated": {
                            "type": "boolean",
                            "description": "More values exist than were returned."
                          },
                          "countsAvailable": {
                            "type": "boolean",
                            "description": "False when counts could not be computed reliably; render values without numbers."
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "approximate": {
                          "type": "boolean",
                          "description": "True when the account scan hit its cap; counts are partial and should be shown as such."
                        },
                        "scanned": {
                          "type": "integer"
                        },
                        "cap": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or oversized filters/refine JSON"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/people/facet-preflight": {
      "get": {
        "operationId": "get-people-facet-preflight",
        "summary": "Whether facet counts will be exact on this instance",
        "description": "Used by the widget editor to warn before a widget is configured, rather than letting approximate counts surface in production.",
        "tags": [
          "People"
        ],
        "responses": {
          "200": {
            "description": "Instance size relative to the scan cap",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "userCount": {
                      "type": "integer"
                    },
                    "cap": {
                      "type": "integer"
                    },
                    "approximate": {
                      "type": "boolean",
                      "description": "True when the instance exceeds the cap, so counts will be approximate."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/permissions": {
      "get": {
        "operationId": "get-permissions",
        "summary": "Get user permissions",
        "description": "Returns the current user's permissions",
        "tags": [
          "Settings"
        ],
        "responses": {
          "200": {
            "description": "Permission data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "isAdmin": {
                      "type": "boolean"
                    },
                    "canEdit": {
                      "type": "boolean"
                    },
                    "canCreate": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/photo-story/capabilities": {
      "get": {
        "summary": "Server-side capabilities for the Photo Story widget",
        "responses": {
          "200": {
            "description": "What the server can do for this source.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoryCapabilitiesResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Unable to load capabilities"
          }
        },
        "operationId": "photo-story-capabilities",
        "tags": [
          "Photo Story"
        ]
      }
    },
    "/api/photo-story/clusters": {
      "get": {
        "summary": "GPS-cluster the photos in a folder (capped at 5000)",
        "parameters": [
          {
            "name": "folder",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Geographic clusters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhotoClusterListing"
                }
              }
            }
          },
          "400": {
            "description": "Missing folder parameter"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Unable to load location clusters"
          }
        },
        "operationId": "list-photo-clusters",
        "tags": [
          "Photo Story"
        ]
      }
    },
    "/api/photo-story/metavox-fields": {
      "get": {
        "summary": "MetaVox field discovery for filter-builder / sort / group-by",
        "responses": {
          "200": {
            "description": "MetaVox fields, or an empty list when MetaVox is absent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetaVoxFieldList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "operationId": "photo-story-metavox-fields",
        "tags": [
          "Photo Story"
        ]
      }
    },
    "/api/photo-story/open-in-files": {
      "get": {
        "operationId": "open-photo-in-files",
        "summary": "Redirect to a photo in the Files app",
        "description": "REDIRECTS (302) to the Files app, scrolled to the file and with it opened. It does NOT return JSON on success — a client following redirects lands on an HTML page, so this belongs in a browser, not in an API call.\n\nAccess is resolved through the caller's own file view, so a file id they cannot see yields 404 rather than a redirect they cannot follow.",
        "tags": [
          "Photo Story"
        ],
        "parameters": [
          {
            "name": "file_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Nextcloud file id. Note the snake_case name."
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to the Files app."
          },
          "400": {
            "description": "file_id missing or not a positive integer."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such file, or the caller cannot see it."
          },
          "500": {
            "description": "The file could not be resolved."
          }
        }
      }
    },
    "/api/photo-story/photo-exif": {
      "get": {
        "summary": "Detailed EXIF for a single photo (used by the lightbox info-pane)",
        "parameters": [
          {
            "name": "file_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "EXIF metadata for one photo.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhotoExif"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid file_id"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "File not found or no EXIF data"
          }
        },
        "operationId": "get-photo-exif",
        "tags": [
          "Photo Story"
        ]
      }
    },
    "/api/photo-story/photos": {
      "get": {
        "summary": "List photos in a folder (paged, mode-aware)",
        "description": "Returns a paged list of photo rows enriched with NC core metadata + MetaVox metadata. Supports timeline/grid/highlights/on-this-day modes, MetaVox filters and cross-folder mode (empty folder + ≥1 filter).",
        "parameters": [
          {
            "name": "folder",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mode",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "timeline",
                "highlights",
                "grid",
                "on-this-day"
              ]
            }
          },
          {
            "name": "filters",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "JSON-encoded filter array (max 16 KB)"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            }
          },
          {
            "name": "sortOrder",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          },
          {
            "name": "sortBy",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Photos, shaped by the requested mode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhotoStoryListing"
                }
              }
            }
          },
          "304": {
            "description": "Not Modified (matches If-None-Match)"
          },
          "400": {
            "description": "Invalid mode / filter payload too large"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Folder not found for this user"
          },
          "500": {
            "description": "Unable to load photos"
          }
        },
        "operationId": "list-photos",
        "tags": [
          "Photo Story"
        ]
      }
    },
    "/api/photo-story/video": {
      "get": {
        "summary": "Range-aware video streaming endpoint for the lightbox",
        "parameters": [
          {
            "name": "file_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The video itself, streamed. Supports HTTP range requests, so a player can seek without downloading the whole file. This is not a JSON endpoint.",
            "content": {
              "video/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "206": {
            "description": "Video stream (partial content)"
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Not found or no access"
          },
          "416": {
            "description": "Range Not Satisfiable"
          },
          "500": {
            "description": "Unable to stream video"
          }
        },
        "operationId": "get-photo-story-video",
        "tags": [
          "Photo Story"
        ]
      }
    },
    "/api/preview": {
      "get": {
        "summary": "Federated-aware preview proxy (shared by PhotoStory and FileStory)",
        "description": "Generates a thumbnail for a single file by id. Local files 302-redirect to NC core /core/preview so NC's own preview cache stays hot. Federated files (Files_Sharing\\External\\Storage) are fetched from the owner instance's publicpreview endpoint and cached in appdata. In-flight dedup ensures concurrent identical requests share one outbound call; a per-remote concurrency cap protects the owning NC instance from a stampede. Falls back to a 302 redirect to the matching mime-icon SVG when no preview can be produced. Rate-limited to 600 requests per user per minute.",
        "parameters": [
          {
            "name": "file_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "NC filecache fileid of the file to preview"
          },
          {
            "name": "x",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 32,
              "maximum": 2048,
              "default": 400
            }
          },
          {
            "name": "y",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 32,
              "maximum": 2048,
              "default": 400
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The preview image itself.",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "302": {
            "description": "Redirect to Nextcloud's own preview or a mimetype icon when no thumbnail can be produced."
          },
          "400": {
            "description": "file_id missing or invalid"
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "File not visible to the current user"
          },
          "429": {
            "description": "Per-user rate limit exceeded (600/min)"
          }
        },
        "operationId": "fetch-link-preview",
        "tags": [
          "Link Previews"
        ]
      }
    },
    "/api/preview/warmup": {
      "post": {
        "summary": "Pre-warm the federated-preview cache for a batch of file ids",
        "description": "Best-effort: synchronously warms up to 16 federated file thumbnails per call. Designed for the PhotoStory/FileStory widgets to call once per page-load with every is_federated fileId from the just-fetched page. Local fileIds and inaccessible ones are silently skipped (counted under 'skipped'). Rate-limited to 60 calls per user per minute.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "file_ids": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    },
                    "description": "List of NC filecache fileids to warm"
                  }
                },
                "required": [
                  "file_ids"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Counts of fileIds for which a preview was successfully warmed vs skipped",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "warmed": {
                      "type": "integer"
                    },
                    "skipped": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "429": {
            "description": "Per-user rate limit exceeded (60/min)"
          }
        },
        "operationId": "warm-link-previews",
        "tags": [
          "Link Previews"
        ]
      }
    },
    "/api/resources/media/{filename}": {
      "get": {
        "operationId": "get-resources-media",
        "summary": "Serve a shared resource file",
        "description": "Serves a file from the shared resources folder — media reused across pages, as opposed to media belonging to one page.\n\nServed inline with a ONE-YEAR immutable cache, so a replaced file keeps serving the old bytes to anyone who cached it. Upload under a new name rather than replacing in place.\n\nThe Content-Type is sniffed from the file's own bytes, not from its extension.",
        "tags": [
          "Media"
        ],
        "parameters": [
          {
            "name": "filename",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The file, inline.",
            "content": {
              "*/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "The path was rejected as invalid."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such file."
          }
        }
      }
    },
    "/api/resources/media/{folder}/{filename}": {
      "get": {
        "operationId": "get-resources-media-in-folder",
        "summary": "Serve a shared resource file from a subfolder",
        "description": "Serves a file from the shared resources folder — media reused across pages, as opposed to media belonging to one page.\n\nServed inline with a ONE-YEAR immutable cache, so a replaced file keeps serving the old bytes to anyone who cached it. Upload under a new name rather than replacing in place.\n\nThe Content-Type is sniffed from the file's own bytes, not from its extension.\n\nThe subfolder variant. Exactly one level deep — deeper paths are not addressable here.",
        "tags": [
          "Media"
        ],
        "parameters": [
          {
            "name": "folder",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "One subfolder level."
          },
          {
            "name": "filename",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The file, inline.",
            "content": {
              "*/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "The path was rejected as invalid."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such file."
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "operationId": "search-pages",
        "summary": "Search pages",
        "description": "Search pages by title and content",
        "tags": [
          "Pages"
        ],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "Search query (minimum 2 characters)",
            "schema": {
              "type": "string",
              "minLength": 2
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SearchResult"
                      }
                    },
                    "query": {
                      "type": "string"
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Rate limit exceeded (30 per minute per user)."
          }
        }
      }
    },
    "/api/settings/engagement": {
      "get": {
        "operationId": "get-engagement-settings",
        "summary": "Get engagement settings",
        "tags": [
          "Settings"
        ],
        "responses": {
          "200": {
            "description": "Engagement settings",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EngagementSettings"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "operationId": "set-engagement-settings",
        "summary": "Set engagement settings",
        "description": "Admin only",
        "tags": [
          "Settings"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EngagementSettings"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The stored engagement settings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettingsSaveResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/settings/feed-connections": {
      "get": {
        "operationId": "get-feed-connections",
        "summary": "List configured feed connections",
        "description": "Returns every configured connection. Available to all logged-in users because the widget editor needs the names, but the response is FIELD-FILTERED BY ROLE: tenantId, clientId, jiraEmail, apiKeyHeader and customHeaders are returned only to administrators, and tokens and client secrets are never returned to anyone — only the hasToken and hasClientCredentials booleans.",
        "tags": [
          "Feeds",
          "Settings"
        ],
        "responses": {
          "200": {
            "description": "Configured connections",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connections": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FeedConnection"
                      }
                    }
                  },
                  "required": [
                    "connections"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Connections could not be read."
          }
        }
      },
      "post": {
        "operationId": "set-feed-connections",
        "summary": "Replace the feed connection list (admin)",
        "description": "Replaces the entire connection list — this is a PUT in spirit; anything omitted is removed.\n\nAdministrators only; a non-admin receives 403.\n\nToken preservation: sending a connection with an empty token field KEEPS the stored token rather than clearing it, so an admin screen can display a masked value and save without re-entering the secret. To actually remove a token, remove the connection.",
        "tags": [
          "Feeds",
          "Settings"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "connections": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/FeedConnection"
                    },
                    "description": "The complete list. Each entry may additionally carry write-only token, clientSecret and customHeaders values."
                  }
                },
                "required": [
                  "connections"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusOk"
                }
              }
            }
          },
          "400": {
            "description": "connections was not an array."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Administrator access required."
          },
          "500": {
            "description": "Save failed."
          }
        }
      }
    },
    "/api/settings/license": {
      "post": {
        "operationId": "save-license-key",
        "summary": "Store a subscription key",
        "tags": [
          "Licensing"
        ],
        "description": "Admin only. Storing a key does not validate it; call the validate endpoint afterwards.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "licenseKey"
                ],
                "properties": {
                  "licenseKey": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stored.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/settings/public-share-people": {
      "get": {
        "operationId": "get-public-share-people-setting",
        "summary": "Whether People widgets render on public share links",
        "tags": [
          "Settings"
        ],
        "responses": {
          "200": {
            "description": "Current setting",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "allowPeopleOnPublicShares": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "operationId": "set-public-share-people-setting",
        "summary": "Allow or forbid People widgets on public share links",
        "description": "Admin only. Off by default: a public share is normally created to hand someone documents, and a People widget on that page would publish a staff directory to anyone holding the link.",
        "tags": [
          "Settings"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "allowPeopleOnPublicShares": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "allowPeopleOnPublicShares"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Setting saved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "allowPeopleOnPublicShares": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not an administrator"
          }
        }
      }
    },
    "/api/settings/publication": {
      "get": {
        "operationId": "get-publication-settings",
        "summary": "Get publication settings",
        "tags": [
          "Settings"
        ],
        "responses": {
          "200": {
            "description": "Publication settings",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicationSettings"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "operationId": "set-publication-settings",
        "summary": "Set publication settings",
        "description": "Admin only",
        "tags": [
          "Settings"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicationSettings"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The stored publication settings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettingsSaveResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/settings/telemetry": {
      "post": {
        "operationId": "set-telemetry",
        "summary": "Turn anonymous usage telemetry on or off",
        "description": "Administrators only. Takes effect immediately for subsequent background reporting runs.",
        "tags": [
          "Settings"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean",
                    "description": "Absent is treated as false, so an empty body switches telemetry OFF rather than leaving it unchanged."
                  }
                },
                "required": [
                  "enabled"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "enabled": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "success",
                    "enabled"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Administrator access required."
          },
          "500": {
            "description": "The setting could not be stored."
          }
        }
      }
    },
    "/api/settings/upload-limit": {
      "get": {
        "operationId": "get-upload-limit",
        "summary": "Effective maximum upload size",
        "description": "The upload ceiling actually in force, derived from the server's PHP and Nextcloud settings rather than from anything IntraVox configures. Use it to size a client-side check; the server enforces it regardless.",
        "tags": [
          "Settings"
        ],
        "responses": {
          "200": {
            "description": "The limit, in bytes and in MB.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "limit": {
                      "type": "integer",
                      "description": "Bytes."
                    },
                    "limitMB": {
                      "type": "number",
                      "description": "The same value in MB, rounded to one decimal. Convenience only."
                    }
                  },
                  "required": [
                    "limit",
                    "limitMB"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "The limit could not be determined."
          }
        }
      }
    },
    "/api/settings/video-domains": {
      "get": {
        "operationId": "get-video-domains",
        "summary": "Get video domains whitelist",
        "tags": [
          "Settings"
        ],
        "responses": {
          "200": {
            "description": "Video domains",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "domains": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "operationId": "set-video-domains",
        "summary": "Set video domains whitelist",
        "description": "Admin only",
        "tags": [
          "Settings"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domains": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The stored allow-list, with any rejected entries named.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VideoDomainsSaveResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/setup": {
      "post": {
        "operationId": "run-setup",
        "summary": "Create the IntraVox group folder",
        "description": "Provisions the group folder IntraVox stores everything in, and runs any pending content migration. Administrators only.\n\nSafe to call when setup is already complete — it converges rather than recreating, so it doubles as a repair step when the folder was removed by hand.\n\nThis is the first call on a fresh install: until it succeeds, endpoints that need the group folder report setup_required or return empty.",
        "tags": [
          "Settings"
        ],
        "responses": {
          "200": {
            "description": "Setup completed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "message": {
                      "type": "string"
                    },
                    "result": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "What provisioning did."
                    },
                    "migration": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "What the content migration did, if any was pending."
                    }
                  },
                  "required": [
                    "success",
                    "message"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Administrator access required."
          },
          "500": {
            "description": "Setup failed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "success",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/share/{token}/calendar/events": {
      "get": {
        "operationId": "get-calendar-events-by-share",
        "summary": "Get calendar events via public share",
        "description": "Returns calendar events using the share owner's context. Requires a valid share token.",
        "tags": [
          "Calendar",
          "Public Share"
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Share token"
          },
          {
            "name": "calendarIds",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated calendar IDs"
          },
          {
            "name": "rangeStart",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Start of date range (ISO 8601)"
          },
          {
            "name": "rangeEnd",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "End of date range (ISO 8601)"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 5,
              "minimum": 1,
              "maximum": 20
            },
            "description": "Maximum events to return"
          }
        ],
        "responses": {
          "200": {
            "description": "List of events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "uid": {
                            "type": "string"
                          },
                          "summary": {
                            "type": "string"
                          },
                          "location": {
                            "type": "string"
                          },
                          "start": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "end": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "isAllDay": {
                            "type": "boolean"
                          },
                          "calendarColor": {
                            "type": "string"
                          },
                          "calendarName": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid date format"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Invalid or expired share token"
          },
          "429": {
            "description": "Rate limit exceeded (30 per 60 seconds per client). Anonymous endpoints are limited per address rather than per user, so several visitors behind one NAT share the budget."
          },
          "500": {
            "description": "Failed to get calendar events"
          }
        }
      }
    },
    "/api/share/{token}/feed/article": {
      "get": {
        "operationId": "get-feed-article-by-share",
        "summary": "Read one feed item's article body on a public share",
        "description": "As /api/feed/article, for an anonymous visitor on a shared page — the case the feature exists for, since following the link there means meeting a cookie wall with no account anywhere.\n\nGuarded by the same selector allowlist as the list: a request naming a feed, connection or selector the share does not publish is refused with 403.\n\nRate limited to 60 requests per minute per IP.",
        "tags": [
          "Feeds",
          "Public Share"
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Nextcloud share token."
          },
          {
            "$ref": "#/components/parameters/FeedSourceType"
          },
          {
            "$ref": "#/components/parameters/FeedUrl"
          },
          {
            "$ref": "#/components/parameters/FeedConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/FeedCourseId"
          },
          {
            "$ref": "#/components/parameters/FeedContentType"
          },
          {
            "$ref": "#/components/parameters/FeedJiraProject"
          },
          {
            "$ref": "#/components/parameters/FeedMoodleForumId"
          },
          {
            "$ref": "#/components/parameters/FeedListId"
          },
          {
            "$ref": "#/components/parameters/FeedSortBy"
          },
          {
            "$ref": "#/components/parameters/FeedSortOrder"
          },
          {
            "$ref": "#/components/parameters/FeedFilterKeyword"
          },
          {
            "name": "itemId",
            "in": "query",
            "required": true,
            "description": "The item's id as returned in the feed list.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The sanitized article body.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "content": {
                      "type": "string",
                      "nullable": true,
                      "description": "Sanitized HTML, or null when nothing is stored."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The share does not publish this feed or selector."
          },
          "404": {
            "description": "No article stored for this item. The entry expires with the feed it came from; clients link out instead."
          },
          "429": {
            "description": "Rate limit exceeded."
          }
        },
        "security": [
          {}
        ]
      }
    },
    "/api/share/{token}/feed/batch": {
      "post": {
        "operationId": "get-feed-batch-by-share",
        "summary": "Fetch several of a share's feeds in one request",
        "description": "As /api/feed/batch, for an anonymous visitor. The rate limit is per IP address, so a page with five widgets used to cost five of a visitor's sixty per minute — behind one office NAT that is twelve page views for everyone together.\n\nEach entry passes the same selector allowlist as the single-feed endpoint; one the share does not publish is refused in its own slot.",
        "tags": [
          "Feeds",
          "Public Share"
        ],
        "security": [
          {}
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Nextcloud share token."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "feeds"
                ],
                "properties": {
                  "feeds": {
                    "type": "object",
                    "maxProperties": 20,
                    "description": "Feed specifications keyed by a caller-chosen slot id. Each value takes the same selectors a single fetch does (sourceType, url or connectionId, plus the source-specific filters), with limit, sortBy, sortOrder and filterKeyword.",
                    "additionalProperties": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One result per slot, keyed as sent. A feed that failed carries its own error and does not fail the others.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "feeds": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing feeds, or more than 20."
          },
          "429": {
            "description": "Rate limit exceeded."
          }
        }
      }
    },
    "/api/share/{token}/feed/external": {
      "get": {
        "operationId": "get-feed-by-share",
        "summary": "Feed items on a shared page",
        "description": "The public-share twin of GET /api/feed/external, returning the same normalised FeedResult.\n\nAnonymous, but not unauthenticated: the share token IS the credential. A password-protected share additionally needs the session cookie from POST /s/{shareToken}/authenticate — without it this answers 403 like an invalid token, so a client must complete that handshake first.\n\nAn invalid, expired or unauthorised token yields 403 with {\"error\": \"Invalid or expired share token\"}. That is the same answer for 'never existed' as for 'expired', deliberately.\n\nA TOKEN PROVES THE VISITOR MAY READ A PAGE, NEVER THAT THEY MAY QUERY WHAT IS BEHIND IT. Every parameter that selects data is intersected with what the shared page actually publishes; anything beyond that set is dropped rather than honoured.\n\nThis matters more here than anywhere else, because connectionId selects a STORED connection — credentials and all — and the fetch runs server-side with them. A connectionId the page does not publish is refused with 403 rather than fetched; without that, any share token would drive any configured connection.\n\nThe same applies to the RSS url. Note the key asymmetry if you are reading the stored widget: the request parameter is 'url', the published value is stored under 'feedUrl'.\n\nUnlike the authenticated endpoint there is no per-user token resolution, so connections needing a personal LMS token return nothing useful on a share.",
        "tags": [
          "Feeds",
          "Public Share"
        ],
        "security": [
          {}
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Nextcloud share token."
          },
          {
            "$ref": "#/components/parameters/FeedSourceType"
          },
          {
            "$ref": "#/components/parameters/FeedUrl"
          },
          {
            "$ref": "#/components/parameters/FeedConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/FeedCourseId"
          },
          {
            "$ref": "#/components/parameters/FeedContentType"
          },
          {
            "$ref": "#/components/parameters/FeedJiraProject"
          },
          {
            "$ref": "#/components/parameters/FeedMoodleForumId"
          },
          {
            "$ref": "#/components/parameters/FeedListId"
          },
          {
            "$ref": "#/components/parameters/FeedSortBy"
          },
          {
            "$ref": "#/components/parameters/FeedSortOrder"
          },
          {
            "$ref": "#/components/parameters/FeedFilterKeyword"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 5,
              "minimum": 1,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Normalised feed items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedResult"
                }
              }
            }
          },
          "403": {
            "description": "Invalid share token, or a connection or feed URL this page does not publish.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedResult"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (30 per 60 seconds per client). Anonymous endpoints are limited per address rather than per user, so several visitors behind one NAT share the budget."
          },
          "500": {
            "description": "Fetch failed. Empty items array with a generic error string.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedResult"
                }
              }
            }
          }
        }
      }
    },
    "/api/share/{token}/feed/image": {
      "get": {
        "operationId": "proxy-feed-image-by-share",
        "summary": "Serve a signed external image on a shared page",
        "description": "The public-share twin of GET /api/feed/image, with identical signature handling: both url and sig are required, the HMAC is bound to the url, and an unsigned URL is refused before any outbound request.\n\nThe share token gates access to the endpoint; the signature is what keeps it from being an open proxy. Both apply — a valid token does not make an unsigned URL fetchable.\n\nAnonymous, but not unauthenticated: the share token IS the credential. A password-protected share additionally needs the session cookie from POST /s/{shareToken}/authenticate — without it this answers 403 like an invalid token, so a client must complete that handshake first.\n\nAn invalid, expired or unauthorised token yields 403 with {\"error\": \"Invalid or expired share token\"}. That is the same answer for 'never existed' as for 'expired', deliberately.",
        "tags": [
          "Feeds",
          "Public Share"
        ],
        "security": [
          {}
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Nextcloud share token."
          },
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "The image URL, exactly as it appeared in the signed link."
          },
          {
            "name": "sig",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "HMAC produced by this backend. Bound to the url; not transferable."
          }
        ],
        "responses": {
          "200": {
            "description": "The image, served inline with a one-day immutable cache.",
            "content": {
              "image/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "url or sig missing."
          },
          "403": {
            "description": "Invalid share token, or a signature that is absent or does not match."
          },
          "429": {
            "description": "Rate limit exceeded (30 per 60 seconds per client). Anonymous endpoints are limited per address rather than per user, so several visitors behind one NAT share the budget."
          },
          "502": {
            "description": "The upstream host could not be reached."
          }
        }
      }
    },
    "/api/share/{token}/navigation": {
      "get": {
        "operationId": "get-navigation-by-share",
        "summary": "Get navigation for a share",
        "description": "Returns the navigation menu filtered to the share's scope. Only items within the shared folder are included.",
        "tags": [
          "Public Share"
        ],
        "security": [
          {}
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Nextcloud share token"
          }
        ],
        "responses": {
          "200": {
            "description": "Navigation data filtered by share scope",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "navigation": {
                      "$ref": "#/components/schemas/Navigation"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Share token invalid"
          },
          "429": {
            "description": "Rate limit exceeded (60 per 60 seconds per client). Anonymous endpoints are limited per address rather than per user, so several visitors behind one NAT share the budget."
          }
        }
      }
    },
    "/api/share/{token}/news": {
      "get": {
        "operationId": "get-news-by-share",
        "summary": "Get news items for a share",
        "description": "Returns news items from pages within the share scope. Supports filtering by source page and sorting.",
        "tags": [
          "Public Share"
        ],
        "security": [
          {}
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Nextcloud share token"
          },
          {
            "name": "sourcePageId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter news to a specific source page"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10
            },
            "description": "Maximum number of news items"
          },
          {
            "name": "sourcePath",
            "in": "query",
            "required": false,
            "description": "Path within the share whose pages supply the news items.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sortBy",
            "in": "query",
            "required": false,
            "description": "Field to sort on.",
            "schema": {
              "type": "string",
              "default": "modified"
            }
          },
          {
            "name": "sortOrder",
            "in": "query",
            "required": false,
            "description": "Sort direction.",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "News items visible through this share.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "items",
                    "total"
                  ],
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NewsItem"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Share token invalid"
          },
          "429": {
            "description": "Rate limit exceeded (60 per 60 seconds per client). Anonymous endpoints are limited per address rather than per user, so several visitors behind one NAT share the budget."
          }
        }
      }
    },
    "/api/share/{token}/page/{uniqueId}": {
      "get": {
        "operationId": "get-page-by-share",
        "summary": "Get a page via share token",
        "description": "Returns a page's content for anonymous access via a Nextcloud share link. The page must be within the share's scope. Password-protected shares require a valid session (see /s/{token}/authenticate).",
        "tags": [
          "Public Share"
        ],
        "security": [
          {}
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Nextcloud share token (15-20 alphanumeric characters)"
          },
          {
            "name": "uniqueId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Unique ID of the page to retrieve"
          }
        ],
        "responses": {
          "200": {
            "description": "Page data including content, breadcrumb, and metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                }
              }
            }
          },
          "403": {
            "description": "Page is outside the share scope"
          },
          "404": {
            "description": "Share token invalid or page not found"
          },
          "429": {
            "description": "Rate limit exceeded (60 per 60 seconds per client). Anonymous endpoints are limited per address rather than per user, so several visitors behind one NAT share the budget."
          }
        }
      }
    },
    "/api/share/{token}/page/{uniqueId}/media/{filename}": {
      "get": {
        "operationId": "get-media-by-share",
        "summary": "Get page media via share token",
        "description": "Returns a media file (image, video, etc.) attached to a page within the share scope.",
        "tags": [
          "Public Share"
        ],
        "security": [
          {}
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Nextcloud share token"
          },
          {
            "name": "uniqueId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Unique ID of the page"
          },
          {
            "name": "filename",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Media filename"
          }
        ],
        "responses": {
          "200": {
            "description": "Media file content",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Share token invalid or media not found"
          },
          "429": {
            "description": "Rate limit exceeded (60 per 60 seconds per client). Anonymous endpoints are limited per address rather than per user, so several visitors behind one NAT share the budget."
          }
        }
      }
    },
    "/api/share/{token}/people": {
      "get": {
        "operationId": "get-people-by-share",
        "summary": "People on a shared page",
        "description": "The People widget's data for a publicly shared page.\n\nAnonymous, but not unauthenticated: the share token IS the credential. A password-protected share additionally needs the session cookie from POST /s/{shareToken}/authenticate — without it this answers 403 like an invalid token, so a client must complete that handshake first.\n\nAn invalid, expired or unauthorised token yields 403 with {\"error\": \"Invalid or expired share token\"}. That is the same answer for 'never existed' as for 'expired', deliberately.\n\nA TOKEN PROVES THE VISITOR MAY READ A PAGE, NEVER THAT THEY MAY QUERY WHAT IS BEHIND IT. Every parameter that selects data is intersected with what the shared page actually publishes; anything beyond that set is dropped rather than honoured.\n\nConcretely: userIds is intersected with the users the widget publishes, and a request naming only unpublished users returns an empty result rather than an error. filters are objects and cannot be intersected element-wise, so the page must publish that EXACT filter set — anything else returns empty.\n\nThe viewer-facing facet parameters are not accepted at all. A facet panel on a public share would be a browsable directory of the organisation — roles, buildings, departments and their headcounts — handed to anyone with the link.\n\nThe whole endpoint can be switched off instance-wide; when it is, it returns an empty result rather than an error, so a widget degrades to empty instead of breaking the page.",
        "tags": [
          "People",
          "Public Share"
        ],
        "security": [
          {}
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Nextcloud share token."
          },
          {
            "name": "userIds",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated user ids. Intersected with the published set; unpublished ids are silently dropped."
          },
          {
            "name": "filters",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "JSON array of {fieldName, operator, value}. Must match a filter set the page publishes exactly, or the result is empty."
          },
          {
            "name": "filterOperator",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "AND",
              "enum": [
                "AND",
                "OR"
              ]
            }
          },
          {
            "name": "sortBy",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "displayName"
            }
          },
          {
            "name": "sortOrder",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "asc",
              "enum": [
                "asc",
                "desc"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching users. Also the answer when the request was refused for publishing reasons, or when public People is disabled instance-wide — an empty set, never an error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "users": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "description": "Account properties, filtered by each user's own visibility scope. uid and displayName are always present; everything else depends on what that user published."
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "hasMore": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "users",
                    "total",
                    "hasMore"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Invalid, expired or password-gated share token."
          },
          "429": {
            "description": "Rate limit exceeded (30 per minute per client)."
          },
          "500": {
            "description": "The query failed."
          }
        }
      }
    },
    "/api/share/{token}/resources/media/{filename}": {
      "get": {
        "operationId": "get-resources-media-by-share",
        "summary": "Get shared resource media via share token",
        "description": "Returns a media file from the shared resources library (_resources folder).",
        "tags": [
          "Public Share"
        ],
        "security": [
          {}
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Nextcloud share token"
          },
          {
            "name": "filename",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Resource media filename"
          }
        ],
        "responses": {
          "200": {
            "description": "Media file content",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Share token invalid or resource not found"
          },
          "429": {
            "description": "Rate limit exceeded (60 per 60 seconds per client). Anonymous endpoints are limited per address rather than per user, so several visitors behind one NAT share the budget."
          }
        }
      }
    },
    "/api/share/{token}/resources/media/{folder}/{filename}": {
      "get": {
        "operationId": "get-resources-media-with-folder-by-share",
        "summary": "Get shared resource media from subfolder via share token",
        "description": "Returns a media file from a subfolder within the shared resources library.",
        "tags": [
          "Public Share"
        ],
        "security": [
          {}
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Nextcloud share token"
          },
          {
            "name": "folder",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Subfolder name (e.g. 'backgrounds')"
          },
          {
            "name": "filename",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Resource media filename"
          }
        ],
        "responses": {
          "200": {
            "description": "Media file content",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Share token invalid or resource not found"
          },
          "429": {
            "description": "Rate limit exceeded (60 per 60 seconds per client). Anonymous endpoints are limited per address rather than per user, so several visitors behind one NAT share the budget."
          }
        }
      }
    },
    "/api/share/{token}/tree": {
      "get": {
        "operationId": "get-page-tree-by-share",
        "summary": "Get page tree for a share",
        "description": "Returns the page tree structure filtered to the share's scope.",
        "tags": [
          "Public Share"
        ],
        "security": [
          {}
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Nextcloud share token"
          }
        ],
        "responses": {
          "200": {
            "description": "Page tree filtered by share scope",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tree": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PageTreeNode"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Share token invalid"
          },
          "429": {
            "description": "Rate limit exceeded (60 per 60 seconds per client). Anonymous endpoints are limited per address rather than per user, so several visitors behind one NAT share the budget."
          }
        }
      }
    },
    "/api/templates": {
      "get": {
        "operationId": "list-templates",
        "summary": "List all templates",
        "description": "Returns a list of all available page templates including built-in and custom templates",
        "tags": [
          "Templates"
        ],
        "responses": {
          "200": {
            "description": "Template list with metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "templates": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TemplatePreview"
                      }
                    }
                  }
                },
                "example": {
                  "templates": [
                    {
                      "id": "department",
                      "name": "Department",
                      "description": "Team information, services, and resources",
                      "columnCount": 3,
                      "widgetCount": 12,
                      "widgetTypes": [
                        "heading",
                        "text",
                        "image",
                        "links"
                      ],
                      "complexity": "medium",
                      "hasHeaderRow": true,
                      "hasSidebars": false
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "operationId": "save-as-template",
        "summary": "Save page as template",
        "description": "Saves an existing page as a reusable template. Copies the page structure and media to the templates folder.",
        "tags": [
          "Templates"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TemplateSaveRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Template saved successfully (201 Created)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "templateId": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/templates/{id}": {
      "get": {
        "operationId": "get-template",
        "summary": "Get template details",
        "description": "Returns the full template data including layout and widgets",
        "tags": [
          "Templates"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Template ID (e.g., 'department', 'event')",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Template data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "template": {
                      "$ref": "#/components/schemas/Page"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "operationId": "delete-template",
        "summary": "Delete template",
        "description": "Deletes a custom template. Built-in templates cannot be deleted.",
        "tags": [
          "Templates"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Template ID to delete",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessAck"
                }
              }
            }
          },
          "400": {
            "description": "Cannot delete built-in template",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/users": {
      "post": {
        "operationId": "get-users-by-id",
        "summary": "Resolve several users by id",
        "description": "Bulk profile lookup. POST rather than GET because the id list can be long enough to run into URL limits — it reads nothing and writes nothing.\n\nAn empty list returns an empty result rather than every user.\n\nEVERY LOGGED-IN USER MAY CALL THIS. What comes back is filtered per property by the visibility scope each user set in Personal info, so a field marked private is omitted rather than returned. uid, displayName, avatarUrl, groups and status are always present; everything else depends on the subject's own settings.\n\nProperties synced from LDAP or OIDC are included too, and those are never enumerated in a fixed list — whatever the directory syncs can appear here, subject to the same scope check.",
        "tags": [
          "People"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "userIds"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Profiles for the ids that exist. Unknown ids are omitted rather than reported.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "users": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/UserProfile"
                      }
                    }
                  },
                  "required": [
                    "users"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "The lookup failed."
          }
        }
      }
    },
    "/api/users/fields": {
      "get": {
        "operationId": "get-user-fields",
        "summary": "Filterable and displayable user fields",
        "description": "The account properties the People widget can filter and display, in editor order. This is the FIELD CATALOGUE, not anyone's data — it describes what fields exist, never their values.\n\n'group' is included as a pseudo-field of type select alongside the real account properties.",
        "tags": [
          "People"
        ],
        "responses": {
          "200": {
            "description": "Available fields",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "fields": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "text",
                              "date",
                              "select"
                            ]
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "fields"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Fields could not be read."
          }
        }
      }
    },
    "/api/users/groups": {
      "get": {
        "operationId": "get-groups",
        "summary": "All groups on the instance",
        "description": "Every group, sorted case-insensitively by display name. Used to populate filter dropdowns.\n\nAvailable to every logged-in user, and NOT scoped to the caller's own memberships — this is the full group list of the instance.",
        "tags": [
          "People"
        ],
        "responses": {
          "200": {
            "description": "All groups",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "groups": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "displayName": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "groups"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Groups could not be read."
          }
        }
      }
    },
    "/api/users/search": {
      "get": {
        "operationId": "search-users",
        "summary": "Find users by name or id",
        "description": "Substring search over display names and user ids.\n\nA query shorter than two characters returns an empty list with an explanatory message and HTTP 200 — not a 400. Enumerating the whole directory one letter at a time is the thing this prevents.\n\nEVERY LOGGED-IN USER MAY CALL THIS. What comes back is filtered per property by the visibility scope each user set in Personal info, so a field marked private is omitted rather than returned. uid, displayName, avatarUrl, groups and status are always present; everything else depends on the subject's own settings.\n\nProperties synced from LDAP or OIDC are included too, and those are never enumerated in a fixed list — whatever the directory syncs can appear here, subject to the same scope check.",
        "tags": [
          "People"
        ],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 2
            },
            "description": "Under two characters yields an empty result rather than an error."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 50
            },
            "description": "Clamped to 50 server-side; asking for more silently gets 50."
          }
        ],
        "responses": {
          "200": {
            "description": "Matching users, or an empty list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "users": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/UserProfile"
                      }
                    },
                    "message": {
                      "type": "string",
                      "description": "Present only when the query was too short."
                    }
                  },
                  "required": [
                    "users"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "The search failed."
          }
        }
      }
    },
    "/api/v1/pages": {
      "get": {
        "operationId": "ocs-list-pages",
        "summary": "List pages",
        "tags": [
          "External API"
        ],
        "description": "External entry point, mounted under /ocs/v2.php/apps/intravox. It reaches the same handler as the internal route and returns the same bare JSON — no OCS envelope, no ?format=xml. Writes require the `OCS-APIRequest: true` header or answer 412.\n\nThe listing, with the same cap, headers and opt-in cursor paging as the internal route.\n\nALSO AVAILABLE ON THE OCS MOUNT at /ocs/v2.php/apps/intravox, which is the base an external integrator should use. Only the /api/v1/* operations are mounted there — every other path in this document 404s on the OCS prefix, /api/health included. Despite the /ocs/ path there is no {ocs:{meta,data}} envelope: no IntraVox controller extends OCSController, so the body is the same bare JSON as on the app mount. Verified against a running instance.",
        "security": [
          {
            "basic_auth": [],
            "ocs_request_header": []
          },
          {
            "bearer_auth": [],
            "ocs_request_header": []
          }
        ],
        "responses": {
          "200": {
            "description": "The pages the caller may read.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PageSummary"
                  }
                },
                "example": [
                  {
                    "uniqueId": "page-9f2c14ab",
                    "title": "Welkom",
                    "modified": 1756123456,
                    "status": "published",
                    "permissions": {
                      "canRead": true,
                      "canWrite": true,
                      "canCreate": true,
                      "canDelete": true,
                      "canShare": false,
                      "raw": 27
                    }
                  },
                  {
                    "uniqueId": "page-3d81e07f",
                    "title": "Personeelsgids",
                    "modified": 1756039001,
                    "status": "published",
                    "permissions": {
                      "canRead": true,
                      "canWrite": true,
                      "canCreate": true,
                      "canDelete": true,
                      "canShare": false,
                      "raw": 27
                    }
                  },
                  {
                    "uniqueId": "page-c05b7712",
                    "title": "Reisbeleid 2027",
                    "modified": 1755998877,
                    "status": "draft",
                    "permissions": {
                      "canRead": true,
                      "canWrite": true,
                      "canCreate": true,
                      "canDelete": false,
                      "canShare": false,
                      "raw": 27
                    }
                  }
                ]
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Too Many Requests. Nextcloud's own brute-force protection, triggered by repeated FAILED AUTHENTICATION from one address — not an IntraVox rate limit, and it applies to every authenticated endpoint in this document regardless of whether one is declared. Once tripped it keeps answering 429 even for correct credentials until the window expires, so a client that retries a bad token in a loop locks itself out. Fix the credentials and wait rather than retrying.",
            "content": {
              "text/xml": {
                "schema": {
                  "type": "string",
                  "description": "An OCS error envelope in XML. Produced by Nextcloud before the app is reached, so it does not follow this API's JSON error shape."
                }
              }
            }
          }
        },
        "servers": [
          {
            "url": "https://{nextcloud_host}/ocs/v2.php/apps/intravox",
            "description": "External API mount. These operations are registered only in the ocs block of appinfo/routes.php; the app mount returns 404 for them.",
            "variables": {
              "nextcloud_host": {
                "default": "localhost",
                "description": "Nextcloud server hostname"
              }
            }
          }
        ]
      },
      "post": {
        "operationId": "ocs-create-page",
        "summary": "Create a page",
        "tags": [
          "External API"
        ],
        "description": "External entry point, mounted under /ocs/v2.php/apps/intravox. It reaches the same handler as the internal route and returns the same bare JSON — no OCS envelope, no ?format=xml. Writes require the `OCS-APIRequest: true` header or answer 412.\n\nThe primary ingest endpoint for a migration. Rate limited to 10 per minute per user; see the Rate Limiting section of the API reference for the documented way around that during a bulk import.\n\nALSO AVAILABLE ON THE OCS MOUNT at /ocs/v2.php/apps/intravox, which is the base an external integrator should use. Only the /api/v1/* operations are mounted there — every other path in this document 404s on the OCS prefix, /api/health included. Despite the /ocs/ path there is no {ocs:{meta,data}} envelope: no IntraVox controller extends OCSController, so the body is the same bare JSON as on the app mount. Verified against a running instance.",
        "security": [
          {
            "basic_auth": [],
            "ocs_request_header": []
          },
          {
            "bearer_auth": [],
            "ocs_request_header": []
          }
        ],
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                },
                "example": {
                  "uniqueId": "page-c05b7712",
                  "title": "Reisbeleid 2027",
                  "language": "nl",
                  "parentId": "page-3d81e07f",
                  "status": "draft",
                  "modified": 1756123456,
                  "layout": {
                    "columns": 2,
                    "rows": []
                  },
                  "permissions": {
                    "canRead": true,
                    "canWrite": true,
                    "canCreate": true,
                    "canDelete": true,
                    "canShare": false,
                    "raw": 27
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "412": {
            "description": "The OCS-APIRequest header was missing."
          },
          "429": {
            "description": "Rate limit exceeded."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PageCreate"
              },
              "example": {
                "title": "Reisbeleid 2027",
                "parentId": "page-3d81e07f",
                "language": "nl"
              }
            }
          }
        },
        "servers": [
          {
            "url": "https://{nextcloud_host}/ocs/v2.php/apps/intravox",
            "description": "External API mount. These operations are registered only in the ocs block of appinfo/routes.php; the app mount returns 404 for them.",
            "variables": {
              "nextcloud_host": {
                "default": "localhost",
                "description": "Nextcloud server hostname"
              }
            }
          }
        ]
      }
    },
    "/api/v1/pages/{id}": {
      "get": {
        "operationId": "ocs-get-page",
        "summary": "Read one page",
        "tags": [
          "External API"
        ],
        "description": "External entry point, mounted under /ocs/v2.php/apps/intravox. It reaches the same handler as the internal route and returns the same bare JSON — no OCS envelope, no ?format=xml. Writes require the `OCS-APIRequest: true` header or answer 412.\n\nReturns the full page including layout and widgets.\n\nALSO AVAILABLE ON THE OCS MOUNT at /ocs/v2.php/apps/intravox, which is the base an external integrator should use. Only the /api/v1/* operations are mounted there — every other path in this document 404s on the OCS prefix, /api/health included. Despite the /ocs/ path there is no {ocs:{meta,data}} envelope: no IntraVox controller extends OCSController, so the body is the same bare JSON as on the app mount. Verified against a running instance.\n\nThe response carries `baseVersion`; send it back on PUT to avoid overwriting a concurrent edit.",
        "security": [
          {
            "basic_auth": [],
            "ocs_request_header": []
          },
          {
            "bearer_auth": [],
            "ocs_request_header": []
          }
        ],
        "responses": {
          "200": {
            "description": "The page.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                },
                "example": {
                  "uniqueId": "page-3d81e07f",
                  "title": "Personeelsgids",
                  "language": "nl",
                  "status": "published",
                  "modified": 1756039001,
                  "parentId": null,
                  "layout": {
                    "columns": 2,
                    "rows": [
                      {
                        "widgets": [
                          {
                            "type": "heading",
                            "content": "Welkom bij het team",
                            "level": 2,
                            "column": 0,
                            "order": 0
                          },
                          {
                            "type": "text",
                            "content": "<p>Alles wat je nodig hebt om te beginnen.</p>",
                            "column": 0,
                            "order": 1
                          },
                          {
                            "type": "text",
                            "content": "<p>Vragen? Mail HR.</p>",
                            "column": 1,
                            "order": 0
                          }
                        ]
                      }
                    ]
                  },
                  "permissions": {
                    "canRead": true,
                    "canWrite": true,
                    "canCreate": true,
                    "canDelete": true,
                    "canShare": false,
                    "raw": 27
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Too Many Requests. Nextcloud's own brute-force protection, triggered by repeated FAILED AUTHENTICATION from one address — not an IntraVox rate limit, and it applies to every authenticated endpoint in this document regardless of whether one is declared. Once tripped it keeps answering 429 even for correct credentials until the window expires, so a client that retries a bad token in a loop locks itself out. Fix the credentials and wait rather than retrying.",
            "content": {
              "text/xml": {
                "schema": {
                  "type": "string",
                  "description": "An OCS error envelope in XML. Produced by Nextcloud before the app is reached, so it does not follow this API's JSON error shape."
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "servers": [
          {
            "url": "https://{nextcloud_host}/ocs/v2.php/apps/intravox",
            "description": "External API mount. These operations are registered only in the ocs block of appinfo/routes.php; the app mount returns 404 for them.",
            "variables": {
              "nextcloud_host": {
                "default": "localhost",
                "description": "Nextcloud server hostname"
              }
            }
          }
        ]
      },
      "put": {
        "operationId": "ocs-update-page",
        "summary": "Replace a page",
        "tags": [
          "External API"
        ],
        "description": "External entry point, mounted under /ocs/v2.php/apps/intravox. It reaches the same handler as the internal route and returns the same bare JSON — no OCS envelope, no ?format=xml. Writes require the `OCS-APIRequest: true` header or answer 412.\n\nWrites the whole page; fields absent from the body are dropped by the sanitizer.\n\nALSO AVAILABLE ON THE OCS MOUNT at /ocs/v2.php/apps/intravox, which is the base an external integrator should use. Only the /api/v1/* operations are mounted there — every other path in this document 404s on the OCS prefix, /api/health included. Despite the /ocs/ path there is no {ocs:{meta,data}} envelope: no IntraVox controller extends OCSController, so the body is the same bare JSON as on the app mount. Verified against a running instance.\n\nCONCURRENCY. A read returns `baseVersion`, the file's modification time at that moment. Send it back in the PUT body and a write that started from an older copy is refused with 409 instead of silently overwriting the other edit.\n\nOmitting it is allowed and is NOT treated as a conflict — an importer or a script that never read the page has nothing to compare. That is a deliberate choice with a consequence worth knowing: a client that leaves `baseVersion` out gets last-write-wins. Interactive editors should always send it.\n\nThe value is never persisted; it is stripped from the payload before the page is written.",
        "security": [
          {
            "basic_auth": [],
            "ocs_request_header": []
          },
          {
            "bearer_auth": [],
            "ocs_request_header": []
          }
        ],
        "responses": {
          "200": {
            "description": "The page as stored.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Conflict: the submitted baseVersion predates the stored file, so someone else saved while this copy was being edited. Re-read the page and re-apply the change; retrying the same body will keep failing."
          },
          "412": {
            "description": "The OCS-APIRequest header was missing."
          },
          "429": {
            "description": "Too Many Requests. Nextcloud's own brute-force protection, triggered by repeated FAILED AUTHENTICATION from one address — not an IntraVox rate limit, and it applies to every authenticated endpoint in this document regardless of whether one is declared. Once tripped it keeps answering 429 even for correct credentials until the window expires, so a client that retries a bad token in a loop locks itself out. Fix the credentials and wait rather than retrying.",
            "content": {
              "text/xml": {
                "schema": {
                  "type": "string",
                  "description": "An OCS error envelope in XML. Produced by Nextcloud before the app is reached, so it does not follow this API's JSON error shape."
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PageUpdate"
              },
              "example": {
                "title": "Personeelsgids (herzien)",
                "layout": {
                  "columns": 2,
                  "rows": [
                    {
                      "widgets": [
                        {
                          "type": "heading",
                          "content": "Welkom bij het team",
                          "level": 2,
                          "column": 0,
                          "order": 0
                        },
                        {
                          "type": "text",
                          "content": "<p>Alles wat je nodig hebt om te beginnen.</p>",
                          "column": 0,
                          "order": 1
                        },
                        {
                          "type": "text",
                          "content": "<p>Vragen? Mail HR.</p>",
                          "column": 1,
                          "order": 0
                        }
                      ]
                    }
                  ]
                }
              }
            }
          }
        },
        "servers": [
          {
            "url": "https://{nextcloud_host}/ocs/v2.php/apps/intravox",
            "description": "External API mount. These operations are registered only in the ocs block of appinfo/routes.php; the app mount returns 404 for them.",
            "variables": {
              "nextcloud_host": {
                "default": "localhost",
                "description": "Nextcloud server hostname"
              }
            }
          }
        ]
      },
      "delete": {
        "operationId": "ocs-delete-page",
        "summary": "Delete a page",
        "tags": [
          "External API"
        ],
        "description": "External entry point, mounted under /ocs/v2.php/apps/intravox. It reaches the same handler as the internal route and returns the same bare JSON — no OCS envelope, no ?format=xml. Writes require the `OCS-APIRequest: true` header or answer 412.\n\nDeleting an already deleted page is not an error for the bulk endpoints, but here it answers 404.\n\nALSO AVAILABLE ON THE OCS MOUNT at /ocs/v2.php/apps/intravox, which is the base an external integrator should use. Only the /api/v1/* operations are mounted there — every other path in this document 404s on the OCS prefix, /api/health included. Despite the /ocs/ path there is no {ocs:{meta,data}} envelope: no IntraVox controller extends OCSController, so the body is the same bare JSON as on the app mount. Verified against a running instance.",
        "security": [
          {
            "basic_auth": [],
            "ocs_request_header": []
          },
          {
            "bearer_auth": [],
            "ocs_request_header": []
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessAck"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "412": {
            "description": "The OCS-APIRequest header was missing."
          },
          "429": {
            "description": "Rate limit exceeded."
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "servers": [
          {
            "url": "https://{nextcloud_host}/ocs/v2.php/apps/intravox",
            "description": "External API mount. These operations are registered only in the ocs block of appinfo/routes.php; the app mount returns 404 for them.",
            "variables": {
              "nextcloud_host": {
                "default": "localhost",
                "description": "Nextcloud server hostname"
              }
            }
          }
        ]
      }
    },
    "/api/v1/pages/{pageId}/media": {
      "get": {
        "operationId": "ocs-list-media",
        "summary": "List a page's media",
        "tags": [
          "External API"
        ],
        "description": "External entry point, mounted under /ocs/v2.php/apps/intravox. It reaches the same handler as the internal route and returns the same bare JSON — no OCS envelope, no ?format=xml. Writes require the `OCS-APIRequest: true` header or answer 412.\n\nCapped, with the same truncation headers as the internal route.\n\nALSO AVAILABLE ON THE OCS MOUNT at /ocs/v2.php/apps/intravox, which is the base an external integrator should use. Only the /api/v1/* operations are mounted there — every other path in this document 404s on the OCS prefix, /api/health included. Despite the /ocs/ path there is no {ocs:{meta,data}} envelope: no IntraVox controller extends OCSController, so the body is the same bare JSON as on the app mount. Verified against a running instance.",
        "security": [
          {
            "basic_auth": [],
            "ocs_request_header": []
          },
          {
            "bearer_auth": [],
            "ocs_request_header": []
          }
        ],
        "responses": {
          "200": {
            "description": "The media entries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "media"
                  ],
                  "properties": {
                    "media": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MediaFile"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Too Many Requests. Nextcloud's own brute-force protection, triggered by repeated FAILED AUTHENTICATION from one address — not an IntraVox rate limit, and it applies to every authenticated endpoint in this document regardless of whether one is declared. Once tripped it keeps answering 429 even for correct credentials until the window expires, so a client that retries a bad token in a loop locks itself out. Fix the credentials and wait rather than retrying.",
            "content": {
              "text/xml": {
                "schema": {
                  "type": "string",
                  "description": "An OCS error envelope in XML. Produced by Nextcloud before the app is reached, so it does not follow this API's JSON error shape."
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "servers": [
          {
            "url": "https://{nextcloud_host}/ocs/v2.php/apps/intravox",
            "description": "External API mount. These operations are registered only in the ocs block of appinfo/routes.php; the app mount returns 404 for them.",
            "variables": {
              "nextcloud_host": {
                "default": "localhost",
                "description": "Nextcloud server hostname"
              }
            }
          }
        ]
      },
      "post": {
        "operationId": "ocs-upload-media",
        "summary": "Upload media to a page",
        "tags": [
          "External API"
        ],
        "description": "External entry point, mounted under /ocs/v2.php/apps/intravox. It reaches the same handler as the internal route and returns the same bare JSON — no OCS envelope, no ?format=xml. Writes require the `OCS-APIRequest: true` header or answer 412.\n\nmultipart/form-data. Large files are better sent over WebDAV; see the migration section of the API reference.\n\nALSO AVAILABLE ON THE OCS MOUNT at /ocs/v2.php/apps/intravox, which is the base an external integrator should use. Only the /api/v1/* operations are mounted there — every other path in this document 404s on the OCS prefix, /api/health included. Despite the /ocs/ path there is no {ocs:{meta,data}} envelope: no IntraVox controller extends OCSController, so the body is the same bare JSON as on the app mount. Verified against a running instance.",
        "security": [
          {
            "basic_auth": [],
            "ocs_request_header": []
          },
          {
            "bearer_auth": [],
            "ocs_request_header": []
          }
        ],
        "responses": {
          "201": {
            "description": "Uploaded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaFile"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "412": {
            "description": "The OCS-APIRequest header was missing."
          },
          "413": {
            "description": "File exceeds the configured maximum."
          },
          "429": {
            "description": "Too Many Requests. Nextcloud's own brute-force protection, triggered by repeated FAILED AUTHENTICATION from one address — not an IntraVox rate limit, and it applies to every authenticated endpoint in this document regardless of whether one is declared. Once tripped it keeps answering 429 even for correct credentials until the window expires, so a client that retries a bad token in a loop locks itself out. Fix the credentials and wait rather than retrying.",
            "content": {
              "text/xml": {
                "schema": {
                  "type": "string",
                  "description": "An OCS error envelope in XML. Produced by Nextcloud before the app is reached, so it does not follow this API's JSON error shape."
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "media": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "servers": [
          {
            "url": "https://{nextcloud_host}/ocs/v2.php/apps/intravox",
            "description": "External API mount. These operations are registered only in the ocs block of appinfo/routes.php; the app mount returns 404 for them.",
            "variables": {
              "nextcloud_host": {
                "default": "localhost",
                "description": "Nextcloud server hostname"
              }
            }
          }
        ]
      }
    },
    "/api/v1/pages/{pageId}/media/{filename}": {
      "get": {
        "operationId": "ocs-get-media",
        "summary": "Download one media file",
        "tags": [
          "External API"
        ],
        "description": "External entry point, mounted under /ocs/v2.php/apps/intravox. It reaches the same handler as the internal route and returns the same bare JSON — no OCS envelope, no ?format=xml. Writes require the `OCS-APIRequest: true` header or answer 412.\n\nStreams the file itself, not JSON.\n\nALSO AVAILABLE ON THE OCS MOUNT at /ocs/v2.php/apps/intravox, which is the base an external integrator should use. Only the /api/v1/* operations are mounted there — every other path in this document 404s on the OCS prefix, /api/health included. Despite the /ocs/ path there is no {ocs:{meta,data}} envelope: no IntraVox controller extends OCSController, so the body is the same bare JSON as on the app mount. Verified against a running instance.",
        "security": [
          {
            "basic_auth": [],
            "ocs_request_header": []
          },
          {
            "bearer_auth": [],
            "ocs_request_header": []
          }
        ],
        "responses": {
          "200": {
            "description": "The file.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Too Many Requests. Nextcloud's own brute-force protection, triggered by repeated FAILED AUTHENTICATION from one address — not an IntraVox rate limit, and it applies to every authenticated endpoint in this document regardless of whether one is declared. Once tripped it keeps answering 429 even for correct credentials until the window expires, so a client that retries a bad token in a loop locks itself out. Fix the credentials and wait rather than retrying.",
            "content": {
              "text/xml": {
                "schema": {
                  "type": "string",
                  "description": "An OCS error envelope in XML. Produced by Nextcloud before the app is reached, so it does not follow this API's JSON error shape."
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "filename",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "servers": [
          {
            "url": "https://{nextcloud_host}/ocs/v2.php/apps/intravox",
            "description": "External API mount. These operations are registered only in the ocs block of appinfo/routes.php; the app mount returns 404 for them.",
            "variables": {
              "nextcloud_host": {
                "default": "localhost",
                "description": "Nextcloud server hostname"
              }
            }
          }
        ]
      }
    },
    "/feed/{token}": {
      "get": {
        "operationId": "get-feed",
        "summary": "Get RSS feed",
        "description": "Returns an RSS 2.0 feed of IntraVox pages accessible to the token owner. Supports conditional requests via ETag and If-Modified-Since headers.",
        "tags": [
          "RSS Feed"
        ],
        "security": [
          {}
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 64,
              "maxLength": 64
            },
            "description": "64-character alphanumeric feed token"
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "description": "ETag from a previous response for conditional request"
          },
          {
            "name": "If-Modified-Since",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "description": "Last-Modified value from a previous response"
          }
        ],
        "responses": {
          "200": {
            "description": "RSS 2.0 XML feed",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              },
              "Last-Modified": {
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "example": "public, max-age=300, must-revalidate"
                }
              }
            },
            "content": {
              "application/rss+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "304": {
            "description": "Not modified (conditional request)"
          },
          "404": {
            "description": "Invalid token or feed not found"
          },
          "429": {
            "description": "Rate limit exceeded (30 per 60 seconds per client). Anonymous endpoints are limited per address rather than per user, so several visitors behind one NAT share the budget."
          }
        }
      }
    },
    "/feed/{token}/media/{pageId}/{filename}": {
      "get": {
        "operationId": "get-feed-media",
        "summary": "Get feed media file",
        "description": "Serves media files (images) referenced in feed items, authenticated by the feed token.",
        "tags": [
          "RSS Feed"
        ],
        "security": [
          {}
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 64,
              "maxLength": 64
            },
            "description": "64-character alphanumeric feed token"
          },
          {
            "name": "pageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Unique ID of the page"
          },
          {
            "name": "filename",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Media filename"
          }
        ],
        "responses": {
          "200": {
            "description": "Media file",
            "content": {
              "image/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Invalid token or media not found"
          },
          "429": {
            "description": "Rate limit exceeded (60 per 60 seconds per client). Anonymous endpoints are limited per address rather than per user, so several visitors behind one NAT share the budget."
          }
        }
      }
    },
    "/s/{shareToken}": {
      "get": {
        "operationId": "open-share",
        "summary": "Open a public share in the browser",
        "tags": [
          "Public Share"
        ],
        "security": [
          {}
        ],
        "description": "A browser page, not a JSON resource — documented because it is the other half of a contract the API already refers to. GET /api/share/{token}/page/{uniqueId} can answer 401 with `passwordRequired: true`, and without this pair a client is told it needs a password and never told where to send it.\n\nPassword-protected shares serve a form here; unprotected ones serve the page directly.",
        "responses": {
          "200": {
            "description": "The share page, or the password form.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No such share, or the token does not point into IntraVox."
          },
          "429": {
            "description": "Rate limit exceeded (60 per 60 seconds per client). Anonymous endpoints are limited per address rather than per user, so several visitors behind one NAT share the budget."
          }
        },
        "parameters": [
          {
            "name": "shareToken",
            "in": "path",
            "required": true,
            "description": "The public share token from the link.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/s/{shareToken}/authenticate": {
      "post": {
        "operationId": "authenticate-share",
        "summary": "Submit a share password",
        "tags": [
          "Public Share"
        ],
        "security": [
          {}
        ],
        "description": "Form POST, not JSON. On success the password is kept in the session, which is what makes the subsequent /api/share/{token}/... calls succeed — so an API client needs a cookie jar here, not a token.\n\nFailure is deliberately slow and throttled: the attempt is registered with brute-force protection and the response is delayed 100-300ms, so timing does not reveal whether a token exists.",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "password"
                ],
                "properties": {
                  "password": {
                    "type": "string"
                  },
                  "returnQuery": {
                    "type": "string",
                    "description": "Query string to restore after the redirect."
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "shareToken",
            "in": "path",
            "required": true,
            "description": "The public share token from the link.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Password rejected; the form is served again.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "303": {
            "description": "Password accepted; redirect to the share."
          },
          "429": {
            "description": "Too many attempts; brute-force protection has kicked in.",
            "content": {
              "text/xml": {
                "schema": {
                  "type": "string",
                  "description": "An OCS error envelope in XML. Produced by Nextcloud before the app is reached, so it does not follow this API's JSON error shape."
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "basic_auth": {
        "type": "http",
        "scheme": "basic"
      },
      "bearer_auth": {
        "type": "http",
        "scheme": "bearer"
      },
      "ocs_request_header": {
        "type": "apiKey",
        "in": "header",
        "name": "OCS-APIRequest",
        "description": "Required on writes. Nextcloud's CSRF check passes as soon as this header is present and non-empty, and without it a POST/PUT/DELETE is refused with 412 'CSRF check failed' — measured, not assumed. Harmless on reads; send it always."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Authentication required",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Permission denied",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "BadRequest": {
        "description": "Invalid request",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "PageSummary": {
        "type": "object",
        "properties": {
          "uniqueId": {
            "type": "string",
            "description": "Unique page identifier"
          },
          "title": {
            "type": "string"
          },
          "modified": {
            "type": "integer",
            "description": "Unix timestamp of last modification"
          },
          "permissions": {
            "$ref": "#/components/schemas/Permissions"
          },
          "status": {
            "type": "string",
            "description": "Publication status. Draft, scheduled and expired pages are only returned to callers with write permission."
          }
        },
        "required": [
          "uniqueId",
          "title",
          "modified",
          "status",
          "permissions"
        ],
        "description": "One row of the page listing. Every field here is always present; the full page body (layout, widgets) comes from GET /api/pages/{id}.",
        "additionalProperties": false
      },
      "Page": {
        "type": "object",
        "properties": {
          "uniqueId": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "language": {
            "type": "string",
            "enum": [
              "nl",
              "en",
              "de",
              "fr"
            ]
          },
          "layout": {
            "$ref": "#/components/schemas/PageLayout"
          },
          "permissions": {
            "$ref": "#/components/schemas/Permissions"
          },
          "breadcrumb": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BreadcrumbItem"
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "published"
            ],
            "description": "Stored publication status. A page with a publish date is governed by that date instead — see effectivePublishState."
          },
          "effectivePublishState": {
            "type": "string",
            "enum": [
              "draft",
              "scheduled",
              "published",
              "expired"
            ],
            "description": "Effective publication state, evaluated live from the stored status plus the configured publish/expiration MetaVox dates. Only 'published' is visible to readers; the other states are hidden from them but returned to users with write permission."
          },
          "publicationDateActive": {
            "type": "boolean",
            "description": "True when a publish or expiration date is set for this page, meaning that date governs publication and the manual draft/published status is ignored."
          },
          "parentId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Unique id of the parent page; null at the language root."
          },
          "modified": {
            "type": "integer",
            "description": "Unix timestamp of the last write."
          },
          "baseVersion": {
            "type": "integer",
            "description": "Optimistic-locking token: the file's mtime when this copy was read. Send it back on PUT and the write is refused with 409 if someone else saved in the meantime. TRANSPORT ONLY — it is never stored, and it is regenerated on every read."
          }
        },
        "additionalProperties": true,
        "description": "A page as stored, plus fields computed at read time.\n\nThe properties below are the ones a client can rely on. The object is deliberately open: the body is the saved page document, so optional keys (parentId, modified, department, and anything a future widget adds) appear when present. Do not generate a strict model that discards unknown fields.",
        "required": [
          "uniqueId",
          "title",
          "language",
          "layout",
          "permissions"
        ]
      },
      "PageCreate": {
        "type": "object",
        "required": [
          "title"
        ],
        "properties": {
          "title": {
            "type": "string"
          },
          "parentId": {
            "type": "string",
            "description": "Parent page unique ID"
          },
          "language": {
            "type": "string"
          }
        }
      },
      "PageUpdate": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "layout": {
            "$ref": "#/components/schemas/PageLayout"
          },
          "baseVersion": {
            "type": "integer",
            "description": "The value from the last read. Omit only when there was no read to compare against."
          }
        }
      },
      "PageLayout": {
        "type": "object",
        "properties": {
          "columns": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5
          },
          "headerRow": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "backgroundColor": {
                "type": "string"
              },
              "widgets": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Widget"
                }
              }
            }
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Row"
            }
          },
          "sideColumns": {
            "type": "object",
            "properties": {
              "left": {
                "$ref": "#/components/schemas/SideColumn"
              },
              "right": {
                "$ref": "#/components/schemas/SideColumn"
              }
            }
          }
        }
      },
      "Row": {
        "type": "object",
        "properties": {
          "columns": {
            "type": "integer"
          },
          "backgroundColor": {
            "type": "string"
          },
          "widgets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Widget"
            }
          }
        }
      },
      "SideColumn": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "backgroundColor": {
            "type": "string"
          },
          "widgets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Widget"
            }
          }
        }
      },
      "Widget": {
        "type": "object",
        "description": "A widget on an IntraVox page. The set of properties that are honored by the server-side sanitizer depends on `type` — see `WidgetConfig` for the widget-specific schemas.",
        "required": [
          "type"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "description": "Widget type — must be one of the values accepted by PageService::ALLOWED_WIDGET_TYPES. Unknown types are dropped on save.",
            "enum": [
              "text",
              "heading",
              "image",
              "links",
              "divider",
              "video",
              "news",
              "people",
              "calendar",
              "feed",
              "photo-story",
              "file-story"
            ]
          },
          "column": {
            "type": "integer",
            "description": "Column position within the row (1-based, clamped to row width)."
          },
          "order": {
            "type": "integer",
            "description": "Sort order within the column."
          },
          "content": {
            "type": "string",
            "description": "Body — used by text/heading widgets only."
          },
          "level": {
            "type": "integer",
            "minimum": 1,
            "maximum": 6,
            "description": "Heading level (1–6) — heading widget only."
          },
          "src": {
            "type": "string",
            "description": "Source URL/filename — image/video widgets."
          },
          "alt": {
            "type": "string",
            "description": "Alt text — image widget."
          },
          "url": {
            "type": "string",
            "description": "Target URL — link widget."
          },
          "text": {
            "type": "string",
            "description": "Display text — link widget."
          },
          "items": {
            "type": "array",
            "description": "List items — links widget.",
            "items": {
              "type": "object"
            }
          },
          "columns": {
            "type": "integer",
            "description": "Column count — links / news / photo-story."
          },
          "backgroundColor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Whitelisted CSS variable or 'transparent' — links / news / people / calendar / feed."
          },
          "title": {
            "type": "string",
            "description": "Widget header — news / video / people / calendar / feed."
          },
          "limit": {
            "type": "integer",
            "description": "Max items to render — news / people / calendar / feed / photo-story / file-story."
          },
          "sortBy": {
            "type": "string",
            "description": "Sort field — news / people / photo-story / file-story."
          },
          "sortOrder": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "description": "Sort direction."
          },
          "layout": {
            "type": "string",
            "description": "Layout variant — news (list/grid/carousel), feed (list/grid), people (card/list)."
          },
          "showImage": {
            "type": "boolean",
            "description": "news / feed."
          },
          "showDate": {
            "type": "boolean",
            "description": "news / feed."
          },
          "showExcerpt": {
            "type": "boolean",
            "description": "news / feed."
          },
          "excerptLength": {
            "type": "integer",
            "description": "news / feed character cap."
          },
          "autoplayInterval": {
            "type": "integer",
            "description": "Carousel autoplay seconds (0 = off) — news."
          },
          "filters": {
            "type": "array",
            "description": "MetaVox filter rows — news / people.",
            "items": {
              "type": "object"
            }
          },
          "filterOperator": {
            "type": "string",
            "enum": [
              "AND",
              "OR"
            ],
            "description": "MetaVox filter join logic — news / people."
          },
          "sourcePath": {
            "type": "string",
            "description": "Folder path — news source."
          },
          "sourcePageId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Page UUID — news source via PageTreeSelect."
          },
          "config": {
            "$ref": "#/components/schemas/WidgetConfig",
            "description": "Widget-specific nested config (photo-story / file-story)."
          },
          "provider": {
            "type": "string",
            "description": "video: embed / local."
          },
          "autoplay": {
            "type": "boolean",
            "description": "video."
          },
          "loop": {
            "type": "boolean",
            "description": "video."
          },
          "muted": {
            "type": "boolean",
            "description": "video."
          },
          "style": {
            "type": "string",
            "enum": [
              "solid",
              "dashed",
              "dotted"
            ],
            "description": "Divider line style."
          },
          "color": {
            "type": "string",
            "description": "Divider color (whitelisted CSS var)."
          },
          "height": {
            "type": "string",
            "description": "Divider height (e.g. '2px', '1rem')."
          },
          "calendarIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "calendar."
          },
          "externalIcsUrls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "calendar."
          },
          "dateRange": {
            "type": "string",
            "description": "calendar."
          },
          "showTime": {
            "type": "boolean",
            "description": "calendar."
          },
          "showLocation": {
            "type": "boolean",
            "description": "calendar."
          },
          "feedUrl": {
            "type": "string",
            "description": "feed."
          },
          "connectionId": {
            "type": "string",
            "description": "feed (LMS / external connector)."
          },
          "courseId": {
            "type": "string",
            "description": "feed (LMS)."
          },
          "showSource": {
            "type": "boolean",
            "description": "feed."
          },
          "openInNewTab": {
            "type": "boolean",
            "description": "feed."
          },
          "sourceType": {
            "type": "string",
            "description": "feed (rss / lms / …)."
          },
          "selectionMode": {
            "type": "string",
            "description": "people (manual / filter)."
          },
          "selectedUsers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "people."
          },
          "showFields": {
            "type": "object",
            "description": "people — per-field visibility booleans."
          },
          "viewerFilters": {
            "$ref": "#/components/schemas/ViewerFilters"
          }
        }
      },
      "WidgetConfig": {
        "type": "object",
        "description": "Nested config used by widgets with rich configuration surfaces. Currently photo-story and file-story.",
        "properties": {
          "folderPath": {
            "type": "string",
            "description": "Source folder path."
          },
          "mode": {
            "type": "string",
            "description": "Layout mode. photo-story: timeline/highlights/grid/on-this-day. file-story: timeline/tiles/list/grouped."
          },
          "style": {
            "type": "string",
            "enum": [
              "magazine",
              "apple",
              "travelogue"
            ],
            "description": "photo-story timeline style. Values: magazine, apple (shown in the UI as \"Clean grid\", the default), travelogue."
          },
          "limit": {
            "type": "integer",
            "description": "Optional total cap on rows/photos, applied in both pagination modes (photo-story + file-story). Blank = all."
          },
          "paginationMode": {
            "type": "string",
            "enum": [
              "infinite",
              "pages"
            ],
            "description": "Long-list handling (photo-story + file-story): infinite scroll (default) or Previous/Next page buttons. Page buttons apply where the widget paginates — file-story list/tiles, photo-story single-folder timeline/grid."
          },
          "pageSize": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500,
            "description": "Documents/photos per page in paginationMode=pages (photo-story + file-story). Default 20 (file-story) / 30 (photo-story)."
          },
          "columns": {
            "type": "integer",
            "minimum": 2,
            "maximum": 5,
            "description": "photo-story grid columns."
          },
          "showCaptions": {
            "type": "boolean",
            "description": "photo-story."
          },
          "showMap": {
            "type": "boolean",
            "description": "photo-story."
          },
          "showDayMaps": {
            "type": "boolean",
            "description": "photo-story (per-day mini-maps in timeline)."
          },
          "sortOrder": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ]
          },
          "sortBy": {
            "type": "string",
            "description": "mtime / name / size / any MetaVox field name."
          },
          "allMetaVoxFolders": {
            "type": "boolean",
            "description": "photo-story cross-folder mode (legacy flag, synced with empty folderPath)."
          },
          "metaVoxFilters": {
            "type": "array",
            "description": "Filter rows.",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string"
                },
                "op": {
                  "type": "string",
                  "enum": [
                    "equals",
                    "contains",
                    "in",
                    "year_equals"
                  ]
                },
                "value": {
                  "description": "string or string[]"
                }
              }
            }
          },
          "granularity": {
            "type": "string",
            "enum": [
              "day",
              "month",
              "year"
            ],
            "description": "file-story timeline bucket size."
          },
          "groupBy": {
            "type": "string",
            "description": "file-story group-by field (category / MetaVox field name)."
          },
          "dateField": {
            "type": "string",
            "description": "file-story: mtime or taken_at."
          },
          "visibleColumns": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "file-story visible-columns multi-select (date / size / path)."
          },
          "tileSize": {
            "type": "string",
            "enum": [
              "small",
              "medium",
              "large"
            ],
            "description": "file-story tiles mode."
          },
          "viewerFilters": {
            "$ref": "#/components/schemas/ViewerFilters"
          }
        }
      },
      "PageTreeNode": {
        "type": "object",
        "properties": {
          "uniqueId": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "children": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PageTreeNode"
            }
          },
          "permissions": {
            "$ref": "#/components/schemas/Permissions"
          }
        }
      },
      "BreadcrumbItem": {
        "type": "object",
        "properties": {
          "uniqueId": {
            "type": "string"
          },
          "title": {
            "type": "string"
          }
        }
      },
      "PageVersion": {
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "integer"
          },
          "label": {
            "type": "string"
          },
          "author": {
            "type": "string"
          },
          "size": {
            "type": "integer"
          }
        }
      },
      "Permissions": {
        "type": "object",
        "properties": {
          "canRead": {
            "type": "boolean"
          },
          "canWrite": {
            "type": "boolean"
          },
          "canCreate": {
            "type": "boolean"
          },
          "canDelete": {
            "type": "boolean"
          },
          "canShare": {
            "type": "boolean"
          },
          "raw": {
            "type": "integer",
            "description": "Nextcloud permissions bitmask"
          }
        }
      },
      "MediaFile": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "mimeType": {
            "type": "string"
          },
          "size": {
            "type": "integer"
          },
          "modified": {
            "type": "integer"
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "properties": {
          "uniqueId": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "excerpt": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "score": {
            "type": "number"
          }
        }
      },
      "NewsItem": {
        "type": "object",
        "properties": {
          "uniqueId": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "excerpt": {
            "type": "string"
          },
          "image": {
            "type": [
              "string",
              "null"
            ]
          },
          "imagePath": {
            "type": [
              "string",
              "null"
            ]
          },
          "modified": {
            "type": "integer"
          },
          "modifiedFormatted": {
            "type": "string"
          },
          "path": {
            "type": "string"
          }
        }
      },
      "Navigation": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NavigationItem"
            }
          }
        }
      },
      "NavigationItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "pageId": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "icon": {
            "type": "string"
          },
          "children": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NavigationItem"
            }
          }
        }
      },
      "Footer": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "content": {
            "type": "string"
          },
          "links": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Comment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "content": {
            "type": "string"
          },
          "authorId": {
            "type": "string"
          },
          "authorName": {
            "type": "string"
          },
          "created": {
            "type": "integer"
          },
          "modified": {
            "type": "integer"
          },
          "parentId": {
            "type": [
              "integer",
              "null"
            ]
          },
          "reactions": {
            "$ref": "#/components/schemas/Reactions"
          },
          "replies": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Comment"
            }
          }
        }
      },
      "Reactions": {
        "type": "object",
        "description": "Reaction state for one page or comment.\n\nNote the shape: 'reactions' is a flat emoji -> count map, and which of them the CALLING USER picked is a separate flat list in 'userReactions'. There is no per-emoji object and no userReacted flag — to render 'you reacted' you intersect the two yourself.\n\nEvery reaction endpoint returns this same complete state after the change, so a client replaces its local state rather than applying a delta.",
        "properties": {
          "reactions": {
            "type": "object",
            "description": "Emoji to count. Emoji with no reactions are absent rather than zero.",
            "additionalProperties": {
              "type": "integer",
              "minimum": 1
            }
          },
          "userReactions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The emoji the calling user has picked. In practice this holds AT MOST ONE entry: one reaction per user is enforced unconditionally (EngagementSettingsService::getSingleReactionPerUser() returns a hardcoded true), so reacting replaces any previous reaction rather than adding to it. It is an array for forward compatibility, not because multiple reactions occur. Empty for an anonymous or unauthenticated reader."
          }
        },
        "required": [
          "reactions",
          "userReactions"
        ]
      },
      "EngagementSettings": {
        "type": "object",
        "properties": {
          "commentsEnabled": {
            "type": "boolean"
          },
          "reactionsEnabled": {
            "type": "boolean"
          },
          "allowedReactions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "PublicationSettings": {
        "type": "object",
        "properties": {
          "publishedOnField": {
            "type": "string",
            "description": "MetaVox field name for publish date"
          },
          "depublishedOnField": {
            "type": "string",
            "description": "MetaVox field name for expiration date"
          }
        }
      },
      "TemplatePreview": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Template identifier (folder name)"
          },
          "name": {
            "type": "string",
            "description": "Template display name"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "created": {
            "type": "integer",
            "description": "Creation timestamp"
          },
          "createdBy": {
            "type": "string"
          },
          "columnCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5
          },
          "widgetCount": {
            "type": "integer"
          },
          "widgetTypes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of widget types used in template"
          },
          "complexity": {
            "type": "string",
            "enum": [
              "simple",
              "medium",
              "advanced"
            ]
          },
          "hasHeaderRow": {
            "type": "boolean"
          },
          "hasSidebars": {
            "type": "boolean"
          }
        }
      },
      "TemplateCreateFromRequest": {
        "type": "object",
        "required": [
          "templateId",
          "pageTitle"
        ],
        "properties": {
          "templateId": {
            "type": "string",
            "description": "Template folder name (e.g., 'department', 'event')"
          },
          "pageTitle": {
            "type": "string",
            "description": "Title for the new page"
          },
          "parentPath": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional parent folder path (e.g., '/teams')"
          }
        }
      },
      "TemplateSaveRequest": {
        "type": "object",
        "description": "Body for POST /api/templates. The field names are the ones the handler reads; an earlier version of this schema named pageId/name/description, which the endpoint rejects with 400.",
        "required": [
          "pageUniqueId",
          "templateTitle"
        ],
        "properties": {
          "pageUniqueId": {
            "type": "string",
            "description": "uniqueId of the page to save as a template."
          },
          "templateTitle": {
            "type": "string",
            "description": "Name of the new template."
          },
          "templateDescription": {
            "type": "string",
            "description": "Optional description."
          }
        }
      },
      "ViewerFilters": {
        "type": "object",
        "description": "Viewer-side facet configuration. When enabled, readers can narrow the widget's own results. Never applied on public share links.",
        "properties": {
          "enabled": {
            "type": "boolean",
            "description": "Whether visitors may filter this widget's results.",
            "default": false
          },
          "facets": {
            "type": "array",
            "maxItems": 12,
            "description": "Fields offered as filter groups, in display order.",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string",
                  "description": "Profile field name."
                },
                "label": {
                  "type": "string",
                  "description": "Label shown to visitors; falls back to the field's own label."
                },
                "limit": {
                  "type": "integer",
                  "minimum": 5,
                  "maximum": 100,
                  "default": 8,
                  "description": "Values shown before 'Show all'."
                },
                "collapsed": {
                  "type": "boolean",
                  "default": false,
                  "description": "Start this group collapsed."
                }
              }
            }
          },
          "searchFields": {
            "type": "array",
            "maxItems": 8,
            "items": {
              "type": "string"
            },
            "description": "Fields the free-text box searches. Display name is always included."
          },
          "searchEnabled": {
            "type": "boolean",
            "default": true
          },
          "layout": {
            "type": "string",
            "enum": [
              "sidebar",
              "top"
            ],
            "default": "sidebar",
            "description": "Panel beside or above the results."
          }
        }
      },
      "Translation": {
        "type": "object",
        "description": "Another language version of a page, from its translation group. Filtered against the caller's own Team Folder access.",
        "properties": {
          "language": {
            "type": "string",
            "example": "de"
          },
          "uniqueId": {
            "type": "string",
            "example": "page-1b2c3d4e-..."
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "published",
              "draft"
            ]
          }
        }
      },
      "PagedPageSummaries": {
        "type": "object",
        "description": "Returned ONLY when the caller paginates explicitly. Without a limit or cursor the endpoint answers with a bare array, unchanged.",
        "required": [
          "items",
          "hasMore",
          "nextCursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PageSummary"
            }
          },
          "hasMore": {
            "type": "boolean",
            "description": "Whether another page follows."
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Opaque cursor for the next page, or null when the walk is finished — so a loop on `while nextCursor` terminates without a special case. Do not construct or do arithmetic on this value: it encodes the sort key and may change."
          }
        }
      },
      "StoryPagination": {
        "type": "object",
        "description": "Offset paging, as the story widgets use it. Unlike the page listing this one does count rows, because a gallery scrolls a stable snapshot rather than walking a mutating tree.",
        "required": [
          "offset",
          "pageSize",
          "total",
          "hasMore",
          "sortOrder",
          "truncated"
        ],
        "properties": {
          "offset": {
            "type": "integer"
          },
          "pageSize": {
            "type": "integer",
            "description": "Clamped to 500 by the handler."
          },
          "total": {
            "type": "integer",
            "description": "Total matching rows, or the configured display limit when one caps the set."
          },
          "hasMore": {
            "type": "boolean"
          },
          "sortOrder": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ]
          },
          "truncated": {
            "type": "boolean",
            "description": "True when a scan cap stopped the count short, so `total` is a lower bound."
          }
        }
      },
      "StoryCapabilities": {
        "type": "object",
        "description": "What the server can do for this source: which optional backends are present.",
        "additionalProperties": true
      },
      "MetaVoxFieldList": {
        "type": "object",
        "description": "MetaVox is optional. When it is absent the endpoint answers 200 with an empty list and available=false rather than an error, so a widget can render without it.",
        "required": [
          "fields",
          "available"
        ],
        "properties": {
          "fields": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "available": {
            "type": "boolean"
          }
        }
      },
      "FileStoryListing": {
        "type": "object",
        "description": "Documents for the file-story widget. `timeline`+`granularity` appear only when mode=timeline; `groups` only when mode=grouped with a groupBy.",
        "required": [
          "files",
          "capabilities",
          "mode",
          "pagination"
        ],
        "properties": {
          "files": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "capabilities": {
            "$ref": "#/components/schemas/StoryCapabilities"
          },
          "mode": {
            "type": "string",
            "enum": [
              "flat",
              "timeline",
              "grouped"
            ]
          },
          "pagination": {
            "$ref": "#/components/schemas/StoryPagination"
          },
          "timeline": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "granularity": {
            "type": "string"
          },
          "groups": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "key",
                "label",
                "count",
                "files"
              ],
              "properties": {
                "key": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                },
                "files": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        }
      },
      "StoryCapabilitiesResponse": {
        "type": "object",
        "required": [
          "capabilities",
          "metaVoxAvailable"
        ],
        "properties": {
          "capabilities": {
            "$ref": "#/components/schemas/StoryCapabilities"
          },
          "metaVoxAvailable": {
            "type": "boolean"
          },
          "sourceIsFederated": {
            "type": "boolean",
            "description": "Whether the source folder lives on a federated share."
          },
          "sourceFederatedInfo": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          }
        }
      },
      "PhotoStoryListing": {
        "type": "object",
        "description": "Photos for the photo-story widget. The shape varies with `mode`: on-this-day returns photos+title without pagination, while timeline, grid and highlights go through the paged path and add `pagination`. Mode-specific extras (timeline groups, clusters) appear only for their mode.",
        "required": [
          "photos",
          "capabilities",
          "mode"
        ],
        "properties": {
          "photos": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "capabilities": {
            "$ref": "#/components/schemas/StoryCapabilities"
          },
          "mode": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "description": "A suggested heading derived from the set."
          },
          "map": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Map display settings, when geodata is available."
          },
          "pagination": {
            "$ref": "#/components/schemas/StoryPagination"
          },
          "timeline": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "granularity": {
            "type": "string"
          }
        }
      },
      "PhotoClusterListing": {
        "type": "object",
        "description": "Geographic clusters for the map view.",
        "required": [
          "clusters",
          "capabilities"
        ],
        "properties": {
          "clusters": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "capabilities": {
            "$ref": "#/components/schemas/StoryCapabilities"
          },
          "folder": {
            "type": "string"
          },
          "map": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "truncated": {
            "type": "boolean",
            "description": "True when the scan cap stopped short of the whole set."
          }
        }
      },
      "PhotoExif": {
        "type": "object",
        "description": "EXIF for one photo. Keys depend on what the file carries, so the set is open.",
        "required": [
          "file_id"
        ],
        "properties": {
          "file_id": {
            "type": "integer"
          }
        },
        "additionalProperties": true
      },
      "SuccessAck": {
        "type": "object",
        "required": [
          "success"
        ],
        "description": "A bare acknowledgement. Failures arrive as a 4xx with an error body, never as success:false here.",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        }
      },
      "SettingsSaveResult": {
        "type": "object",
        "required": [
          "success",
          "settings"
        ],
        "description": "Settings write. Returns the stored settings, so a client does not need a follow-up GET to learn what was actually persisted after validation.",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "settings": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "VideoDomainsSaveResult": {
        "type": "object",
        "required": [
          "success"
        ],
        "description": "Video-domain allow-list write. Entries that failed validation are named rather than silently dropped.",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "invalidDomains": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "FeedTokenState": {
        "type": "object",
        "required": [
          "hasToken"
        ],
        "description": "The RSS token state. `token` is only present right after issuing or regenerating one; a plain read never returns it again.",
        "properties": {
          "hasToken": {
            "type": "boolean"
          },
          "token": {
            "type": "string"
          },
          "feedUrl": {
            "type": "string"
          },
          "scope": {
            "type": "string"
          },
          "limit": {
            "type": "integer"
          },
          "config": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "PageMetadata": {
        "type": "object",
        "additionalProperties": true,
        "description": "MetaVox field values for one page. Keys are field ids configured on the instance, so the set is open by nature."
      },
      "AnalyticsSettings": {
        "type": "object",
        "required": [
          "success",
          "enabled",
          "retentionDays"
        ],
        "description": "Analytics collection settings. Admin only.",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "enabled": {
            "type": "boolean"
          },
          "retentionDays": {
            "type": "integer",
            "minimum": 7,
            "maximum": 365,
            "description": "Clamped to 7..365 by the handler; a value outside that range is silently brought inside it rather than rejected."
          }
        }
      },
      "AnalyticsStats": {
        "type": "object",
        "required": [
          "success"
        ],
        "additionalProperties": true,
        "description": "View statistics. The metric keys come from the storage layer and vary with what has been collected, so the set is open.",
        "properties": {
          "success": {
            "type": "boolean"
          }
        }
      },
      "TopPages": {
        "type": "object",
        "required": [
          "success",
          "pages",
          "period"
        ],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "pages": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "period": {
            "type": "integer",
            "description": "The window in days that was actually applied, after clamping."
          }
        }
      },
      "PageLock": {
        "type": [
          "object",
          "null"
        ],
        "description": "Who holds the editing lock on a page, or null when it is free.",
        "properties": {
          "pageUniqueId": {
            "type": "string"
          },
          "userId": {
            "type": "string",
            "description": "The account holding the lock."
          },
          "displayName": {
            "type": "string",
            "description": "Shown to the user who is blocked, so they know whom to ask."
          },
          "lockedSince": {
            "type": "integer",
            "description": "Unix timestamp the lock was taken."
          },
          "lastHeartbeat": {
            "type": "integer",
            "description": "Last refresh. A lock whose heartbeat has gone stale can be taken over."
          }
        }
      },
      "PageLockResult": {
        "type": "object",
        "required": [
          "success"
        ],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "lock": {
            "$ref": "#/components/schemas/PageLock"
          },
          "error": {
            "type": "string",
            "description": "Present on a refusal, naming the reason."
          }
        }
      },
      "LanguageList": {
        "type": "object",
        "description": "Which languages exist on the instance and which of them are enabled.",
        "properties": {
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Enabled language codes."
          },
          "availableLanguages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Everything that could be enabled."
          },
          "defaultLanguage": {
            "type": "string"
          }
        }
      },
      "LanguageEnableResult": {
        "type": "object",
        "description": "Result of changing the enabled set. Enabling a language creates its homepage, and that can partly fail without the whole call failing — hence the per-language results.",
        "properties": {
          "enabled": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The enabled set after the change."
          },
          "newlyEnabled": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "homepageResults": {
            "type": "object",
            "additionalProperties": true,
            "description": "Per newly enabled language, whether its homepage could be created."
          }
        }
      },
      "LanguageContentStatus": {
        "type": "object",
        "additionalProperties": true,
        "description": "Per language, whether it has content yet. The only endpoint here a non-admin may call, because the editor needs it to offer a language switch."
      },
      "LicenseStats": {
        "type": "object",
        "required": [
          "success"
        ],
        "description": "Subscription state and page usage. The verdict comes from the cached result of the last check, not from a live call to the licence server: this is read on every render of the admin settings, and a slow server would otherwise stall the page.",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "hasLicense": {
            "type": "boolean",
            "description": "Whether a key is configured at all."
          },
          "licenseValid": {
            "type": "boolean"
          },
          "licenseReason": {
            "type": "string",
            "description": "Why a key was refused — expired, unknown, already registered elsewhere, deactivated. Empty when the licence is valid."
          },
          "licenseValidUntil": {
            "type": [
              "string",
              "null"
            ],
            "description": "Expiry date, also present on a refusal so an expired key can name the date it lapsed."
          },
          "licenseKeyMasked": {
            "type": "string",
            "description": "The key with its middle replaced; the full key is never returned."
          },
          "licenseInfo": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "pageCounts": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Pages per language."
          },
          "totalPages": {
            "type": "integer"
          },
          "perLanguage": {
            "type": "boolean"
          },
          "supportedLanguages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "LicenseValidation": {
        "type": "object",
        "additionalProperties": true,
        "description": "The licence server's verdict. Contacts the server, so unlike the stats endpoint it can be slow or fail.",
        "properties": {
          "valid": {
            "type": "boolean"
          },
          "reason": {
            "type": "string",
            "description": "Present when refused."
          }
        }
      },
      "FeedItem": {
        "type": "object",
        "description": "One normalised entry. Every source type (RSS, Atom, Moodle, Canvas, Brightspace, Jira, SharePoint, OpenProject, generic REST) is mapped onto this same shape, so a client never branches on sourceType to read a result.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Source-supplied identifier — a GUID, a link, or an md5 of the title when the feed offers neither. Stable enough to de-duplicate a single fetch; not a durable key."
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "Absolute link to the item at its source. Jira issue keys and OpenProject work packages are rewritten to their browse/web URL rather than the API URL."
          },
          "excerpt": {
            "type": "string",
            "description": "Sanitised plain-text summary; source HTML is stripped."
          },
          "image": {
            "type": [
              "string",
              "null"
            ],
            "description": "Never the source URL. Images are rewritten to a signed GET /api/feed/image proxy link, because the page CSP forbids loading third-party images directly. The signature is bound to the URL, so it cannot be pointed elsewhere."
          },
          "date": {
            "type": "string",
            "format": "date-time"
          },
          "source": {
            "type": "string"
          },
          "author": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "title",
          "url",
          "excerpt",
          "date"
        ]
      },
      "FeedResult": {
        "type": "object",
        "description": "Result of a feed fetch. Note the failure convention: an unreachable or malformed source is NOT reported as an item-level error — it returns an empty items array with an error string, so a widget degrades to empty rather than breaking the page.",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FeedItem"
            },
            "description": "Capped at 50 server-side regardless of the requested limit."
          },
          "source": {
            "type": "string",
            "description": "Display name of the origin — the connection name, or the feed's own title for RSS."
          },
          "feedImage": {
            "type": [
              "string",
              "null"
            ],
            "description": "Feed-level logo, proxied the same way as item images."
          },
          "error": {
            "type": "string",
            "description": "Present only on failure, alongside an empty items array."
          }
        }
      },
      "NamedRef": {
        "type": "object",
        "description": "An id/name pair used by every picker endpoint (courses, forums, Jira projects, SharePoint lists). Sorted case-insensitively by name.",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "FeedConnection": {
        "type": "object",
        "description": "A configured external connection. IMPORTANT: this endpoint is available to every logged-in user, because the widget editor needs connection NAMES to build a dropdown. The credential-adjacent fields below are therefore returned ONLY to administrators; a non-admin caller receives the object without them. Never assume their presence.",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "description": "moodle, canvas, brightspace, jira, sharepoint, openproject or a generic REST type."
          },
          "baseUrl": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "hasToken": {
            "type": "boolean",
            "description": "Whether a token is stored. The token itself is never returned."
          },
          "authMode": {
            "type": "string"
          },
          "oidcAutoConnect": {
            "type": "boolean"
          },
          "siteUrl": {
            "type": "string"
          },
          "hasClientCredentials": {
            "type": "boolean",
            "description": "Whether both a client id and secret are stored. The secret is never returned."
          },
          "customEndpoint": {
            "type": "string",
            "description": "Non-LMS connection types only."
          },
          "authMethod": {
            "type": "string",
            "description": "Non-LMS connection types only."
          },
          "responseMapping": {
            "type": "object",
            "additionalProperties": true,
            "description": "Field mapping for generic REST sources. Non-LMS connection types only."
          },
          "tenantId": {
            "type": "string",
            "description": "Administrators only."
          },
          "clientId": {
            "type": "string",
            "description": "Administrators only."
          },
          "jiraEmail": {
            "type": "string",
            "description": "Administrators only."
          },
          "apiKeyHeader": {
            "type": "string",
            "description": "Administrators only, non-LMS types only."
          },
          "customHeaders": {
            "type": "object",
            "additionalProperties": true,
            "description": "Administrators only, non-LMS types only. Routinely holds an API key as a header value — the most sensitive field in this object."
          }
        },
        "required": [
          "id",
          "name",
          "type",
          "baseUrl",
          "active",
          "hasToken"
        ]
      },
      "StatusOk": {
        "type": "object",
        "description": "A bare acknowledgement using the status/ok convention. Distinct from SuccessAck ({success: true}) — the codebase carries both shapes and they are not interchangeable.",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ]
          }
        }
      },
      "BulkValidation": {
        "type": "object",
        "description": "Outcome of a dry run. This is also what a mutating endpoint returns when dryRun is true — note that the envelope then differs from the one you get for the real call, so a client must branch on which it asked for.",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Always true: this reports on the validation itself, not on whether every page passed. Read canProceed and willFail for that."
          },
          "operation": {
            "type": "string",
            "enum": [
              "delete",
              "move",
              "update"
            ]
          },
          "total": {
            "type": "integer",
            "description": "Number of ids submitted."
          },
          "canProceed": {
            "type": "integer"
          },
          "willFail": {
            "type": "integer"
          },
          "valid": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "pageId": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                }
              },
              "required": [
                "pageId",
                "title"
              ]
            }
          },
          "invalid": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "pageId": {
                  "type": "string"
                },
                "reason": {
                  "type": "string",
                  "description": "'Permission denied' or 'Page not found'. Deliberately coarse — it must not confirm the existence of a page the caller may not see."
                }
              },
              "required": [
                "pageId",
                "reason"
              ]
            }
          }
        },
        "required": [
          "success",
          "operation",
          "total",
          "canProceed",
          "willFail",
          "valid",
          "invalid"
        ]
      },
      "BulkResult": {
        "type": "object",
        "description": "Outcome of an executed bulk operation.\n\nWATCH THE SUCCESS-COUNT KEY. It is named after the operation, not fixed: 'deleted' for delete, 'moved' for move, 'updated' for update. There is no single key holding the number that succeeded, so a client must look up the one matching the operation it requested. The failure count is always 'failed'.\n\n'failed' is therefore an INTEGER at the top level while results[] entries carry a status string — the two are unrelated despite the shared word.",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "True only when nothing failed. A partial result is false and arrives with status 207."
          },
          "operation": {
            "type": "string",
            "enum": [
              "delete",
              "move",
              "update"
            ]
          },
          "total": {
            "type": "integer",
            "description": "Attempted = succeeded + failed."
          },
          "deleted": {
            "type": "integer",
            "description": "Present only when operation is delete."
          },
          "moved": {
            "type": "integer",
            "description": "Present only when operation is move."
          },
          "updated": {
            "type": "integer",
            "description": "Present only when operation is update."
          },
          "failed": {
            "type": "integer",
            "description": "How many failed."
          },
          "results": {
            "type": "array",
            "description": "Per-page outcome, successes first then failures.",
            "items": {
              "type": "object",
              "properties": {
                "pageId": {
                  "type": "string"
                },
                "title": {
                  "type": "string",
                  "description": "Present on success only."
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "deleted",
                    "moved",
                    "updated",
                    "failed"
                  ]
                },
                "error": {
                  "type": "string",
                  "description": "Present on failure only."
                }
              },
              "required": [
                "pageId",
                "status"
              ]
            }
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Flat 'pageId: reason' strings, the same failures as in results[]. Redundant, kept for existing callers."
          }
        },
        "required": [
          "success",
          "operation",
          "total",
          "failed",
          "results",
          "errors"
        ]
      },
      "DemoDataStatus": {
        "type": "object",
        "description": "Whether demo content is installed, per language.",
        "properties": {
          "imported": {
            "type": "boolean"
          },
          "available_languages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Enabled content languages. Note the snake_case keys here — this response mixes conventions with the camelCase setupComplete below."
          },
          "default_language": {
            "type": "string"
          },
          "setupComplete": {
            "type": "boolean",
            "description": "Whether the IntraVox GroupFolder exists yet. When false every language reports status 'setup_required'."
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "flag": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "setup_required",
                    "unavailable",
                    "not_installed",
                    "installed",
                    "empty"
                  ],
                  "description": "setup_required: the GroupFolder does not exist. unavailable: no bundled demo data ships for this language. not_installed: nothing there yet. empty: a folder exists but holds no content. installed: content present."
                }
              },
              "required": [
                "code",
                "name",
                "status"
              ]
            }
          }
        },
        "required": [
          "imported",
          "available_languages",
          "default_language",
          "languages",
          "setupComplete"
        ]
      },
      "DemoDataOperationResult": {
        "type": "object",
        "description": "Result of an import or clean start.\n\nMIND THE KEY: on this envelope the human-readable text is 'message', both on success and on failure. That differs from the 'error' key returned when the controller itself catches an exception — so a client reading only one of the two will silently show nothing for half the failure modes.\n\nAlso note that success:false arrives with HTTP 500, including for ordinary refusals such as 'language not enabled'. That is not a server fault, but it is not distinguishable from one by status code alone.",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "imported": {
            "type": "integer",
            "description": "Pages imported. Import only."
          },
          "skipped": {
            "type": "integer",
            "description": "Pages left alone because they already existed. Import only, and only meaningful in skip_existing mode."
          },
          "errors": {
            "type": "integer",
            "description": "Per-page failures. success is true only when this is 0. Import only."
          },
          "uniqueId": {
            "type": "string",
            "description": "Unique id of the freshly created homepage. Clean start only."
          },
          "commentsDeleted": {
            "type": "integer",
            "description": "Clean start only."
          }
        },
        "required": [
          "success",
          "message"
        ]
      },
      "OrphanedFolder": {
        "type": "object",
        "description": "A directory under __groupfolders/ with no matching GroupFolder row — content left behind when a GroupFolder was removed while its files stayed on disk.",
        "properties": {
          "id": {
            "type": "integer",
            "description": "The numeric folder id, which is also the directory name."
          },
          "path": {
            "type": "string",
            "description": "Absolute server path. Administrator-only information by nature."
          },
          "size": {
            "type": "integer",
            "description": "Bytes."
          },
          "sizeFormatted": {
            "type": "string"
          },
          "hasIntraVoxContent": {
            "type": "boolean",
            "description": "Whether language folders with a home.json were found. False means this orphan is probably not IntraVox's."
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "lastModified": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix timestamp."
          },
          "lastModifiedFormatted": {
            "type": [
              "string",
              "null"
            ]
          },
          "pageCount": {
            "type": "integer"
          },
          "sampleContents": {
            "type": "object",
            "description": "A capped sample of top-level entries, with totalEntries giving the true count.",
            "properties": {
              "totalEntries": {
                "type": "integer"
              },
              "entries": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "dir",
                        "file"
                      ]
                    },
                    "size": {
                      "type": "integer"
                    },
                    "sizeFormatted": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "languageDetails": {
            "type": "object",
            "description": "Per-language breakdown. Returned by the details endpoint only.",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "pageCount": {
                  "type": "integer"
                },
                "hasHome": {
                  "type": "boolean"
                },
                "hasNavigation": {
                  "type": "boolean"
                },
                "hasFooter": {
                  "type": "boolean"
                },
                "mediaCount": {
                  "type": "integer"
                },
                "size": {
                  "type": "integer"
                },
                "sizeFormatted": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "id",
          "path",
          "size",
          "hasIntraVoxContent",
          "languages",
          "pageCount"
        ]
      },
      "LmsUserConnection": {
        "type": "object",
        "description": "An LMS connection as seen by ONE user. Distinct from FeedConnection: that describes the admin-level configuration, this describes whether the calling user has personally linked their account to it. Two users see different 'connected' values for the same connection.",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "authMode": {
            "type": "string",
            "description": "'token' for a manually pasted API token, otherwise an OAuth2 mode. Determines which of the two connect endpoints applies."
          },
          "oidcAutoConnect": {
            "type": "boolean",
            "description": "Whether the connection reuses the user's existing Nextcloud OIDC session instead of a separate authorisation."
          },
          "connected": {
            "type": "boolean",
            "description": "Whether this user has a stored token. The token itself is never returned."
          },
          "tokenType": {
            "type": [
              "string",
              "null"
            ]
          },
          "connectedAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "When this user linked the connection."
          }
        },
        "required": [
          "id",
          "name",
          "type",
          "authMode",
          "connected"
        ]
      },
      "PageExport": {
        "type": "object",
        "description": "One exported page. Wrapped rather than flat: the page's own document sits under 'content', with comments and reactions alongside it.",
        "properties": {
          "uniqueId": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "content": {
            "type": "object",
            "additionalProperties": true,
            "description": "The complete page document as stored."
          },
          "comments": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            },
            "description": "Present only when includeComments is 1."
          },
          "pageReactions": {
            "$ref": "#/components/schemas/Reactions",
            "description": "Present only when includeComments is 1 — reactions ride along with comments, they are not separately selectable."
          }
        },
        "required": [
          "uniqueId",
          "title",
          "content"
        ]
      },
      "LanguageExport": {
        "type": "object",
        "description": "A complete language export: every page the caller's mount exposes, plus the navigation and footer.\n\nThe version fields matter for round-tripping. exportVersion/schemaVersion identify the payload format, and requiresMinVersion states the oldest IntraVox that can import it — an older instance should refuse rather than import partially.",
        "properties": {
          "exportVersion": {
            "type": "string",
            "description": "Payload format version, e.g. '1.3'."
          },
          "schemaVersion": {
            "type": "string"
          },
          "exportDate": {
            "type": "string",
            "format": "date-time"
          },
          "language": {
            "type": "string"
          },
          "exportedBy": {
            "type": "string",
            "description": "'IntraVox/<app version>'."
          },
          "requiresMinVersion": {
            "type": "string",
            "description": "Oldest IntraVox version able to import this payload."
          },
          "navigation": {
            "type": "object",
            "additionalProperties": true
          },
          "footer": {
            "type": "object",
            "additionalProperties": true
          },
          "pages": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            },
            "description": "Each entry carries the page document plus _exportPath and _fileId helpers used on import."
          },
          "metaVox": {
            "type": "object",
            "additionalProperties": true,
            "description": "MetaVox field definitions, when that app is present."
          }
        },
        "required": [
          "exportVersion",
          "language",
          "pages"
        ]
      },
      "UserProfile": {
        "type": "object",
        "description": "A user as this API exposes them. Only the always-present keys are listed; the rest depend on the subject's visibility scopes and on what the directory syncs.",
        "properties": {
          "uid": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          },
          "avatarUrl": {
            "type": "string",
            "format": "uri"
          },
          "groups": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "description": "null when the user's scope hides it. Never read around the scope."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "role": {
            "type": [
              "string",
              "null"
            ]
          },
          "organisation": {
            "type": [
              "string",
              "null"
            ]
          },
          "birthdate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Normalised to ISO 8601 regardless of how Nextcloud stored it."
          }
        },
        "required": [
          "uid",
          "displayName"
        ],
        "additionalProperties": true
      },
      "ImportStats": {
        "type": "object",
        "description": "What an import actually did. Every counter is an integer — including navigationImported and footerImported, which are 0 or 1 rather than booleans, deliberately so the whole object has one type.\n\nThere is no per-page list: a page that was skipped is counted, not named. To know WHICH pages already existed you compare before and after yourself.",
        "properties": {
          "pagesImported": {
            "type": "integer"
          },
          "pagesSkipped": {
            "type": "integer",
            "description": "Pages left alone because they already existed and overwrite was off."
          },
          "mediaFilesImported": {
            "type": "integer"
          },
          "commentsImported": {
            "type": "integer"
          },
          "navigationImported": {
            "type": "integer",
            "enum": [
              0,
              1
            ]
          },
          "footerImported": {
            "type": "integer",
            "enum": [
              0,
              1
            ]
          },
          "metavoxEnabled": {
            "type": "boolean",
            "description": "Whether the archive carried MetaVox data at all."
          },
          "metavoxFieldsImported": {
            "type": "integer"
          },
          "metavoxFieldsSkipped": {
            "type": "integer"
          },
          "metavoxFieldsFailed": {
            "type": "integer"
          }
        },
        "required": [
          "pagesImported",
          "pagesSkipped",
          "mediaFilesImported",
          "commentsImported"
        ]
      },
      "SafeError": {
        "type": "object",
        "description": "The error shape used where a failure must not describe itself.\n\n'error' is a fixed generic sentence — it never carries the exception message, because these handlers touch file paths and comment ids that would disclose internal structure. The detail is logged server-side under 'errorId'; quote that in a support request rather than the message, which says the same thing every time.",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "description": "Generic and stable. Not the cause."
          },
          "errorId": {
            "type": "string",
            "description": "Correlates this response with the server log entry holding the real cause."
          }
        },
        "required": [
          "success",
          "error",
          "errorId"
        ]
      },
      "ExportableLanguage": {
        "type": "object",
        "description": "A content language that can be exported, with enough context to choose one.",
        "properties": {
          "code": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "description": "Native display name."
          },
          "flag": {
            "type": "string",
            "description": "Emoji flag; may be empty."
          },
          "hasContent": {
            "type": "boolean"
          },
          "pageCount": {
            "type": "integer"
          }
        },
        "required": [
          "code",
          "name",
          "hasContent",
          "pageCount"
        ]
      }
    },
    "parameters": {
      "FeedSourceType": {
        "name": "sourceType",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "default": "rss",
          "enum": [
            "rss",
            "atom",
            "moodle",
            "canvas",
            "brightspace",
            "jira",
            "sharepoint",
            "openproject",
            "rest"
          ]
        },
        "description": "Selects which fetcher runs. Anything other than 'rss' reads connectionId instead of url."
      },
      "FeedUrl": {
        "name": "url",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "format": "uri"
        },
        "description": "RSS/Atom feed URL. Used only when sourceType is rss. Validated against SSRF before any request is made: non-http(s) schemes, loopback, link-local and private ranges are refused, and a host that does not resolve is refused rather than fetched."
      },
      "FeedConnectionIdQuery": {
        "name": "connectionId",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Which stored connection to fetch through. Used for every sourceType except rss."
      },
      "FeedCourseId": {
        "name": "courseId",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "pattern": "^[a-zA-Z0-9_-]{1,64}$"
        },
        "description": "A value failing this pattern is silently discarded rather than rejected — the fetch proceeds without a course filter."
      },
      "FeedContentType": {
        "name": "contentType",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "news",
            "my-courses",
            "courses",
            "assignments",
            "deadlines",
            "pages",
            "documents",
            "list",
            "open",
            "overdue",
            "milestones",
            "recently-updated",
            "bugs",
            "recent",
            "created-recent"
          ]
        },
        "description": "Which slice of the source to read; meaning depends on sourceType. An unrecognised value is silently discarded."
      },
      "FeedJiraProject": {
        "name": "jiraProject",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "pattern": "^[A-Z][A-Z0-9_]{1,20}$"
        },
        "description": "Jira project key. Silently discarded if malformed."
      },
      "FeedMoodleForumId": {
        "name": "moodleForumId",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "pattern": "^[0-9]{1,10}$"
        },
        "description": "Silently discarded if malformed."
      },
      "FeedListId": {
        "name": "listId",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "pattern": "^[a-zA-Z0-9-]{1,64}$"
        },
        "description": "SharePoint list or document-library id. Silently discarded if malformed."
      },
      "FeedSortBy": {
        "name": "sortBy",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "default": "date",
          "enum": [
            "date",
            "title"
          ]
        },
        "description": "An unrecognised value falls back to 'date' rather than erroring."
      },
      "FeedSortOrder": {
        "name": "sortOrder",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "default": "desc",
          "enum": [
            "asc",
            "desc"
          ]
        },
        "description": "An unrecognised value falls back to 'desc'."
      },
      "FeedFilterKeyword": {
        "name": "filterKeyword",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "maxLength": 100
        },
        "description": "Truncated to 100 characters server-side."
      }
    }
  }
}