API Docs

Service root

GET /api/v1/

Read service and version metadata. The descriptor currently reports pre-release; it is not a resource availability inventory.

No parameters.

Example request

GET /api/v1/ HTTP/1.1
Host: YOUR_API_HOST
Accept: application/json

Example response · 200 OK

{
  "service": "fast-and-pray",
  "version": "v1",
  "base_path": "/api/v1/",
  "status": "pre-release"
}

Churches

GET /api/v1/churches/

Discover churches and the IDs used by church-scoped requests. Names are canonical; lang is ignored.

Example request

GET /api/v1/churches/?limit=25&offset=0 HTTP/1.1
Host: YOUR_API_HOST
Accept: application/json

Example response · 200 OK

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Armenian Apostolic Church"
    }
  ]
}

Icons

GET /api/v1/icons/

Browse icons, optionally filtered by church. Titles are canonical; lang is ignored. Omit church_id to include all churches.

Example request

GET /api/v1/icons/?church_id=1&limit=25 HTTP/1.1
Host: YOUR_API_HOST
Accept: application/json

Example response · 200 OK

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 12,
      "title": "Holy Cross",
      "image_url": null,
      "thumbnail_url": null
    }
  ]
}

Fasts in a range

GET /api/v1/fasts/

Find fasts with stored days overlapping the inclusive range. After filling either omitted bound, the range must be ordered and span at most 366 inclusive days.

Example request

GET /api/v1/fasts/?church_id=1&start_date=2026-09-01&end_date=2026-09-30&lang=en HTTP/1.1
Host: YOUR_API_HOST
Accept: application/json

Example response · 200 OK

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 7,
      "church_id": 1,
      "name": "Fast of the Holy Cross",
      "description": "A period of fasting before the Feast of the Holy Cross.",
      "start_date": "2026-09-07",
      "end_date": "2026-09-11",
      "culmination_feast": "Exaltation of the Holy Cross",
      "culmination_feast_date": "2026-09-13",
      "year": 2026,
      "image_url": null,
      "thumbnail_url": null,
      "learn_more_url": null
    }
  ]
}

One fast

GET /api/v1/fasts/{id}/

Read one fast by ID. An unknown ID returns resource_not_found (404).

Example request

GET /api/v1/fasts/7/?lang=en HTTP/1.1
Host: YOUR_API_HOST
Accept: application/json

Example response · 200 OK

{
  "id": 7,
  "church_id": 1,
  "name": "Fast of the Holy Cross",
  "description": "A period of fasting before the Feast of the Holy Cross.",
  "start_date": "2026-09-07",
  "end_date": "2026-09-11",
  "culmination_feast": "Exaltation of the Holy Cross",
  "culmination_feast_date": "2026-09-13",
  "year": 2026,
  "image_url": null,
  "thumbnail_url": null,
  "learn_more_url": null
}

Fasts by date

GET /api/v1/fasts/by-date/

Find fasts with a stored day on the given inclusive calendar date.

Example request

GET /api/v1/fasts/by-date/?church_id=1&date=2026-09-09&lang=en HTTP/1.1
Host: YOUR_API_HOST
Accept: application/json

Example response · 200 OK

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 7,
      "church_id": 1,
      "name": "Fast of the Holy Cross",
      "description": "A period of fasting before the Feast of the Holy Cross.",
      "start_date": "2026-09-07",
      "end_date": "2026-09-11",
      "culmination_feast": "Exaltation of the Holy Cross",
      "culmination_feast_date": "2026-09-13",
      "year": 2026,
      "image_url": null,
      "thumbnail_url": null,
      "learn_more_url": null
    }
  ]
}

Fasts by feast date

GET /api/v1/fasts/by-feast-date/

Find fasts whose culmination feast falls on the given date.

Example request

GET /api/v1/fasts/by-feast-date/?church_id=1&date=2026-09-13&lang=en HTTP/1.1
Host: YOUR_API_HOST
Accept: application/json

Example response · 200 OK

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 7,
      "church_id": 1,
      "name": "Fast of the Holy Cross",
      "description": "A period of fasting before the Feast of the Holy Cross.",
      "start_date": "2026-09-07",
      "end_date": "2026-09-11",
      "culmination_feast": "Exaltation of the Holy Cross",
      "culmination_feast_date": "2026-09-13",
      "year": 2026,
      "image_url": null,
      "thumbnail_url": null,
      "learn_more_url": null
    }
  ]
}

Readings

GET /api/v1/readings/

Read stored Scripture citations, ordered by sequence then ID. An unimported day returns an empty readings array. No passage text is returned or retrieved.

Example request

GET /api/v1/readings/?church_id=1&date=2026-09-13&lang=en HTTP/1.1
Host: YOUR_API_HOST
Accept: application/json

Example response · 200 OK

{
  "date": "2026-09-13",
  "readings": [
    {
      "id": 42,
      "sequence": 1,
      "book": "John",
      "start_chapter": 3,
      "start_verse": 13,
      "end_chapter": 3,
      "end_verse": 21
    }
  ]
}

Feasts

GET /api/v1/feasts/

Resolve commemorations through the offline church calendar and return stored feasts in service order, without duplicates. No matches return an empty feasts array; no rows are created.

Example request

GET /api/v1/feasts/?church_id=1&date=2026-09-13&lang=en HTTP/1.1
Host: YOUR_API_HOST
Accept: application/json

Example response · 200 OK

{
  "date": "2026-09-13",
  "feasts": [
    {
      "name": "Exaltation of the Holy Cross",
      "icon": {
        "id": 12,
        "title": "Holy Cross",
        "image_url": null,
        "thumbnail_url": null
      }
    }
  ]
}

Calendar

GET /api/v1/calendar/

Combine stored readings, church, fast and feasts for one day. fast is the lowest-ID active Fast or null. feasts and partial_failures are always arrays.

Example request

GET /api/v1/calendar/?church_id=1&date=2026-09-13&lang=en&tz=UTC HTTP/1.1
Host: YOUR_API_HOST
Accept: application/json

Example response · 200 OK

{
  "date": "2026-09-13",
  "church": {
    "id": 1,
    "name": "Armenian Apostolic Church"
  },
  "readings": [
    {
      "id": 42,
      "sequence": 1,
      "book": "John",
      "start_chapter": 3,
      "start_verse": 13,
      "end_chapter": 3,
      "end_verse": 21
    }
  ],
  "fast": null,
  "feasts": [
    {
      "name": "Exaltation of the Holy Cross",
      "icon": {
        "id": 12,
        "title": "Holy Cross",
        "image_url": null,
        "thumbnail_url": null
      }
    }
  ],
  "partial_failures": []
}

Response fields

Examples show the exact current field sets. IDs are integers. Feast objects expose only name and icon; they have no public identifier. Church name, Icon title, Feast name, and Fast name are strings. Icon image and thumbnail URLs are strings or null; thumbnails are returned only when already cached. Feast icon is an Icon object or null; it is null when absent or when its church differs from the Feast.

Fast church_id is an integer; description and culmination_feast are strings or null; year is an integer or null. All three Fast date fields are ISO dates or null. Fast image, thumbnail, and learn-more URLs are strings or null. Date bounds come from stored fast days.

Reading sequence is an integer or null; book is a string; chapter and verse fields are integers. Readings contain citations only, with no passage text.

Calendar always returns date, church, readings, fast, feasts, and partial_failures. Empty resources are normal and leave partial_failures empty. Explicit feast-data unavailability returns 200 with an empty feasts array and this partial_failures entry:

[{"component": "feasts", "code": "data_unavailable"}]

Each entry has exactly these two string fields. Invalid input fails the whole request with 400; unexpected errors or database failures fail the whole request with 503.

Errors

Every error has code, message, and an object-valued details. Codes and documented details keys are stable; message wording may change.

Unknown v1 paths return 404 JSON regardless of method or Accept header. Unsupported methods return 405 with Allow: GET, HEAD, OPTIONS; an unsupported Accept header returns 406 JSON.

HTTP 400

/api/v1/readings/?church_id=1&date=tomorrow

{
  "code": "invalid_date",
  "message": "date must use ISO YYYY-MM-DD format.",
  "details": {
    "parameter": "date",
    "value": "tomorrow"
  }
}

HTTP 404

/api/v1/unknown/

{
  "code": "not_found",
  "message": "The requested route does not exist.",
  "details": {}
}

HTTP 405

POST /api/v1/

{
  "code": "method_not_allowed",
  "message": "Method \"POST\" not allowed.",
  "details": {}
}

HTTP 406

GET /api/v1/ with Accept: text/html

{
  "code": "not_acceptable",
  "message": "Could not satisfy the request Accept header.",
  "details": {}
}

HTTP 429

Anonymous quota exceeded; Retry-After: 30

{
  "code": "throttled",
  "message": "Request limit exceeded.",
  "details": {
    "retry_after": 30
  }
}

HTTP 503

Admission store unavailable; Retry-After: 5

{
  "code": "service_unavailable",
  "message": "Please retry shortly.",
  "details": {
    "retry_after": 5
  }
}

Fair use and freshness

Limits are 60 requests per minute and 1000 requests per hour per client IP across routes and methods, including HEAD and errors. Both fixed windows must allow a request. Shared networks share an allowance. Windows follow server time; rejected requests do not extend them. CORS preflight handled by the outer middleware does not consume the allowance. Session cookies and bearer tokens grant no additional quota.

On 429, wait at least the integer seconds in Retry-After (also in details.retry_after), then add jitter. The header is readable through CORS. An unavailable admission store returns 503 with a five-second hint; a concurrent cache fill can return 503 with a one-second hint. Avoid polling unchanged dates and never rotate addresses to evade limits.

Successful data may be reused by the application for up to five minutes after validation and admission. This five-minute data freshness window is separate from HTTP caching: all public API responses send Cache-Control: no-store, including errors. Browsers and shared HTTP caches must not store responses; CDN response caching must remain disabled. Error responses are not cached by the application.

Compatibility and deprecation

Use only the documented /api/v1/ routes for third-party integrations. Internal /api/ and /hub/ routes are unsupported for new integrations.

Stable v1 fields and request semantics remain compatible throughout v1. Optional response fields may be added; clients should tolerate them. Breaking changes require a new path version. Version deprecation is announced here and in release notes with at least a 180-day notice period, plus Deprecation and Sunset response headers. A security, privacy, or legal emergency may require faster retirement.