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.

{
  "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.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/....