Hymnography Endpoint

Get troparia, kontakia, prayers, magnifications, hagiographies, and icon metadata for one or more internal calendar ids.

hagiography content is currently work in progress. Coverage is incomplete, some saint entries do not yet include narrative data, and existing texts/titles/metadata may be expanded or refined as source material is reviewed.

Request

GET /hymnography/?id=387&id=391&id=theodore_tyron_saturday_first_week_lent

Parameters:

Parameter	Type	In	Description
`id`	string[]	query	Repeatable internal ids (`1..24` values). Example: `?id=387&id=391`.
`lang`	string	query	`ru` (default) or `en` (meta/error localization).

Validation:

max 24 ids;
each id length: 1..128;
pattern: ^[A-Za-z0-9_][A-Za-z0-9._:-]{0,127}$.

Response

Returns an ordered array in data, preserving the same order as requested ids.

found=true: hymnography payload for this id.
found=false: empty collections + notFound object for this id.
icons[]: zero or more local icon assets for the same id, each with relative path, absolute url, localized title/description, and optional metadata.
The movable saint ID anna_kashinskaya resolves the texts and icons stored under fixed saint ID 1372; the response still returns "id": "anna_kashinskaya".

Some movable event IDs resolve their content from another record; the response always echoes back the ID that was requested. In addition to anna_kashinskaya above:

Requested ID	Content served from
`lazarus_saturday`	`resurrection_of_righteous_lazarus`
`second_sunday_lent`	`gregory_palamas_second_sunday_lent`
`fourth_sunday_lent`	`john_climacus_fourth_sunday_lent`
`fifth_sunday_lent`	`mary_of_egypt_fifth_sunday_lent`

These days appear twice in the calendar — once as the season event and once as the movable commemoration that owns the service — so a single record serves both IDs.

{
  "meta": {
    "lang": "ru",
    "format": "html",
    "requestedIds": ["387", "391", "unknown_item"],
    "count": 2
  },
  "data": [
    {
      "id": "387",
      "found": true,
      "troparia": [
        {
          "delta": 0,
          "tone": 4,
          "texts": [
            { "lang": "cu", "value": "<p>...</p>" },
            { "lang": "ru", "value": "<p>...</p>" }
          ]
        }
      ],
      "kontakia": [],
      "prayers": [],
      "magnifications": [],
      "hagiography": {
        "links": [
          {
            "url": "https://example.com/sermons/lazarus-saturday",
            "text": {
              "ru": "Sermon for Lazarus Saturday",
              "en": "Sermon for Lazarus Saturday"
            },
            "title": {
              "ru": "Sermon for Lazarus Saturday",
              "en": "Sermon for Lazarus Saturday"
            },
            "author": {
              "ru": "Selected author"
            }
          }
        ],
        "short": null,
        "full": null
      },
      "icons": [
        {
          "path": "/images/icons/421/421-001-eustathius-of-antioch.svg",
          "url": "https://api.ispovednik.org/images/icons/421/421-001-eustathius-of-antioch.svg",
          "title": {
            "texts": [
              { "lang": "ru", "value": "Икона святителя Евстафия Антиохийского" },
              { "lang": "en", "value": "Icon of Saint Eustathius of Antioch" }
            ]
          },
          "description": null,
          "mimeType": "image/svg+xml",
          "width": 256,
          "height": 256,
          "sortOrder": 1
        }
      ]
    },
    {
      "id": "unknown_item",
      "found": false,
      "troparia": [],
      "kontakia": [],
      "prayers": [],
      "magnifications": [],
      "hagiography": null,
      "icons": [],
      "notFound": {
        "code": "ID_NOT_FOUND",
        "message": "No hymnography found for requested id."
      }
    }
  ]
}

Notes

troparia and kontakia use shared delta for pairing.
prayers and magnifications each use independent delta sequences.
texts[].value is sanitized HTML with allowlisted tags only: p, br, h2, h3, ul, ol, li, strong, em, and safe internal footnote anchors via a.
Anchor tags are limited to local fragment links only: href="#..." and optional id="..."; external links and other attributes are stripped.
hagiography.short.title and hagiography.full.title provide localized precomputed headings (plain text).
hagiography.links[] contains manually curated external reading links for the whole hagiography section. Each link uses an absolute https:// URL, a short plain-text text object with ru and/or en, a localized plain-text title object, and an optional localized plain-text author object.
In source data, hagiography.links[].title is optional. In the API response, title is always present and defaults per language to text when no explicit title value is provided.
In source data, hagiography.links[].author is optional. When present, it is returned as provided; there is no fallback default for author metadata.
hagiography.links[] must not point back to provenance/source domains used for harvesting or reference extraction.
hagiography.full is either a single narrative object, an array of narrative objects when a commemoration carries several distinct narratives (for example separate accounts by different authors), or null. Clients must handle both the object and the array form.
Entries in the hagiography.full array keep their source order, and each entry only exposes the languages it is actually written in — a narrative that exists only in English returns a single en text and is never merged with a neighbouring Russian narrative.
hagiography.full.type classifies full narrative blocks:
- hagiography: saint life (default for existing and new saint entries).
- history: icon history (used for icon entries, for UI heading "History").
Hagiography coverage is best-effort during the current rollout: some ids return hagiography: null, some entries may contain only partial narrative material, and the corpus continues to be reviewed and expanded.
icons[].url is generated from the current request origin, so local/dev hosts return local absolute URLs while production returns https://api.ispovednik.org/....