Set document page settings

The document-server API lets you set page settings — including the header and footer distance — when you create a document and when you update an existing document's page metadata. The same settings are available through the document_server_set_page_settings MCP tool. Distances are measured in millimetres in the API and MCP, and in centimetres in the editor UI.

Authentication

Every /api route requires a Bearer token. Send Authorization: Bearer <token> on each request. The MCP endpoint at https://documents.templi.ai/mcp requires a Bearer JWT. Unauthenticated requests are rejected.

Create a document with page settings

POST /api/documents/create creates a document. Pass an optional pageSettings object in the request body to set the page layout at creation time.

{
  "pageSettings": {
    "header_distance": 15,
    "footer_distance": 12,
    "paper_size": "A4",
    "paper_orientation": "portrait",
    "paper_colour": "#FFFFFF",
    "margins": {
      "top": 20,
      "right": 20,
      "bottom": 20,
      "left": 20
    }
  }
}

A successful create returns HTTP 201 with a body containing name, createdAt, and updatedAt. Creating a document with a duplicate identifier returns HTTP 409.

Update page metadata

PUT /api/documents/:identifier/page-meta updates the page settings of an existing document. The request body must include pageSettings and/or headerFooter; a request with neither returns HTTP 400 with the message 'pageSettings' or 'headerFooter' is required. Updating a document that does not exist returns HTTP 404 with the message Document not found.

{
  "pageSettings": {
    "header_distance": 18,
    "footer_distance": 10
  }
}

A successful update returns a body containing name and updatedAt.

pageSettings fields

Validation is strict: unknown properties in pageSettings are rejected.

Set page settings with the MCP tool

The document_server_set_page_settings MCP tool sets page settings on a document in scope. Its inputs are document_id (string) plus header_distance, footer_distance, paper_size, paper_orientation, paper_colour, and margins, with the same millimetre and non-negative validation as the HTTP API.

The tool confirms each change with a response message: Header distance set to <value>mm and Footer distance set to <value>mm. When no settings are supplied, it returns No page settings changed. When no document is in scope, it returns No document in scope — pass document_id.

Units

The API and MCP tool accept and return distances in millimetres. The editor UI displays these distances in centimetres. Convert between the two when moving between the editor and the API or MCP.

Errors

The page-meta endpoint returns HTTP 400 with 'pageSettings' or 'headerFooter' is required when the body has neither field, and HTTP 404 with Document not found when the document does not exist. The create endpoint returns HTTP 409 for a duplicate identifier. Non-negative validation rejects negative distance values, and strict validation rejects unknown properties in pageSettings.