Conflagent is a lightweight, standalone REST API service that acts as a bridge between a custom GPT (or any other HTTP client) and a sandboxed section of an Atlassian Confluence workspace. It allows programmatic listing, creation, reading, updating, and renaming of Confluence pages, enabling GPT-based document automation, intelligent assistants, or bot integrations.

• REST API secured via a pre-shared GPT secret (Bearer token via Authorization: Bearer <token> header)
• Supports multiple independent endpoint instances, each isolated under /endpoint/<name>/ and configured via separate conflagent.<name>.properties files
• Dynamic OpenAPI schema rendering per endpoint at /endpoint/<name>/openapi.json
• Operations limited to a pre-defined Confluence space and root page per endpoint
• Fully compatible with Custom GPTs via OpenAPI tool definition
• Minimal, self-contained Flask app with no external database
• Hierarchical navigation endpoints accept page titles (no Confluence IDs required); Conflagent resolves IDs internally when calling the Confluence API

Designed to integrate with a Custom GPT Operator Tool, this API allows a GPT to:

• List all subpages under a specified Confluence root page
• Read content of a child page by its title
• Create a new child page under the root
• Update an existing child page by title
• Rename a child page by title

⚠️ When updating pages, submit full content only – the API does not support diffs or partial updates. Markdown input is accepted and will be automatically converted to Confluence HTML format. Take care not to mangle internal page links during updates.

This provides a clean way to expose a read/write Confluence sandbox to GPTs without exposing the entire Confluence workspace or admin API tokens.

Each GPT or user-specific configuration lives in its own file named conflagent.<endpoint>.properties. These endpoints are isolated and treated as private secrets — there is no discovery API for listing endpoints.

The API structure for each endpoint is:

/endpoint/<name>/pages
/endpoint/<name>/pages/<title>
/endpoint/<name>/pages/rename
/endpoint/<name>/openapi.json   ← dynamic OpenAPI schema
/endpoint/<name>/health

It should be placed outside deployment folder.

conflagent/
├── conflagent.py                    # Flask routing entry point with lightweight handlers
├── conflagent_core/                 # Core services for config, auth, OpenAPI, and Confluence access
├── conflagent.properties.example    # Example configuration file
├── tests/                           # Unit and integration tests covering routes and services

This repository contains only the Conflagent service code. The automation that builds and ships the application lives in a separate, private deployment repository. In practice this means:

• Three permanent environments – main deploys to the dev instance, staging to the stage instance for manual verification, and prod to the production instance that must remain stable.
• Trunk-based development – feature work branches off main, is merged via small, continuously integrated changes, and then flows through staging to production.
• Environment-specific logic – infrastructure templates, secrets management, and any pipeline-specific scripts are managed outside of this repo. Coordinate with the deployment repository for changes to those assets.

Regardless of environment, Conflagent must be hosted behind HTTPS to keep GPT secrets and Confluence tokens protected in transit.

All protected operations require a pre-shared Bearer token header:

Authorization: Bearer your_gpt_secret

GPT tool calls must include this to access or modify Confluence content. The secret should be embedded in your Custom GPT configuration. Each endpoint has its own secret.

Every REST call now returns a structured envelope that is easy for GPT agents and other clients to parse consistently:

{
  "success": true,
  "code": "OK",
  "message": "Operation completed successfully.",
  "data": { /* endpoint-specific payload */ },
  "timestamp": "2025-11-04T09:20:31Z"
}

Key fields:

Error responses return success: false, populate code with one of the values listed above, include a descriptive message, and set data to null.

To integrate this API with a Custom GPT:

1. Download the OpenAPI schema from your running deployment at https://<host>/endpoint/<name>/openapi.json and provide it to the GPT tool definition. The schema is generated dynamically with the correct server URL and operations for that endpoint.
2. Configure the Authorization header with Bearer your_gpt_secret in your GPT setup.
3. Ensure the API server is reachable over HTTPS at the declared domain and under the endpoint prefix you defined.
4. Your GPT will now be able to list, read, create, update, and rename pages within the sandboxed Confluence space for that endpoint.

MIT License

Developed by Jan Chimiak.

For questions, improvements or ideas — feel free to open an issue or PR.