api.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "eXist-db Platform API",
    "version": "0.14.0",
    "description": "Unified REST API for eXist-db: query execution, language services, database management, user management, package management, search, and cross-app linking.",
    "license": {
      "name": "LGPL-2.1",
      "url": "https://opensource.org/licenses/LGPL-2.1"
    }
  },
  "servers": [
    {
      "url": "/exist/apps/existdb-openapi",
      "description": "Local eXist-db instance"
    }
  ],
  "tags": [
    {
      "name": "System",
      "description": "System information, scheduler, and test runner"
    },
    {
      "name": "Query",
      "description": "XQuery execution with cursor-based result pagination"
    },
    {
      "name": "Language Service",
      "description": "Language services for XQuery (diagnostics, completions, hover, etc.). Data shapes are inspired by the Language Server Protocol but consumed over HTTP/JSON."
    },
    {
      "name": "Database",
      "description": "Database resource and collection management"
    },
    {
      "name": "Users",
      "description": "User account management"
    },
    {
      "name": "Groups",
      "description": "Group management"
    },
    {
      "name": "Packages",
      "description": "EXPath package management"
    },
    {
      "name": "Search",
      "description": "Sitewide full-text search"
    },
    {
      "name": "Site",
      "description": "Site-level app listing and cross-app link resolution"
    }
  ],
  "components": {
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      },
      "cookieAuth": {
        "type": "apiKey",
        "in": "cookie",
        "name": "org.exist.login"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message"
          }
        },
        "required": [
          "error"
        ],
        "example": {
          "error": "Resource not found: /db/nonexistent.xml"
        }
      },
      "QueryError": {
        "type": "object",
        "description": "Structured error envelope for a failed query evaluation. `line`/`column` are 1-based and user-relative — the position in the submitted `query`, the same frame an editor uses — so a client can place an error marker without parsing prose.",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error QName, e.g. `err:XPST0003`"
          },
          "message": {
            "type": "string",
            "description": "The human-readable reason, with eXist's framing removed (no W3C boilerplate, leaked Java class name, or `[at line …]` suffix)"
          },
          "line": {
            "type": "integer",
            "nullable": true,
            "description": "1-based, user-relative line of the error in the submitted query; null when the error carries no position"
          },
          "column": {
            "type": "integer",
            "nullable": true,
            "description": "1-based, user-relative column; null when the error carries no position"
          },
          "raw": {
            "type": "string",
            "description": "The unmodified `$err:description`, retained so no detail is lost"
          }
        },
        "required": [
          "code",
          "message",
          "raw"
        ],
        "example": {
          "code": "err:XPST0003",
          "message": "unexpected token: null",
          "line": 1,
          "column": 5,
          "raw": "It is a static error if an expression is not a valid instance of the grammar defined in A.1 EBNF. org.exist.xquery.XPathException: err:XPST0003 unexpected token: null [at line 1, column 5]"
        }
      }
    }
  },
  "security": [
    {
      "basicAuth": []
    },
    {
      "cookieAuth": []
    }
  ],
  "paths": {
    "/api/system/info": {
      "get": {
        "summary": "Get system information",
        "operationId": "system-api:info",
        "description": "Returns database, Java, and OS information. No authentication required. Replaces xst's info.xq.",
        "tags": [
          "System"
        ],
        "responses": {
          "200": {
            "description": "System information including database version, Java runtime, and operating system details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "db": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "version": {
                          "type": "string"
                        },
                        "git": {
                          "type": "string"
                        }
                      }
                    },
                    "java": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "string"
                        },
                        "vendor": {
                          "type": "string"
                        }
                      }
                    },
                    "os": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "version": {
                          "type": "string"
                        },
                        "arch": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "example": {
                    "db": {
                      "name": "eXist",
                      "version": "7.0.0",
                      "git": "abc123"
                    },
                    "java": {
                      "version": "21.0.5",
                      "vendor": "Azul Systems, Inc."
                    },
                    "os": {
                      "name": "Mac OS X",
                      "version": "15.0",
                      "arch": "aarch64"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/system/scheduler": {
      "get": {
        "summary": "List scheduled jobs",
        "operationId": "system-api:scheduler",
        "description": "Returns all scheduled jobs from the eXist-db scheduler. Used by Dashboard's System tab.",
        "tags": [
          "System"
        ],
        "responses": {
          "200": {
            "description": "Scheduled jobs with trigger states and timing information",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jobs": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "group": {
                            "type": "string"
                          },
                          "triggerState": {
                            "type": "string"
                          },
                          "start": {
                            "type": "string"
                          },
                          "end": {
                            "type": "string"
                          },
                          "previous": {
                            "type": "string"
                          },
                          "next": {
                            "type": "string"
                          },
                          "expression": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  },
                  "example": {
                    "jobs": [
                      {
                        "name": "Sessions.Check",
                        "group": "eXist.Security",
                        "triggerState": "NORMAL",
                        "start": "",
                        "end": "",
                        "previous": "2024-01-01T00:00:00",
                        "next": "2024-01-01T00:05:00",
                        "expression": "0 0/5 * * * ?"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/test": {
      "post": {
        "summary": "Run XQSuite tests",
        "operationId": "system-api:test",
        "description": "Runs XQSuite tests on a stored XQuery module. Returns the test results as HTML.",
        "tags": [
          "System"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "source"
                ],
                "properties": {
                  "source": {
                    "type": "string",
                    "description": "DB path to the XQSuite test module"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Test results with pass/fail counts and XML output",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "source": {
                      "type": "string",
                      "description": "DB path of the test module"
                    },
                    "tests": {
                      "type": "integer",
                      "description": "Total number of tests"
                    },
                    "failures": {
                      "type": "integer",
                      "description": "Number of failed tests"
                    },
                    "errors": {
                      "type": "integer",
                      "description": "Number of tests with errors"
                    },
                    "pending": {
                      "type": "integer",
                      "description": "Number of pending tests"
                    },
                    "results": {
                      "type": "string",
                      "description": "XML test results (JUnit format)"
                    }
                  },
                  "example": {
                    "source": "/db/apps/myapp/test/suite.xql",
                    "tests": 12,
                    "failures": 0,
                    "errors": 0,
                    "pending": 1,
                    "results": "<testsuites>...</testsuites>"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request — missing or invalid source parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Test module not found at the given path",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/query": {
      "post": {
        "summary": "Execute query and return cursor",
        "operationId": "query:execute",
        "description": "Compiles and evaluates an XQuery expression, returning a cursor ID for paginated result retrieval. The cursor must be closed when no longer needed.",
        "tags": [
          "Query"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "XQuery expression to evaluate"
                  },
                  "module-load-path": {
                    "type": "string",
                    "description": "Module load path for resolving imports"
                  },
                  "context-item": {
                    "type": "string",
                    "description": "Serialized XML to use as the context item — the node `expression` will see as `.` / the focus of unprefixed path expressions like `//foo`. Use when the editor has unsaved buffer content not yet stored in the database. Ignored when `context-path` is also supplied."
                  },
                  "context-path": {
                    "type": "string",
                    "description": "DB path (e.g. `/db/apps/foo/data.xml`) to a document to use as the context item. Convenience shortcut over `context-item` when the editor's current document is already in the database. Takes precedence over `context-item`."
                  },
                  "variables": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "External-variable bindings: each property name is a variable's local name (no namespace), bound to the matching `declare variable $name external;` in the expression. JSON values map to XDM by kind — string→xs:string, number→xs:double, boolean→xs:boolean, array→array(*), object→map(*) — so an array value is read with array accessors (e.g. `$x?*`, or `array:flatten($x)` for its members). A typed external declaration (e.g. `as xs:integer`) is matched strictly: pass a conforming value or cast in-query (`xs:integer($n)`). A name with no matching external declaration is ignored, as eXist's own XML-RPC and REST query interfaces do.",
                    "example": {
                      "project-id": "frus1981-88v36",
                      "div-ids": ["d278", "d300"]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Query executed successfully; returns a cursor for result retrieval",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "cursor": {
                      "type": "string",
                      "description": "Unique cursor ID for fetching results"
                    },
                    "items": {
                      "type": "integer",
                      "description": "Total number of result items"
                    },
                    "elapsed": {
                      "type": "integer",
                      "description": "Total elapsed time in milliseconds"
                    },
                    "timing": {
                      "type": "object",
                      "properties": {
                        "compile": {
                          "type": "integer",
                          "description": "Compilation time in ms"
                        },
                        "evaluate": {
                          "type": "integer",
                          "description": "Evaluation time in ms"
                        },
                        "total": {
                          "type": "integer",
                          "description": "Total time in ms"
                        }
                      }
                    }
                  },
                  "example": {
                    "cursor": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                    "items": 10,
                    "elapsed": 5,
                    "timing": {
                      "compile": 2,
                      "evaluate": 3,
                      "total": 5
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Either a request-validation error (missing `query` field or malformed `context-item` XML) with an `{ error }` body, or — when the submitted query itself fails to compile or evaluate (a standard XPath/XQuery error) — a structured `QueryError` body with user-relative `line`/`column`.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/Error" },
                    { "$ref": "#/components/schemas/QueryError" }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "`context-path` was supplied but the document at that path doesn't exist",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal failure during query compilation or evaluation (an error outside the standard XPath/XQuery `err:` namespace). Body is a structured `QueryError` so clients can surface the real cause.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueryError"
                }
              }
            }
          }
        }
      }
    },
    "/api/query/{id}/results": {
      "get": {
        "summary": "Fetch page of results from cursor",
        "operationId": "query:fetch",
        "description": "Retrieves a page of serialized results from an open query cursor. Supports configurable start position, count, serialization method, and indentation.",
        "tags": [
          "Query"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Cursor ID returned by POST /api/query"
          },
          {
            "name": "start",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            },
            "description": "1-based start position"
          },
          {
            "name": "count",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10
            },
            "description": "Number of items to return"
          },
          {
            "name": "method",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "adaptive"
            },
            "description": "Serialization method (adaptive, xml, json, text)"
          },
          {
            "name": "indent",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "yes"
            },
            "description": "Whether to indent output (yes/no)"
          }
        ],
        "responses": {
          "200": {
            "description": "Array of serialized result items with type information",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "value": {
                        "type": "string",
                        "description": "Serialized value"
                      },
                      "type": {
                        "type": "string",
                        "description": "XDM type (e.g. xs:integer, element())"
                      },
                      "documentURI": {
                        "type": "string",
                        "description": "Source document URI if applicable"
                      },
                      "nodeId": {
                        "type": "string",
                        "description": "Internal node ID if applicable"
                      }
                    }
                  },
                  "example": [
                    {
                      "value": "1",
                      "type": "xs:integer",
                      "documentURI": "",
                      "nodeId": ""
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Cursor not found or expired",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/query/{id}": {
      "delete": {
        "summary": "Close cursor and release resources",
        "operationId": "query:close",
        "description": "Closes an open query cursor and releases associated server-side resources. Should be called when the client is done fetching results.",
        "tags": [
          "Query"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Cursor ID to close"
          }
        ],
        "responses": {
          "200": {
            "description": "Cursor successfully closed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "closed": {
                      "type": "boolean",
                      "description": "Always true on success"
                    }
                  },
                  "example": {
                    "closed": true
                  }
                }
              }
            }
          },
          "404": {
            "description": "Cursor not found or already closed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/query/{id}/cancel": {
      "post": {
        "summary": "Cancel running query",
        "operationId": "query:cancel",
        "description": "Attempts to cancel a currently running query. Not yet implemented — returns an error message.",
        "tags": [
          "Query"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Cursor ID of the running query"
          }
        ],
        "responses": {
          "200": {
            "description": "Cancel result (currently returns not-implemented error)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "example": {
                    "error": "Not yet implemented"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/langservice/diagnostics": {
      "post": {
        "summary": "Compile check",
        "operationId": "langservice:diagnostics",
        "description": "Compiles an XQuery expression and returns any syntax or static errors as diagnostics. Used by IDE integrations for real-time error checking.",
        "tags": [
          "Language Service"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "expression"
                ],
                "properties": {
                  "expression": {
                    "type": "string",
                    "description": "XQuery expression to check"
                  },
                  "module-load-path": {
                    "type": "string",
                    "description": "Module load path for resolving imports"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Array of diagnostic entries (empty if no errors)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "line": {
                        "type": "integer",
                        "description": "0-based line number"
                      },
                      "column": {
                        "type": "integer",
                        "description": "0-based column number"
                      },
                      "severity": {
                        "type": "integer",
                        "description": "Severity level (1=error, 2=warning, 3=info, 4=hint)"
                      },
                      "code": {
                        "type": "string",
                        "description": "XQuery error code (e.g. XPST0003)"
                      },
                      "message": {
                        "type": "string",
                        "description": "Human-readable error message"
                      }
                    }
                  },
                  "example": [
                    {
                      "line": 0,
                      "column": 5,
                      "severity": 1,
                      "code": "XPST0003",
                      "message": "unexpected token"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/langservice/completions": {
      "post": {
        "summary": "Code completions",
        "operationId": "langservice:completions",
        "description": "Returns completion suggestions for an XQuery expression at the current cursor position. Includes functions, variables, and namespace prefixes.",
        "tags": [
          "Language Service"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "expression"
                ],
                "properties": {
                  "expression": {
                    "type": "string",
                    "description": "XQuery expression up to the cursor"
                  },
                  "module-load-path": {
                    "type": "string",
                    "description": "Module load path for resolving imports"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Array of completion items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "label": {
                        "type": "string",
                        "description": "Display label (e.g. fn:count#1)"
                      },
                      "kind": {
                        "type": "integer",
                        "description": "Completion kind (LSP CompletionItemKind)"
                      },
                      "detail": {
                        "type": "string",
                        "description": "Function signature or type info"
                      },
                      "documentation": {
                        "type": "string",
                        "description": "Documentation string"
                      },
                      "insertText": {
                        "type": "string",
                        "description": "Text to insert on accept"
                      }
                    }
                  },
                  "example": [
                    {
                      "label": "fn:count#1",
                      "kind": 3,
                      "detail": "fn:count($arg as item()*) as xs:integer",
                      "documentation": "Returns the number of items in a sequence",
                      "insertText": "fn:count()"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/langservice/hover": {
      "post": {
        "summary": "Hover info",
        "operationId": "langservice:hover",
        "description": "Returns hover information (signature and documentation) for the symbol at the given line and column in the XQuery expression.",
        "tags": [
          "Language Service"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "expression",
                  "line",
                  "column"
                ],
                "properties": {
                  "expression": {
                    "type": "string",
                    "description": "Full XQuery expression"
                  },
                  "line": {
                    "type": "integer",
                    "description": "0-based line number"
                  },
                  "column": {
                    "type": "integer",
                    "description": "0-based column number"
                  },
                  "module-load-path": {
                    "type": "string",
                    "description": "Module load path for resolving imports"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "LSP-shaped Hover: a map with one key, `contents`, whose value is a MarkupContent ({kind, value}) carrying Markdown-formatted documentation. Returns `null` (HTTP 200) if no symbol is found at the position.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contents": {
                      "type": "object",
                      "description": "LSP MarkupContent — see the `MarkupContent` schema component.",
                      "properties": {
                        "kind": {
                          "type": "string",
                          "enum": ["markdown", "plaintext"],
                          "description": "Format of the `value` string."
                        },
                        "value": {
                          "type": "string",
                          "description": "The Markdown (or plaintext) body. For functions: a fenced XQuery code block with the signature, the description, a Parameters bullet list, and a Returns line."
                        }
                      }
                    }
                  },
                  "example": {
                    "contents": {
                      "kind": "markdown",
                      "value": "```xquery\ncount($items as item()*) as xs:integer\n```\n\nReturns the number of items in the argument sequence.\n\n**Parameters**\n\n- `$items` (`item()*`) — The items\n\n**Returns:** `xs:integer`"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/langservice/signature-help": {
      "post": {
        "summary": "Parameter help inside a function call",
        "operationId": "langservice:signature-help",
        "description": "Returns LSP-shaped SignatureHelp for the function call surrounding the cursor: the call's signature, each parameter's label and per-parameter Markdown docs, plus an `activeParameter` index computed by counting commas at the call's paren depth. Returns `null` if the cursor is not inside a function-call argument list.",
        "tags": [
          "Language Service"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "expression",
                  "line",
                  "column"
                ],
                "properties": {
                  "expression": {
                    "type": "string",
                    "description": "Full XQuery expression"
                  },
                  "line": {
                    "type": "integer",
                    "description": "0-based line number"
                  },
                  "column": {
                    "type": "integer",
                    "description": "0-based column number"
                  },
                  "module-load-path": {
                    "type": "string",
                    "description": "Module load path for resolving imports"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "LSP-shaped SignatureHelp, or `null` (HTTP 200) if the cursor is not inside a function call.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "signatures": {
                      "type": "array",
                      "description": "One entry per overload of the function at the cursor, sorted by arity ascending. For functions with a single arity, a single-element array.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "label": {
                            "type": "string",
                            "description": "One-line function signature."
                          },
                          "documentation": {
                            "type": "object",
                            "description": "Markdown description.",
                            "properties": {
                              "kind": { "type": "string", "enum": ["markdown", "plaintext"] },
                              "value": { "type": "string" }
                            }
                          },
                          "parameters": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "label": {
                                  "type": "string",
                                  "description": "Parameter label, designed to substring-match the signature label (e.g. `$arg as item()*`)."
                                },
                                "documentation": {
                                  "type": "object",
                                  "properties": {
                                    "kind": { "type": "string", "enum": ["markdown", "plaintext"] },
                                    "value": { "type": "string" }
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "activeSignature": {
                      "type": "integer",
                      "description": "Index into `signatures` (0-based)."
                    },
                    "activeParameter": {
                      "type": "integer",
                      "description": "0-based index of the parameter the cursor is on, computed by counting top-level commas between the opening paren and the cursor."
                    }
                  },
                  "example": {
                    "signatures": [
                      {
                        "label": "substring($sourceString as xs:string?, $start as xs:double) as xs:string",
                        "documentation": { "kind": "markdown", "value": "Returns the contiguous sequence of characters …" },
                        "parameters": [
                          { "label": "$sourceString as xs:string?", "documentation": { "kind": "markdown", "value": "`$sourceString as xs:string?`\n\nThe source string" } },
                          { "label": "$start as xs:double", "documentation": { "kind": "markdown", "value": "`$start as xs:double`\n\nThe starting position" } }
                        ]
                      }
                    ],
                    "activeSignature": 0,
                    "activeParameter": 1
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/langservice/definition": {
      "post": {
        "summary": "Go to definition",
        "operationId": "langservice:definition",
        "description": "Resolves the definition location for the symbol at the given line and column. Returns the file URI, line, and column of the definition.",
        "tags": [
          "Language Service"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "expression",
                  "line",
                  "column"
                ],
                "properties": {
                  "expression": {
                    "type": "string",
                    "description": "Full XQuery expression"
                  },
                  "line": {
                    "type": "integer",
                    "description": "0-based line number"
                  },
                  "column": {
                    "type": "integer",
                    "description": "0-based column number"
                  },
                  "module-load-path": {
                    "type": "string",
                    "description": "Module load path for resolving imports"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Definition location of the referenced symbol",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "line": {
                      "type": "integer",
                      "description": "0-based line of definition"
                    },
                    "column": {
                      "type": "integer",
                      "description": "0-based column of definition"
                    },
                    "name": {
                      "type": "string",
                      "description": "Qualified name of the symbol"
                    },
                    "kind": {
                      "type": "string",
                      "description": "Symbol kind (function, variable, etc.)"
                    },
                    "uri": {
                      "type": "string",
                      "description": "DB path of the module containing the definition"
                    }
                  },
                  "example": {
                    "line": 5,
                    "column": 0,
                    "name": "local:my-func#1",
                    "kind": "function",
                    "uri": "/db/apps/myapp/modules/lib.xqm"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/langservice/references": {
      "post": {
        "summary": "Find all references",
        "operationId": "langservice:references",
        "description": "Finds all references to the symbol at the given line and column within the current expression.",
        "tags": [
          "Language Service"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "expression",
                  "line",
                  "column"
                ],
                "properties": {
                  "expression": {
                    "type": "string",
                    "description": "Full XQuery expression"
                  },
                  "line": {
                    "type": "integer",
                    "description": "0-based line number"
                  },
                  "column": {
                    "type": "integer",
                    "description": "0-based column number"
                  },
                  "module-load-path": {
                    "type": "string",
                    "description": "Module load path for resolving imports"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Array of reference locations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "line": {
                        "type": "integer",
                        "description": "0-based line of reference"
                      },
                      "column": {
                        "type": "integer",
                        "description": "0-based column of reference"
                      },
                      "name": {
                        "type": "string",
                        "description": "Qualified name of the symbol"
                      },
                      "kind": {
                        "type": "string",
                        "description": "Symbol kind"
                      }
                    }
                  },
                  "example": [
                    {
                      "line": 10,
                      "column": 4,
                      "name": "local:my-func#1",
                      "kind": "function"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/langservice/symbols": {
      "post": {
        "summary": "Document symbols",
        "operationId": "langservice:symbols",
        "description": "Returns all symbols (functions, variables) defined in the given XQuery expression. Used for document outline views in IDEs.",
        "tags": [
          "Language Service"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "expression"
                ],
                "properties": {
                  "expression": {
                    "type": "string",
                    "description": "Full XQuery expression"
                  },
                  "module-load-path": {
                    "type": "string",
                    "description": "Module load path for resolving imports"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Array of document symbols",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "description": "Qualified symbol name"
                      },
                      "kind": {
                        "type": "integer",
                        "description": "LSP SymbolKind number"
                      },
                      "line": {
                        "type": "integer",
                        "description": "0-based line of symbol"
                      },
                      "column": {
                        "type": "integer",
                        "description": "0-based column of symbol"
                      },
                      "detail": {
                        "type": "string",
                        "description": "Full signature"
                      }
                    }
                  },
                  "example": [
                    {
                      "name": "local:my-func#2",
                      "kind": 12,
                      "line": 5,
                      "column": 0,
                      "detail": "local:my-func($a, $b)"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/db": {
      "get": {
        "summary": "List collection contents",
        "operationId": "db:list",
        "description": "Lists the contents of a database collection including sub-collections and resources with metadata. Supports recursive listing, depth limits, and glob filtering.",
        "tags": [
          "Database"
        ],
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "/db"
            },
            "description": "Collection path to list"
          },
          {
            "name": "recursive",
            "in": "query",
            "description": "Enable recursive listing",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Max recursion depth (0=unlimited)",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "glob",
            "in": "query",
            "description": "Glob pattern filter for resource names",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "collections-only",
            "in": "query",
            "description": "Only list collections",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "start",
            "in": "query",
            "description": "1-based offset of the first child to return (flat listing only)",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "count",
            "in": "query",
            "description": "Maximum number of children to return (flat listing only; default: all)",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Collection metadata with children array. Each item carries `writable` (whether the caller may write to it) and `accessible` (whether the caller may read/open it) flags, both evaluated authoritatively by the server so clients needn't re-derive them from the mode bits; resource items also carry `mime-type`. A child whose metadata can't be read at all (e.g. a collection whose permissions the caller isn't allowed to retrieve) does not fail the listing — it appears as a degraded entry carrying just `type`, `name`, `path`, `accessible: false`, and an `error`. A flat (non-recursive) listing also carries `total` (full child count), `start` (1-based offset of this page) and `count` (items in this page).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "description": "Always 'collection'"
                    },
                    "name": {
                      "type": "string",
                      "description": "Collection name"
                    },
                    "path": {
                      "type": "string",
                      "description": "Full collection path"
                    },
                    "mode": {
                      "type": "string",
                      "description": "Unix-style permission string"
                    },
                    "owner": {
                      "type": "string"
                    },
                    "group": {
                      "type": "string"
                    },
                    "acl": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "writable": {
                      "type": "boolean",
                      "description": "Whether the caller may write to this item (sm:has-access, authoritative)"
                    },
                    "accessible": {
                      "type": "boolean",
                      "description": "Whether the caller may read/open this item (sm:has-access, authoritative). A degraded child entry whose metadata couldn't be read carries accessible: false."
                    },
                    "size": {
                      "type": "integer"
                    },
                    "modified": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "created": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "children": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      },
                      "description": "Child collections and resources"
                    }
                  },
                  "example": {
                    "type": "collection",
                    "name": "db",
                    "path": "/db",
                    "mode": "rwxr-xr-x",
                    "owner": "SYSTEM",
                    "group": "dba",
                    "acl": [],
                    "size": 0,
                    "modified": "2024-01-01T00:00:00.000-05:00",
                    "created": "2024-01-01T00:00:00.000-05:00",
                    "children": [
                      {
                        "type": "collection",
                        "name": "apps",
                        "path": "/db/apps",
                        "mode": "rwxr-xr-x",
                        "owner": "SYSTEM",
                        "group": "dba",
                        "acl": [],
                        "size": 0,
                        "modified": "2024-01-01T00:00:00.000-05:00",
                        "created": "2024-01-01T00:00:00.000-05:00"
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Collection not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/db/resource": {
      "get": {
        "summary": "Get a resource's content",
        "operationId": "db:get-resource",
        "description": "Returns a resource's content. Binary resources stream as raw bytes; XML/text resources are serialized from the stored node tree honoring the serialization parameters below (eXist keeps XML as a node tree, not a byte stream, so every read is a serialization). The body IS the content; `Content-Type` carries the mime. Metadata is a separate concern — use GET /api/db/properties. XQuery resources return their source, not execution output.",
        "tags": [
          "Database"
        ],
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Full DB path of the resource (decoded UTF-8, e.g. /db/apps/myapp/café.xml)"
          },
          {
            "name": "download",
            "in": "query",
            "schema": { "type": "string", "enum": ["true", "false", "yes", "no"] },
            "description": "When true, sets Content-Disposition: attachment so the browser saves rather than renders the resource."
          },
          { "name": "method", "in": "query", "schema": { "type": "string", "enum": ["xml", "xhtml", "html5", "text", "json", "adaptive", "microxml"] }, "description": "W3C serialization method (XML/text resources). Omit to use the conf.xml default; ignored for binary." },
          { "name": "indent", "in": "query", "schema": { "type": "string", "enum": ["yes", "no", "true", "false"] }, "description": "W3C: pretty-print the output." },
          { "name": "omit-xml-declaration", "in": "query", "schema": { "type": "string", "enum": ["yes", "no", "true", "false"] }, "description": "W3C: omit the <?xml ...?> declaration." },
          { "name": "encoding", "in": "query", "schema": { "type": "string" }, "description": "W3C: output character encoding (e.g. UTF-8)." },
          { "name": "media-type", "in": "query", "schema": { "type": "string" }, "description": "W3C: serialization media-type." },
          { "name": "item-separator", "in": "query", "schema": { "type": "string" }, "description": "W3C: separator between serialized items." },
          { "name": "standalone", "in": "query", "schema": { "type": "string", "enum": ["yes", "no", "omit"] }, "description": "W3C: standalone declaration." },
          { "name": "doctype-public", "in": "query", "schema": { "type": "string" }, "description": "W3C: PUBLIC identifier for the DOCTYPE." },
          { "name": "doctype-system", "in": "query", "schema": { "type": "string" }, "description": "W3C: SYSTEM identifier for the DOCTYPE." },
          { "name": "cdata-section-elements", "in": "query", "schema": { "type": "string" }, "description": "W3C: space-separated element QNames serialized as CDATA sections." },
          { "name": "normalization-form", "in": "query", "schema": { "type": "string" }, "description": "W3C: Unicode normalization form (NFC/NFD/NFKC/NFKD/none)." },
          { "name": "html-version", "in": "query", "schema": { "type": "string" }, "description": "W3C: HTML version (with method=html5/xhtml)." },
          { "name": "json-node-output-method", "in": "query", "schema": { "type": "string" }, "description": "W3C: serialization method for nodes nested in JSON output." },
          { "name": "suppress-indentation", "in": "query", "schema": { "type": "string" }, "description": "W3C: space-separated element QNames whose content is not indented." },
          { "name": "undeclare-prefixes", "in": "query", "schema": { "type": "string", "enum": ["yes", "no", "true", "false"] }, "description": "W3C: undeclare namespace prefixes that go out of scope." },
          { "name": "escape-uri-attributes", "in": "query", "schema": { "type": "string", "enum": ["yes", "no", "true", "false"] }, "description": "W3C: escape URI-valued HTML attributes." },
          { "name": "byte-order-mark", "in": "query", "schema": { "type": "string", "enum": ["yes", "no", "true", "false"] }, "description": "W3C: emit a byte-order mark." },
          { "name": "allow-duplicate-names", "in": "query", "schema": { "type": "string", "enum": ["yes", "no", "true", "false"] }, "description": "W3C (JSON): allow duplicate keys." },
          { "name": "exist:expand-xincludes", "in": "query", "schema": { "type": "string", "enum": ["yes", "no", "true", "false"] }, "description": "eXist serializer extension (implementation-defined, hence the exist: prefix): expand <xi:include> elements. Defaults to the conf.xml setting; set 'no' to preserve includes verbatim (e.g. for round-tripping)." },
          { "name": "exist:highlight-matches", "in": "query", "schema": { "type": "string" }, "description": "eXist serializer extension: mark full-text/index matches (none|attributes|elements|both)." },
          { "name": "exist:add-exist-id", "in": "query", "schema": { "type": "string" }, "description": "eXist serializer extension: add exist:id attributes (none|element|all)." },
          { "name": "exist:process-xsl-pi", "in": "query", "schema": { "type": "string", "enum": ["yes", "no", "true", "false"] }, "description": "eXist serializer extension: act on xml-stylesheet processing instructions." },
          { "name": "exist:jsonp", "in": "query", "schema": { "type": "string" }, "description": "eXist serializer extension: wrap JSON output in the named JSONP callback." },
          { "name": "exist:insert-final-newline", "in": "query", "schema": { "type": "string", "enum": ["yes", "no", "true", "false"] }, "description": "eXist serializer extension: append a trailing newline." }
        ],
        "responses": {
          "200": {
            "description": "The resource's content. `Content-Type` is the stored mime type. A binary resource streams as raw bytes; an XML/text resource is serialized with the requested parameters (omitted params fall through to the conf.xml defaults).",
            "content": {
              "*/*": { "schema": { "type": "string", "format": "binary" } }
            }
          },
          "400": {
            "description": "Missing required parameter: path",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "404": {
            "description": "Resource not found",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      },
      "put": {
        "summary": "Store a resource from a raw request body (binary-safe)",
        "operationId": "db:store-resource",
        "description": "Stores or updates a resource from the raw request body (binary-safe). The path is a query parameter; the body is the content. The parent collection must exist. The stored mime type comes from the optional `mime` query parameter; when omitted the server infers it from the path's filename extension via eXist's `mime-types.xml` (e.g. `.xq` → `application/xquery`, `.svg` → `image/svg+xml`). Pass `mime=application/octet-stream` to force raw-byte storage of content that would otherwise be parsed (e.g. malformed HTML). The request's own `Content-Type` is transport only and is not used as the stored mime.",
        "tags": [
          "Database"
        ],
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Target DB path for the resource (decoded UTF-8)"
          },
          {
            "name": "mime",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Override the stored mime type. Omit to infer from the filename extension; set application/octet-stream to force raw-byte storage."
          }
        ],
        "requestBody": {
          "required": true,
          "description": "The raw resource content (the request Content-Type is transport only; use the `mime` query parameter to set the stored mime).",
          "content": {
            "*/*": { "schema": { "type": "string", "format": "binary" } }
          }
        },
        "responses": {
          "201": {
            "description": "Resource created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "path": { "type": "string", "description": "Canonical decoded DB path of the stored resource (may differ from the request path if the name was normalized)" }
                  },
                  "example": { "path": "/db/apps/myapp/test.xml" }
                }
              }
            }
          },
          "200": {
            "description": "Resource overwritten",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "path": { "type": "string", "description": "Canonical decoded DB path of the stored resource" }
                  },
                  "example": { "path": "/db/apps/myapp/test.xml" }
                }
              }
            }
          },
          "400": {
            "description": "Bad request — missing path, a path outside /db, or a store failure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove resource",
        "operationId": "db:remove-resource",
        "description": "Deletes a resource from the database. Requires write permission on the parent collection.",
        "tags": [
          "Database"
        ],
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Full DB path of the resource to remove"
          }
        ],
        "responses": {
          "200": {
            "description": "Resource successfully removed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "removed": {
                      "type": "string",
                      "description": "DB path of the removed resource"
                    }
                  },
                  "example": {
                    "removed": "/db/apps/myapp/test.xml"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Path is not under /db",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient permissions to remove the resource",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/db/collection": {
      "post": {
        "summary": "Create collection",
        "operationId": "db:create-collection",
        "description": "Creates a new collection. By default the parent collection must already exist — a missing parent returns 409. Pass `recursive: true` to create any missing ancestor collections (mkdir -p).",
        "tags": [
          "Database"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "path"
                ],
                "properties": {
                  "path": {
                    "type": "string",
                    "description": "Full DB path for the new collection"
                  },
                  "recursive": {
                    "type": "boolean",
                    "default": false,
                    "description": "Create any missing ancestor collections (mkdir -p). Default false: the parent collection must already exist."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Collection created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "created": {
                      "type": "string",
                      "description": "DB path of the created collection"
                    }
                  },
                  "example": {
                    "created": "/db/test"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request — missing or invalid path",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Parent collection does not exist (pass recursive=true to create intermediate collections)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove collection",
        "operationId": "db:remove-collection",
        "description": "Removes a collection from the database. Non-empty collections require the force parameter. Protected system collections cannot be removed.",
        "tags": [
          "Database"
        ],
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Full DB path of the collection to remove"
          },
          {
            "name": "force",
            "in": "query",
            "description": "Force removal of non-empty collections",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Collection removed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "removed": {
                      "type": "string",
                      "description": "DB path of the removed collection"
                    }
                  },
                  "example": {
                    "removed": "/db/test"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Path is not under /db",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient permissions to remove the collection",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Collection not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Collection is not empty and force was not set",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/db/move": {
      "post": {
        "summary": "Move or rename resource or collection",
        "operationId": "db:move",
        "description": "Moves or renames a resource or collection. The destination is given as an explicit `(parent, name)` pair — matching eXist's XML-RPC `moveResource` / `moveCollection` signature. Either `parent` or `newName` is required: `{source, parent}` moves into `parent` preserving source's leaf name; `{source, parent, name}` moves and renames; `{source, newName}` is a friendlier shortcut for in-place rename (equivalent to `parent = source's parent` + `name = newName`). `parent`, if supplied, must already exist as a collection.",
        "tags": [
          "Database"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "source"
                ],
                "properties": {
                  "source": {
                    "type": "string",
                    "description": "DB path of the resource/collection to move"
                  },
                  "parent": {
                    "type": "string",
                    "description": "Destination parent collection (must exist). Required unless `newName` is supplied."
                  },
                  "name": {
                    "type": "string",
                    "description": "Leaf name at the destination. Defaults to source's leaf when omitted."
                  },
                  "newName": {
                    "type": "string",
                    "description": "Shortcut for in-place rename. Equivalent to passing `parent = source's parent` and `name = newName`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resource or collection moved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "moved": {
                      "type": "string",
                      "description": "Original path of the moved item"
                    },
                    "to": {
                      "type": "string",
                      "description": "Full path of the moved item at its new location"
                    }
                  },
                  "example": {
                    "moved": "/db/test/a.xml",
                    "to": "/db/test2/a.xml"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request — missing source or target",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Source not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Destination already exists (refuse-to-overwrite)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Move failed mid-operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/db/copy": {
      "post": {
        "summary": "Copy resource or collection",
        "operationId": "db:copy",
        "description": "Copies a resource or collection. The destination is given as an explicit `(parent, name)` pair — matching eXist's XML-RPC `copyResource` / `copyCollection` signature. Either `parent` or `newName` is required: `{source, parent}` copies into `parent` preserving source's leaf name; `{source, parent, name}` copies and renames; `{source, newName}` is a friendlier shortcut for duplicating within source's own collection (equivalent to `parent = source's parent` + `name = newName`). `parent`, if supplied, must already exist as a collection.",
        "tags": [
          "Database"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "source"
                ],
                "properties": {
                  "source": {
                    "type": "string",
                    "description": "DB path of the resource/collection to copy"
                  },
                  "parent": {
                    "type": "string",
                    "description": "Destination parent collection (must exist). Required unless `newName` is supplied."
                  },
                  "name": {
                    "type": "string",
                    "description": "Leaf name for the copy. Defaults to source's leaf when omitted."
                  },
                  "newName": {
                    "type": "string",
                    "description": "Shortcut for duplicating within source's own collection under this leaf name. Equivalent to passing `parent = source's parent` and `name = newName`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resource or collection copied successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "copied": {
                      "type": "string",
                      "description": "Original path of the copied item"
                    },
                    "to": {
                      "type": "string",
                      "description": "Full path of the copy at its new location"
                    }
                  },
                  "example": {
                    "copied": "/db/test/a.xml",
                    "to": "/db/test2/a.xml"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request — missing source or target",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Source not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Destination already exists (refuse-to-overwrite)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Copy failed mid-operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/db/properties": {
      "get": {
        "summary": "Get resource/collection properties",
        "operationId": "db:properties",
        "description": "Returns detailed properties of a resource or collection including ownership, permissions, MIME type, size, and timestamps.",
        "tags": [
          "Database"
        ],
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Full DB path of the resource or collection"
          }
        ],
        "responses": {
          "200": {
            "description": "Resource or collection properties",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "path": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string",
                      "description": "Either 'resource' or 'collection'"
                    },
                    "owner": {
                      "type": "string"
                    },
                    "group": {
                      "type": "string"
                    },
                    "mode": {
                      "type": "string",
                      "description": "Unix-style permission string"
                    },
                    "acl": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "mime-type": {
                      "type": "string"
                    },
                    "size": {
                      "type": "integer",
                      "description": "Size in bytes"
                    },
                    "created": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "last-modified": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "example": {
                    "path": "/db/apps/myapp/index.xq",
                    "type": "resource",
                    "owner": "admin",
                    "group": "dba",
                    "mode": "rwxr-xr-x",
                    "acl": [],
                    "mime-type": "application/xquery",
                    "size": 1234,
                    "created": "2024-01-01T00:00:00.000-05:00",
                    "last-modified": "2024-01-01T00:00:00.000-05:00"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource or collection not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/db/sync": {
      "get": {
        "summary": "Sync tree with timestamps",
        "operationId": "db:sync",
        "description": "Returns a collection tree with lastModified timestamps. Supports incremental sync by filtering to resources modified after a given timestamp.",
        "tags": [
          "Database"
        ],
        "parameters": [
          {
            "name": "root",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "/db"
            },
            "description": "Collection root path"
          },
          {
            "name": "timestamp",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "ISO datetime — only return resources modified after this time"
          }
        ],
        "responses": {
          "200": {
            "description": "Hierarchical sync tree with timestamps for each item",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "root": {
                      "type": "string",
                      "description": "Root collection path"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Server timestamp of this sync snapshot"
                    },
                    "children": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "path": {
                            "type": "string"
                          },
                          "lastModified": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "children": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          }
                        }
                      }
                    }
                  },
                  "example": {
                    "root": "/db/apps/myapp",
                    "timestamp": "2024-01-01T12:00:00.000-05:00",
                    "children": [
                      {
                        "path": "modules",
                        "lastModified": "2024-01-01T00:00:00.000-05:00",
                        "children": [
                          {
                            "path": "app.xqm",
                            "lastModified": "2024-01-01T00:00:00.000-05:00"
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Root collection not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/db/permissions": {
      "post": {
        "summary": "Set permissions",
        "operationId": "db:set-permissions",
        "description": "Updates the owner, group, and/or mode of a resource or collection. Requires dba privileges or ownership of the item.",
        "tags": [
          "Database"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "path"
                ],
                "properties": {
                  "path": {
                    "type": "string",
                    "description": "DB path of the resource or collection"
                  },
                  "owner": {
                    "type": "string",
                    "description": "New owner username"
                  },
                  "group": {
                    "type": "string",
                    "description": "New group name"
                  },
                  "mode": {
                    "type": "string",
                    "description": "New permission mode, as a symbolic string. Three formats are accepted: (1) **simple symbolic** — `rwxr-xr-x` (9 characters covering user/group/other × read/write/execute); (2) **Unix symbolic** — relative form with `+`/`-`/`=` operators, e.g. `u+x,g-w` or `u=rwx,g=rx,o=r`; (3) **eXist symbolic** — verbose form like `user=+read,user=+write,group=+read,other=+read`. Octal strings (e.g. `0644`, `644`) are **not** accepted by the underlying `sm:chmod` string overload; clients that want to send a numeric mode must convert it to one of the symbolic forms first.",
                    "example": "rwxr-xr-x"
                  },
                  "mime": {
                    "type": "string",
                    "description": "New MIME (content) type for the resource (e.g. application/xml)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Permissions updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "updated": {
                      "type": "string",
                      "description": "DB path of the updated item"
                    }
                  },
                  "example": {
                    "updated": "/db/apps/myapp/index.xq"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request — missing path or invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/modules": {
      "get": {
        "summary": "Discover importable modules",
        "operationId": "db:modules",
        "description": "Returns importable modules from package-local files, mapped modules, and registered built-in modules. Used by IDE tools for import suggestions.",
        "tags": [
          "Database"
        ],
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Current file's DB path (used to find package root)"
          },
          {
            "name": "prefix",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by module prefix"
          },
          {
            "name": "uri",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Already-imported URIs to exclude (comma-separated)"
          }
        ],
        "responses": {
          "200": {
            "description": "Array of importable modules with their prefix, namespace, source, and origin",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "prefix": {
                        "type": "string",
                        "description": "Module prefix"
                      },
                      "namespace": {
                        "type": "string",
                        "description": "Module namespace URI"
                      },
                      "source": {
                        "type": "string",
                        "description": "Module source location"
                      },
                      "ref": {
                        "type": "string",
                        "description": "Origin: 'package', 'global', or 'mapped'"
                      }
                    }
                  },
                  "example": [
                    {
                      "prefix": "config",
                      "namespace": "http://myapp.com/config",
                      "source": "/db/apps/myapp/modules/config.xqm",
                      "ref": "package"
                    },
                    {
                      "prefix": "util",
                      "namespace": "http://exist-db.org/xquery/util",
                      "source": "java:org.exist.xquery...",
                      "ref": "global"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/users/whoami": {
      "get": {
        "summary": "Get current user identity",
        "operationId": "users:whoami",
        "description": "Returns the real and effective user identities and group memberships. Also serves as a capability probe: a 200 response indicates existdb-openapi is installed. Replaces xst's whoami.xq.",
        "tags": [
          "Users"
        ],
        "responses": {
          "200": {
            "description": "Current user identity with real and effective credentials",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "real": {
                      "type": "object",
                      "properties": {
                        "user": {
                          "type": "string"
                        },
                        "groups": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "effective": {
                      "type": "object",
                      "properties": {
                        "user": {
                          "type": "string"
                        },
                        "groups": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  },
                  "example": {
                    "real": {
                      "user": "admin",
                      "groups": [
                        "dba"
                      ]
                    },
                    "effective": {
                      "user": "admin",
                      "groups": [
                        "dba"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/users": {
      "get": {
        "summary": "List all users",
        "operationId": "users:list",
        "description": "Returns all user accounts in the database with their group memberships and enabled status. Requires dba privileges.",
        "tags": [
          "Users"
        ],
        "responses": {
          "200": {
            "description": "Array of user accounts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "groups": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "enabled": {
                        "type": "boolean"
                      }
                    }
                  },
                  "example": [
                    {
                      "name": "admin",
                      "groups": [
                        "dba"
                      ],
                      "enabled": true
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create user",
        "operationId": "users:create",
        "description": "Creates a new user account. Requires dba privileges. The user is automatically added to a personal group matching their username.",
        "tags": [
          "Users"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "password"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Username for the new account"
                  },
                  "password": {
                    "type": "string",
                    "description": "Password for the new account"
                  },
                  "groups": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Additional groups to assign"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "created": {
                      "type": "string",
                      "description": "Username of the created account"
                    }
                  },
                  "example": {
                    "created": "newuser"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request — missing required fields or user already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/users/{name}": {
      "get": {
        "summary": "Get user details",
        "operationId": "users:get",
        "description": "Returns detailed information about a user account including groups, primary group, enabled status, umask, and metadata.",
        "tags": [
          "Users"
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Username to look up"
          }
        ],
        "responses": {
          "200": {
            "description": "User account details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "groups": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "primaryGroup": {
                      "type": "string"
                    },
                    "enabled": {
                      "type": "boolean"
                    },
                    "umask": {
                      "type": "integer"
                    },
                    "metadata": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "value": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  },
                  "example": {
                    "name": "admin",
                    "groups": [
                      "dba"
                    ],
                    "primaryGroup": "dba",
                    "enabled": true,
                    "umask": 18,
                    "metadata": [
                      {
                        "key": "http://axschema.org/namePerson",
                        "value": "admin"
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Update user",
        "operationId": "users:update",
        "description": "Updates an existing user account. Can change password and/or group memberships. Requires dba privileges.",
        "tags": [
          "Users"
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Username to update"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "password": {
                    "type": "string",
                    "description": "New password"
                  },
                  "groups": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Updated group list"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "User updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "updated": {
                      "type": "string",
                      "description": "Username of the updated account"
                    }
                  },
                  "example": {
                    "updated": "newuser"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request — invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove user",
        "operationId": "users:remove",
        "description": "Deletes a user account from the database. The user's personal group is also removed. Requires dba privileges.",
        "tags": [
          "Users"
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Username to remove"
          }
        ],
        "responses": {
          "200": {
            "description": "User removed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "removed": {
                      "type": "string",
                      "description": "Username of the removed account"
                    }
                  },
                  "example": {
                    "removed": "newuser"
                  }
                }
              }
            }
          },
          "403": {
            "description": "Cannot remove system users or insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/groups": {
      "get": {
        "summary": "List all groups",
        "operationId": "users:list-groups",
        "description": "Returns all groups in the database with their managers and members. Requires dba privileges.",
        "tags": [
          "Groups"
        ],
        "responses": {
          "200": {
            "description": "Array of groups",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "managers": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "members": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "example": [
                    {
                      "name": "dba",
                      "managers": [
                        "admin"
                      ],
                      "members": [
                        "SYSTEM",
                        "admin"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create group",
        "operationId": "users:create-group",
        "description": "Creates a new group. The calling user is automatically added as a manager. Requires dba privileges.",
        "tags": [
          "Groups"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Name for the new group"
                  },
                  "managers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Initial group managers"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Group created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "created": {
                      "type": "string",
                      "description": "Name of the created group"
                    }
                  },
                  "example": {
                    "created": "newgroup"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request — missing name or group already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/groups/{name}": {
      "get": {
        "summary": "Get group details",
        "operationId": "users:get-group",
        "description": "Returns detailed information about a group including managers, members, and metadata.",
        "tags": [
          "Groups"
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Group name to look up"
          }
        ],
        "responses": {
          "200": {
            "description": "Group details with managers, members, and metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "managers": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "members": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "metadata": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "value": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  },
                  "example": {
                    "name": "dba",
                    "managers": [
                      "admin"
                    ],
                    "members": [
                      "SYSTEM",
                      "admin"
                    ],
                    "metadata": [
                      {
                        "key": "http://exist-db.org/security/description",
                        "value": "Database Administrators"
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Group not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove group",
        "operationId": "users:remove-group",
        "description": "Deletes a group from the database. System groups (dba, guest) cannot be removed. Requires dba privileges.",
        "tags": [
          "Groups"
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Group name to remove"
          }
        ],
        "responses": {
          "200": {
            "description": "Group removed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "removed": {
                      "type": "string",
                      "description": "Name of the removed group"
                    }
                  },
                  "example": {
                    "removed": "newgroup"
                  }
                }
              }
            }
          },
          "403": {
            "description": "Cannot remove system groups or insufficient permissions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Group not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/packages": {
      "get": {
        "summary": "List installed packages",
        "operationId": "packages:list",
        "description": "Returns all EXPath packages installed in the database with detailed metadata including version, dependencies, components, and processor compatibility.",
        "tags": [
          "Packages"
        ],
        "responses": {
          "200": {
            "description": "Array of installed packages",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "uri": {
                        "type": "string",
                        "description": "Package URI"
                      },
                      "name": {
                        "type": "string",
                        "description": "Package name (typically same as URI)"
                      },
                      "abbrev": {
                        "type": "string",
                        "description": "Short abbreviation"
                      },
                      "version": {
                        "type": "string"
                      },
                      "title": {
                        "type": "string"
                      },
                      "processor": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "semverMin": {
                              "type": "string",
                              "nullable": true
                            },
                            "semverMax": {
                              "type": "string",
                              "nullable": true
                            },
                            "semver": {
                              "type": "string",
                              "nullable": true
                            },
                            "versions": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      },
                      "dependencies": {
                        "type": "array",
                        "items": {
                          "type": "object"
                        }
                      },
                      "components": {
                        "type": "object",
                        "properties": {
                          "xquery": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "xslt": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "jar": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        }
                      },
                      "website": {
                        "type": "string"
                      },
                      "description": {
                        "type": "string"
                      },
                      "license": {
                        "type": "string"
                      },
                      "authors": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "type": {
                        "type": "string",
                        "description": "Package type: application or library"
                      },
                      "target": {
                        "type": "string",
                        "description": "Installation target collection name"
                      },
                      "date": {
                        "type": "string",
                        "format": "date-time"
                      }
                    }
                  },
                  "example": [
                    {
                      "uri": "http://exist-db.org/pkg/api",
                      "name": "http://exist-db.org/pkg/api",
                      "abbrev": "existdb-openapi",
                      "version": "0.9.0-SNAPSHOT",
                      "title": "Platform API Module",
                      "processor": [
                        {
                          "name": "http://exist-db.org",
                          "semverMin": "7.0.0-SNAPSHOT",
                          "semverMax": null,
                          "semver": null,
                          "versions": []
                        }
                      ],
                      "dependencies": [],
                      "components": {
                        "xquery": [],
                        "xslt": [],
                        "jar": [
                          "existdb-openapi-0.9.0-SNAPSHOT.jar"
                        ]
                      },
                      "website": "",
                      "description": "Unified platform API",
                      "license": "LGPL-2.1",
                      "authors": [
                        "eXist-db"
                      ],
                      "type": "application",
                      "target": "existdb-openapi",
                      "date": "2024-01-01T00:00:00Z"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/packages/install": {
      "post": {
        "summary": "Install package",
        "operationId": "packages:install",
        "description": "Installs a package from the public repository by name/URL, or from an uploaded .xar file. The package is deployed automatically after installation.",
        "tags": [
          "Packages"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Package name (URI) to install from registry"
                  },
                  "url": {
                    "type": "string",
                    "description": "Registry find URL"
                  },
                  "version": {
                    "type": "string",
                    "description": "Specific version to install (empty for latest)"
                  }
                }
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Package installed and deployed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "result": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "description": "Package URI"
                        },
                        "version": {
                          "type": "string"
                        },
                        "target": {
                          "type": "string",
                          "description": "Installation target path"
                        }
                      }
                    }
                  },
                  "example": {
                    "success": true,
                    "result": {
                      "name": "http://www.functx.com",
                      "version": "",
                      "target": "/db/system/repo/functx-1.0.1"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request — missing package name/URL or invalid .xar file",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/packages/{name}": {
      "get": {
        "summary": "Package details",
        "operationId": "packages:get",
        "description": "Returns detailed metadata for a single installed package identified by its abbreviation.",
        "tags": [
          "Packages"
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Package abbreviation (e.g. 'existdb-openapi')"
          }
        ],
        "responses": {
          "200": {
            "description": "Package details (same shape as items in the package list)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "uri": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "abbrev": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "processor": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "dependencies": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "components": {
                      "type": "object"
                    },
                    "website": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "license": {
                      "type": "string"
                    },
                    "authors": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "type": {
                      "type": "string"
                    },
                    "target": {
                      "type": "string"
                    },
                    "date": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "example": {
                    "uri": "http://exist-db.org/pkg/api",
                    "name": "http://exist-db.org/pkg/api",
                    "abbrev": "existdb-openapi",
                    "version": "0.9.0-SNAPSHOT",
                    "title": "Platform API Module",
                    "processor": [
                      {
                        "name": "http://exist-db.org",
                        "semverMin": "7.0.0-SNAPSHOT",
                        "semverMax": null,
                        "semver": null,
                        "versions": []
                      }
                    ],
                    "dependencies": [],
                    "components": {
                      "xquery": [],
                      "xslt": [],
                      "jar": [
                        "existdb-openapi-0.9.0-SNAPSHOT.jar"
                      ]
                    },
                    "website": "",
                    "description": "Unified platform API",
                    "license": "LGPL-2.1",
                    "authors": [
                      "eXist-db"
                    ],
                    "type": "application",
                    "target": "existdb-openapi",
                    "date": "2024-01-01T00:00:00Z"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Package not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove package",
        "operationId": "packages:remove",
        "description": "Undeploys and removes an installed package. Fails if other packages depend on it unless force=true is set.",
        "tags": [
          "Packages"
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Package abbreviation to remove"
          },
          {
            "name": "force",
            "in": "query",
            "description": "Force removal even if dependents exist",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Package undeployed and removed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "Package URI"
                    },
                    "undeploy": {
                      "type": "boolean",
                      "description": "Whether undeployment succeeded"
                    },
                    "remove": {
                      "type": "boolean",
                      "description": "Whether removal succeeded"
                    }
                  },
                  "example": {
                    "name": "http://www.functx.com",
                    "undeploy": true,
                    "remove": true
                  }
                }
              }
            }
          },
          "404": {
            "description": "Package not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Other packages depend on this one — use force=true to override",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "dependents": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "URIs of dependent packages"
                    },
                    "hint": {
                      "type": "string"
                    }
                  },
                  "example": {
                    "error": "Cannot remove: other packages depend on http://www.functx.com",
                    "dependents": [
                      "http://other/pkg"
                    ],
                    "hint": "Use force=true"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/packages/update-check": {
      "post": {
        "summary": "Check for package updates",
        "operationId": "packages:update-check",
        "description": "Queries the public package repository to check whether newer versions are available for any installed packages.",
        "tags": [
          "Packages"
        ],
        "responses": {
          "200": {
            "description": "Update availability report from the registry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "registry": {
                      "type": "string",
                      "description": "Registry URL that was queried"
                    },
                    "updates": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string",
                            "description": "Package URI"
                          },
                          "abbrev": {
                            "type": "string"
                          },
                          "installed": {
                            "type": "string",
                            "description": "Currently installed version"
                          },
                          "available": {
                            "type": "string",
                            "description": "Latest available version"
                          }
                        }
                      }
                    }
                  },
                  "example": {
                    "registry": "https://exist-db.org/exist/apps/public-repo",
                    "updates": [
                      {
                        "name": "http://www.functx.com",
                        "abbrev": "functx",
                        "installed": "1.0.0",
                        "available": "1.0.1"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "summary": "Sitewide search",
        "operationId": "search:query",
        "description": "Performs a full-text search across all installed applications. Results include snippets with highlighted matches and links to the source documents.",
        "tags": [
          "Search"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Search query string"
          },
          {
            "name": "app",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Restrict to a single app via the site-app facet (e.g. docs, blog, notebook)"
          },
          {
            "name": "section",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Restrict to a section within an app via the site-section facet (e.g. functions, posts)"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            },
            "description": "Maximum number of results to return (page size)"
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            },
            "description": "Zero-based index of the first result to return (for paging)"
          }
        ],
        "responses": {
          "200": {
            "description": "Search results with total count, relevance scores, and KWIC-highlighted snippets",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "string",
                      "description": "The search query that was executed"
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total number of matching results"
                    },
                    "offset": {
                      "type": "integer",
                      "description": "Zero-based index of the first result in this page"
                    },
                    "limit": {
                      "type": "integer",
                      "description": "Page size that was applied"
                    },
                    "facets": {
                      "type": "object",
                      "description": "Facet counts for building a filter UI: each dimension maps facet values to hit counts.",
                      "properties": {
                        "site-app": {
                          "type": "object",
                          "additionalProperties": { "type": "integer" },
                          "description": "Hit count per app (e.g. { \"docs\": 88, \"blog\": 21 })"
                        },
                        "site-section": {
                          "type": "object",
                          "additionalProperties": { "type": "integer" },
                          "description": "Hit count per section"
                        }
                      }
                    },
                    "results": {
                      "type": "array",
                      "description": "Results ordered by descending relevance score",
                      "items": {
                        "type": "object",
                        "properties": {
                          "uri": {
                            "type": "string",
                            "description": "Canonical DB path of the matching document (open over exist:)"
                          },
                          "path": {
                            "type": "string",
                            "description": "DB path of the matching document (alias of uri)"
                          },
                          "title": {
                            "type": "string"
                          },
                          "app": {
                            "type": "string",
                            "description": "Source app abbreviation"
                          },
                          "url": {
                            "type": "string",
                            "description": "HTTP-accessible URL"
                          },
                          "score": {
                            "type": "number",
                            "description": "Lucene relevance score (higher is more relevant)"
                          },
                          "snippet": {
                            "type": "string",
                            "description": "First KWIC fragment as a well-formed XML string: a single <span> root with matched terms in <mark>. Parse with fn:parse-xml (no parse-xml-fragment needed); also valid HTML for innerHTML."
                          },
                          "highlights": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "KWIC fragments centered on a match. Each is a well-formed XML string (a single <span> root with matched terms in <mark>), parseable with fn:parse-xml."
                          }
                        }
                      }
                    }
                  },
                  "example": {
                    "query": "url rewriting",
                    "total": 22,
                    "offset": 0,
                    "limit": 20,
                    "facets": {
                      "site-app": { "docs": 18, "blog": 4 },
                      "site-section": { }
                    },
                    "results": [
                      {
                        "uri": "/db/apps/doc/data/urlrewrite/urlrewrite.xml",
                        "path": "/db/apps/doc/data/urlrewrite/urlrewrite.xml",
                        "title": "URL Rewriting",
                        "app": "doc",
                        "url": "/exist/apps/doc/data/urlrewrite/urlrewrite.xml",
                        "score": 8.42,
                        "snippet": "<span>...eXist-db's <mark>URL</mark> <mark>rewriting</mark> lets you map...</span>",
                        "highlights": [
                          "<span>...eXist-db's <mark>URL</mark> <mark>rewriting</mark> lets you map...</span>"
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/site/apps": {
      "get": {
        "summary": "List installed apps",
        "operationId": "site:apps",
        "description": "Returns all installed applications with their title, version, URL, and icon. Used for building navigation menus and app launchers.",
        "tags": [
          "Site"
        ],
        "responses": {
          "200": {
            "description": "Array of installed applications",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "description": "Package URI"
                      },
                      "abbrev": {
                        "type": "string",
                        "description": "Short abbreviation"
                      },
                      "title": {
                        "type": "string",
                        "description": "Human-readable title"
                      },
                      "version": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string",
                        "description": "Base URL for the app"
                      },
                      "icon": {
                        "type": "string",
                        "description": "Icon URL (empty if none)"
                      }
                    }
                  },
                  "example": [
                    {
                      "name": "http://exist-db.org/apps/dashboard",
                      "abbrev": "dashboard",
                      "title": "Dashboard",
                      "version": "2.0.9",
                      "url": "/exist/apps/dashboard/",
                      "icon": ""
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/site/resolve": {
      "get": {
        "summary": "Resolve cross-app link",
        "operationId": "site:resolve",
        "description": "Resolves a cross-application link by mapping an app abbreviation and path to the correct URL. Used for inter-app navigation without hardcoding paths.",
        "tags": [
          "Site"
        ],
        "parameters": [
          {
            "name": "app",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Target app abbreviation"
          },
          {
            "name": "path",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Path within the target app"
          }
        ],
        "responses": {
          "200": {
            "description": "Resolved URL for the cross-app link",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "description": "Fully resolved URL"
                    }
                  },
                  "example": {
                    "url": "/exist/apps/doc/getting-started"
                  }
                }
              }
            }
          },
          "404": {
            "description": "App not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/eval": {
      "post": {
        "summary": "Evaluate query and return serialized results as plain text",
        "operationId": "query:eval",
        "description": "Executes an XQuery expression and returns results serialized as plain text. Accepts the same serialization parameters as GET /api/query/{id}/results (method, indent, omit-xml-declaration, etc.). Designed for interactive try-it widgets where a single round-trip is preferred over the cursor pattern.",
        "tags": [
          "Query"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "XQuery expression to evaluate"
                  },
                  "count": {
                    "type": "integer",
                    "default": 50,
                    "description": "Maximum number of items to return"
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "adaptive",
                      "xml",
                      "html",
                      "html5",
                      "text",
                      "json"
                    ],
                    "default": "adaptive",
                    "description": "Serialization method"
                  },
                  "indent": {
                    "type": "string",
                    "enum": [
                      "yes",
                      "no"
                    ],
                    "default": "yes",
                    "description": "Whether to indent serialized output"
                  },
                  "omit-xml-declaration": {
                    "type": "string",
                    "enum": [
                      "yes",
                      "no"
                    ],
                    "default": "yes",
                    "description": "Whether to omit the XML declaration"
                  },
                  "encoding": {
                    "type": "string",
                    "description": "Character encoding (e.g. UTF-8)"
                  },
                  "item-separator": {
                    "type": "string",
                    "description": "String inserted between serialized items"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Query results serialized as plain text",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/langservice/capabilities": {
      "get": {
        "summary": "Capability discovery",
        "description": "Returns the set of language-service features the running existdb-openapi instance supports.",
        "operationId": "langservice:capabilities",
        "tags": [
          "Language Service"
        ],
        "responses": {
          "200": {
            "description": "Capability map",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  }
}