Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/alfonsoolavarria/florilegio/llms.txt

Use this file to discover all available pages before exploring further.

The Admin Bible Sync endpoints allow the Florilegio Django admin panel to incrementally import full Bible translations from the API.Bible service into the local VersiculoBiblia database table. All four endpoints are protected by the @staff_member_required decorator and will redirect unauthenticated or non-staff users to the admin login page. The BIBLE_API_KEY environment variable must be set to a valid API.Bible API key before any sync operation can succeed.

​
Supported Versions

Version KeyBible IDName
nblace11b813f9a27e20-01Nueva Biblia de las Américas
ntv826f63861180e056-01Nueva Traducción Viviente
rvr09592420522e16049f-01Reina Valera 1909

​
GET /api/admin/bible-status/

Returns the current synchronization status for all three supported Bible versions. The admin panel calls this endpoint first to determine which versions need to be re-synced. Auth: Staff required (@staff_member_required) A version is considered to need syncing (needs_sync: true) when either 30 or more days have elapsed since the last successful sync, or when no VersiculoBiblia records exist in the database for that version. Response 
{
  "statuses": [
    {
      "key": "nbla",
      "name": "Nueva Biblia de las Américas",
      "days_passed": 12,
      "needs_sync": false,
      "sync_date": "2024-01-10 14:30"
    },
    {
      "key": "ntv",
      "name": "Nueva Traducción Viviente",
      "days_passed": 30,
      "needs_sync": true,
      "sync_date": "Nunca"
    }
  ]
}
FieldTypeDescription
keystringInternal version key (nbla, ntv, or rvr09)
namestringHuman-readable name of the Bible translation
days_passedintegerDays elapsed since last_synced_at. Defaults to 30 when no prior sync exists
needs_syncbooleantrue when days_passed >= 30 or no verses exist for this version
sync_datestringFormatted timestamp (YYYY-MM-DD HH:MM) of the last sync, or "Nunca" if never synced

​
GET /api/admin/bible-sync/<version_key>/setup/

Returns the ordered list of book numbers that must be iterated to perform a full Bible sync. The list always contains integers 1 through 66, corresponding to Genesis through Revelation. Auth: Staff required
​
version_key
string
required
The Bible version to sync. Must be one of: nbla, ntv, rvr09.
Response 
{
  "books": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
            21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40,
            41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60,
            61, 62, 63, 64, 65, 66]
}

​
GET /api/admin/bible-sync/<version_key>/sync/<libro_num>/<capitulo_num>/

Fetches a single chapter from the API.Bible REST API, parses the HTML/USFM-based response using BeautifulSoup, extracts individual verse text, and saves or updates the corresponding VersiculoBiblia records in the database. Existing records for the given version, book, and chapter are deleted before the new batch is inserted via bulk_create. Auth: Staff required
​
version_key
string
required
Bible version key. Must be one of: nbla, ntv, rvr09. Returns HTTP 400 with {"error": "Versión no válida"} if the key is unrecognized.
​
libro_num
integer
required
Book number in the range 1–66. Internally mapped to its USFM code (e.g., 1 → GEN, 40 → MAT, 66 → REV) before constructing the API.Bible request URL.
​
capitulo_num
integer
required
Chapter number within the book. Combined with the USFM book code to form the passage ID (e.g., GEN.1 for Genesis chapter 1).
Success response 
{
  "success": true,
  "verses_imported": 31
}
Error responses
StatusBodyCause
400{"error": "Versión no válida"}version_key is not one of the three supported values
400{"error": "Libro no válido"}libro_num is not in the USFM mapping (outside 1–66)
200{"error": "Not found", "end_of_book": true}API.Bible returned 404 — chapter does not exist in this translation (signals end of book to the caller)
400{"error": "Error de la API: <code>"}Any other non-200 response from API.Bible is propagated
The sync endpoint constructs USFM passage IDs of the form BOOK.chapter (e.g., GEN.1 for Genesis chapter 1, MAT.5 for Matthew chapter 5) and requests HTML-formatted content from the API.Bible /chapters/{id} endpoint. Verse numbers are parsed from <span class="v"> elements in the returned HTML.
Full USFM book code mapping
#CodeBook#CodeBook
1GENGenesis34NAMNahum
2EXOExodus35HABHabakkuk
3LEVLeviticus36ZEPZephaniah
4NUMNumbers37HAGHaggai
5DEUDeuteronomy38ZECZechariah
6JOSJoshua39MALMalachi
7JDGJudges40MATMatthew
8RUTRuth41MRKMark
91SA1 Samuel42LUKLuke
102SA2 Samuel43JHNJohn
111KI1 Kings44ACTActs
122KI2 Kings45ROMRomans
131CH1 Chronicles461CO1 Corinthians
142CH2 Chronicles472CO2 Corinthians
15EZREzra48GALGalatians
16NEHNehemiah49EPHEphesians
17ESTEsther50PHPPhilippians
18JOBJob51COLColossians
19PSAPsalms521TH1 Thessalonians
20PROProverbs532TH2 Thessalonians
21ECCEcclesiastes541TI1 Timothy
22SNGSong of Solomon552TI2 Timothy
23ISAIsaiah56TITTitus
24JERJeremiah57PHMPhilemon
25LAMLamentations58HEBHebrews
26EZKEzekiel59JASJames
27DANDaniel601PE1 Peter
28HOSHosea612PE2 Peter
29JOLJoel621JN1 John
30AMOAmos632JN2 John
31OBAObadiah643JN3 John
32JONJonah65JUDJude
33MICMicah66REVRevelation

​
GET /api/admin/bible-sync/<version_key>/finish/

Marks a version sync as complete by updating the ApiBibleSyncStatus.last_synced_at timestamp to the current time. This resets the days_passed counter and clears the needs_sync flag for the version. Auth: Staff required
​
version_key
string
required
Bible version key for which to record the completion timestamp. Must be one of: nbla, ntv, rvr09.
Success response 
{"success": true}

​
Sync Workflow

1

Check sync status

Call GET /api/admin/bible-status/ to retrieve the current sync state for all three versions. Inspect needs_sync for each entry to decide which versions to process.
2

Get the list of books

For each version that needs syncing, call GET /api/admin/bible-sync/<version_key>/setup/ to retrieve the ordered list of book numbers (1–66) to iterate over.
3

Sync each chapter

For every book number returned by setup, iterate through chapter numbers starting at 1 and call GET /api/admin/bible-sync/<version_key>/sync/<libro>/<cap>/ for each. Continue incrementing the chapter number until the response contains "end_of_book": true (HTTP 200 with a 404 from API.Bible), which signals the book has no more chapters.
4

Record completion

After all 66 books and their chapters have been synced, call GET /api/admin/bible-sync/<version_key>/finish/ to save the current timestamp as last_synced_at. This prevents the version from appearing as needing a sync for the next 30 days.
A full sync of all three versions (66 books × avg ~22 chapters ≈ 1,452 API calls per version) can take several minutes to complete. The Florilegio admin panel handles this process progressively using JavaScript, advancing chapter by chapter in the background to avoid timeouts. Do not close the admin panel tab while a sync is in progress.
The BIBLE_API_KEY environment variable must be set to a valid API.Bible key. Requests are sent to https://rest.api.bible/v1/bibles/{bible_id}/chapters/{USFM_passage_id} with the key passed in the api-key request header. The passage ID format is BOOK.chapter (e.g., GEN.1 for Genesis chapter 1, REV.22 for Revelation chapter 22).

Build docs developers (and LLMs) love

Get started for freeTalk to us