Phonemos User Guide

Phonemos REST API

The REST API provides programmatic access to the core functionality of Phonemos. You can read and write wiki page content across languages and revisions, navigate and query the object hierarchy, read and update metadata on any object, search for content and users, and trigger exports in a variety of formats (PDF, DOCX, Markdown, LaTeX, archive, and more).

It is designed for stable, long-term integrations — the API is versioned and Phonemos commits to not introducing breaking changes within a version.

Full interactive documentation including all endpoints, parameters, and request/response schemas is available in the published Swagger documentation at /_api/rest/docs/ on your instance.

Endpoints

Objects are the central resource of the API — everything in Phonemos (topics, zones, pages, and more) is an object with a unique ID. The /objects endpoints provide access to properties common to all objects: details, hierarchy, and metadata. The /objects/metadata-schema endpoints expose the metadata schema that applies to an object or its children.

Certain object types have additional endpoints that expose type-specific functionality. Pages, for example, have /pages endpoints for reading and writing content across languages and revisions. These share the same ID as the underlying object — an object ID and its corresponding page ID are interchangeable.

Beyond objects, the API also covers /users for looking up user accounts, /data/fields for resolving metadata field definitions and their options, and /exports for triggering and downloading exports in various formats.

See the Swagger documentation for more details.

Authentication

All endpoints require an OAuth 2.0 Bearer token passed in the Authorization header:

1 Authorization: Bearer <token>

Tokens can be obtained through your Phonemos instance's identity provider (Keycloak). Service accounts are the recommended approach for automated integrations.

Headers

Request headers

Authentication (all endpoints)

  • Authorization: Bearer <token> — required on every request

Content negotiation (page content endpoints)

  • Accept — desired response format; application/json (default) or text/plain

  • Accept-Language — preferred languages in RFC 7231 format, e.g. de, en;q=0.9

  • Phonemos-Autotranslate — boolean; if true, requests auto-translation when no preferred language is available

Metadata write endpoints

  • Phonemos-Invalid-Data-Handling — how to handle invalid metadata values: reject (default, returns an error) or drop (silently ignores invalid values)

Response headers

Page content responses

  • Content-Language — language of the returned content

  • Phonemos-Object-Id — wikipage object ID

  • Phonemos-Branch-Id — branch ID (when available)

  • Phonemos-Content-Id — content ID (when available)

  • Phonemos-Revision-Id — revision ID (when available)

  • Phonemos-Revision-Number — revision number (when available)

  • Phonemos-Autotranslated — whether the content was auto-translated

Downloads (307 redirect)

  • Location — URL to the exported file