# Bible Study API — handleiding voor agents (Hermes, ChatGPT, scripts)

> **Voor de agent:** lees dit hele bestand één keer. Alles wat je nodig hebt staat hier.
> Live versie: `https://bible.sluijsjes.nl/api/v1/docs` · OpenAPI: `https://bible.sluijsjes.nl/api/v1/openapi.json`

Met deze API voeg je namens een gebruiker **notities**, **markeringen (highlights)**, **tags** en **studies** toe aan zijn Bible Study-account. De Bijbeltekst zelf komt níet via deze API (licentie) — je werkt altijd met *verwijzingen*.

Sinds september 2026 is alles wat je aanmaakt **privé** tenzij je het expliciet publiceert (zie §5). Er is daarnaast een **publieke leeslaag** zonder token: openbare studies, openbare notities, profielen en de naslagdata (tijdlijn, personen, plaatsen, routes) — zie §9.

---

## 1. Authenticatie

Elke aanvraag die eigen gegevens leest of schrijft heeft een persoonlijk token nodig. Zonder token werken alleen `/api/v1/docs`, `/api/v1/openapi.json`, `/api/v1/reference` en de publieke eindpunten uit §9.

```
Authorization: Bearer bsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

De gebruiker maakt het token aan via **Instellingen → API-toegang** (`/settings`). Het token wordt één keer getoond. Intrekken kan op dezelfde plek.

Controle: `GET /api/v1/me` → `{ "email": "…", "isAuthor": true }`.

## 2. Bijbelverwijzingen

Overal waar `reference` staat mag je gewoon schrijven wat een mens zou schrijven — Nederlands of Engels:

| Invoer | Betekent |
|---|---|
| `Genesis 1:1` · `Gen 1:1` · `GEN.1.1` | één vers |
| `Psalm 89:6–8` · `Ps. 89:6-8` · `PSA.89.6-8` | versbereik |
| `1 Koningen 22:19–23` · `1 Kon. 22:19-23` · `1 Kings 22:19-23` | genummerd boek |
| `Daniël 7:9–10` · `Daniel 7:9-10` | met/zonder trema |
| `Johannes 3:16-4:2` | over hoofdstukgrens |
| `Psalm 82` | heel hoofdstuk |
| `Judas 6` | boek met één hoofdstuk = vers 6 |
| `Job 1:6 / 2:1` · `Gen 1:1; 1:26` | **meerdere** verwijzingen → er wordt per verwijzing één item gemaakt |

Twijfel je? Test eerst (geen token nodig):

```bash
curl "https://bible.sluijsjes.nl/api/v1/reference?q=Job%201:6%20/%202:1"
# → {"ranges":[{"start":"JOB.1.6","end":"JOB.1.6","nl":"Job 1:6"},{"start":"JOB.2.1","end":"JOB.2.1","nl":"Job 2:1"}]}
```

Canonieke vorm = `BOEK.HOOFDSTUK.VERS` met USFM-boekcodes (`GEN`, `PSA`, `1KI`, `JHN`, `COL`, …). Antwoorden bevatten altijd zowel `reference` (leesbaar) als `start`/`end` (canoniek).

## 3. Twee talen (NL + EN)

De site staat standaard in het Engels; bezoekers kunnen naar Nederlands wisselen. Notities en studies hebben daarom twee versies:

| Veld | Betekenis |
|---|---|
| `content` / `title` | origineel (meestal Nederlands) — verplicht |
| `contentEn` / `titleEn` | Engelse vertaling — optioneel |

Lever **altijd beide** als je kunt. Ontbreekt de Engelse versie, dan toont de site in het Engels het origineel met de melding "not translated yet".

- Een bestaande notitie opnieuw aanbieden (zelfde `reference` + `content`) mét `contentEn` **vult de vertaling aan** — handig om achteraf te vertalen.
- Studies: `PATCH /api/v1/studies/{id}` met `titleEn`, `contentEn`, `descriptionEn`, of `appendContentEn` (voegt toe aan de Engelse tekst).

## 4. Kleuren

`yellow` · `green` · `blue` · `purple` · `orange` · `red` (standaard: `yellow`).
Liggen er meerdere markeringen over één vers, dan toont de app dat vers automatisch in een aparte paarse "meerdere markeringen"-kleur; die kleur kun je niet zelf kiezen.

## 5. Openbaar of privé (visibility)

Studies en notities hebben een zichtbaarheid:

| Waarde | Betekenis |
|---|---|
| `"private"` | **standaard** — alleen de eigenaar ziet het, ook niet via URL of API |
| `"unlisted"` | iedereen mét de link kan het lezen; het staat in geen enkel overzicht, profiel, zoekresultaat of list-endpoint |
| `"public"` | iedereen kan het lezen én het staat in de overzichten; de naam van de maker staat erbij |

- **Aanmaken zonder `visibility` → `private`.** Oudere clients blijven dus gewoon werken en publiceren nooit per ongeluk iets.
- Publiceren of terugdraaien: `PATCH /api/v1/studies/{id}` of `PATCH /api/v1/notes/{id}` met `{ "visibility": "public" }` / `{ "visibility": "private" }`.
- Bij het opnieuw aanbieden van een bestaande notitie (dedupe) wordt een meegegeven `visibility` ook toegepast.
- Filteren: `GET /api/v1/studies?visibility=public`, `GET /api/v1/notes?visibility=private`.
- Elk antwoord bevat `visibility` (en bij studies ook `status`, `publishedAt`, `lastReviewedAt` en `contentVersion`).

Vraag de gebruiker wat hij wil voordat je iets publiceert; publiceren betekent zichtbaar op internet.

**Publiceren vereist een bevestigd e-mailadres.** Is het account nog niet bevestigd, dan antwoordt de API `403 {"error":"email_not_verified"}`; privé werken kan gewoon door. Zeg dat dan tegen de gebruiker in plaats van het opnieuw te proberen.

### Status van een studie (los van zichtbaarheid)

| `status` | Betekenis |
|---|---|
| `"draft"` | **standaard** — nog aan het schrijven |
| `"review"` | klaar om nagekeken te worden |
| `"published"` | af |
| `"archived"` | uit de overzichten, nog wel bereikbaar via de link |

`PATCH /api/v1/studies/{id}` met `{ "status": "review" }` zet de status. Zichtbaarheid en status zijn onafhankelijk: `published` + `private` is "af, maar voor mezelf". Een studie die van `review` naar `published` gaat, krijgt automatisch een datum bij "laatst gecontroleerd". `contentVersion` loopt op zodra de tekst of de titel verandert — laat die dus met rust in een PATCH.

## 6. Eindpunten

Basis-URL: `https://bible.sluijsjes.nl`. Alle bodies zijn JSON (`Content-Type: application/json`).

### Notities

```http
POST /api/v1/notes
{ "reference": "Psalm 82:1", "title": "Gods hemelse raad", "content": "God staat in een vergadering van *elohim* …",
  "titleEn": "God's divine council", "contentEn": "God stands in an assembly of *elohim* …", "tags": ["Unseen realm"] }
```

- `content` is **Markdown**. `title` en `tags` zijn optioneel; ontbrekende tags worden aangemaakt.
- **Batch:** `{ "items": [ {…}, {…} ] }` (max. 200) → antwoord `{ results: [...], created, failed }`.
- **Idempotent:** een notitie met exact dezelfde verwijzing + tekst wordt niet dubbel aangemaakt (`skipped`). Zet `"dedupe": false` om dat uit te zetten.
- Lijst: `GET /api/v1/notes?reference=Psalm 82&tag=Unseen realm&q=raad`
- Wijzigen: `PATCH /api/v1/notes/{id}` met `content`, `title`, `tags` (vervangt), `reference`
- Verwijderen: `DELETE /api/v1/notes/{id}`

### Markeringen (highlights)

```http
POST /api/v1/highlights
{ "reference": "Daniël 7:9-10", "color": "blue", "tags": ["Unseen realm"] }
```

- Batch met `{ "items": [...] }`. Een identieke markering (zelfde bereik + kleur) wordt hergebruikt en krijgt alleen de tags erbij.
- Een tag hoort altijd bij een markering: wil je een tag op een tekst zetten, maak dan een highlight met `tags`.
- Lijst: `GET /api/v1/highlights?reference=…&tag=…&color=…`
- Wijzigen: `PATCH /api/v1/highlights/{id}` met `color` en/of `tags` (vervangt) · Verwijderen: `DELETE /api/v1/highlights/{id}`

### Tags

- `GET /api/v1/tags`
- `POST /api/v1/tags` `{ "name": "Unseen realm", "color": "green" }` — bestaat de naam al, dan krijg je die terug.

### Studies

Een studie is een **verhaal in Markdown**. Elke Bijbelverwijzing in de tekst ("zie Psalm 82:1", "1 Koningen 22") wordt in de app automatisch klikbaar en opent die tekst in de Bijbel ernaast.

```http
POST /api/v1/studies
{
  "title": "De hemelse raad",
  "emoji": "👑",
  "content": "# De hemelse raad\n\nPsalm 82:1 beschrijft God te midden van de *elohim* …\n\n> God staat in de vergadering van God\n\nVergelijk 1 Koningen 22:19–23 en Daniël 7:9–10.",
  "titleEn": "The divine council",
  "contentEn": "# The divine council\n\nPsalm 82:1 describes God among the *elohim* …\n\nCompare 1 Kings 22:19–23 and Daniel 7:9–10.",
  "passages": ["Psalm 82", "Job 1:6"],
  "visibility": "private",
  "status": "draft"
}
```

- `GET /api/v1/studies` · `GET /api/v1/studies/{id}` (incl. `detectedReferences`)
- `PATCH /api/v1/studies/{id}` met `title`, `emoji`, `content` (vervangt), **`appendContent`** (voegt een stuk toe aan het einde) of `visibility`
- `POST /api/v1/studies/{id}/passages` `{ "reference": "Psalm 89:6-8" }`
- `POST /api/v1/studies/{id}/highlight-all` `{ "color": "green", "tags": ["Unseen realm"], "includeChapters": false }` — markeert **alle** Bijbelverwijzingen in de studie in één keer.
- Audio toevoegen: `POST /api/v1/studies/{id}/audio` met het bestand als **ruwe body**, header `Content-Type: audio/mp4` en `X-File-Name: bestand.m4a` (optioneel `X-Title: …`, URI-encoded). Toegestaan: m4a, mp3, ogg/opus, wav, aac, flac, webm.

```bash
curl -X POST "https://bible.sluijsjes.nl/api/v1/studies/STUDY_ID/audio" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: audio/mp4" \
  -H "X-File-Name: preek.m4a" --data-binary @preek.m4a
```

### Alles in één keer: import

```http
POST /api/v1/import
{
  "tags":       [ { "name": "Unseen realm", "color": "green" } ],
  "notes":      [ { "reference": "Genesis 1:1", "content": "…", "tags": ["Unseen realm"] } ],
  "highlights": [ { "reference": "Psalm 82:1", "color": "green", "tags": ["Unseen realm"] } ],
  "studies":    [ { "title": "…", "emoji": "📜", "content": "# …" } ]
}
```

Antwoord: per onderdeel een lijst met `{ index, ok, … }` of `{ index, ok: false, error }`, plus `failed` (totaal aantal fouten). Opnieuw uitvoeren is veilig voor notities en markeringen.

## 7. Voorbeeld — notities toevoegen

```bash
curl -X POST "https://bible.sluijsjes.nl/api/v1/notes" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "reference": "Genesis 1:1", "tags": ["Unseen realm"],
        "content": "God staat vóór en boven de hele schepping. Zowel de zichtbare als de onzichtbare wereld vindt haar oorsprong in Hem; geen enkel geestelijk wezen is Zijn gelijke." },
      { "reference": "Psalm 89:6–8", "tags": ["Unseen realm"],
        "content": "JHWH wordt beschreven te midden van een “raad van heiligen”. Geen van deze hemelse wezens is met Hem te vergelijken." },
      { "reference": "Job 1:6 / 2:1", "title": "Job 1:6 / 2:1", "tags": ["Unseen realm"],
        "content": "De “zonen van God” verschijnen voor JHWH en ook de satan komt daar." }
    ]
  }'
```

## 8. Foutmeldingen

| Status | Betekenis | Wat te doen |
|---|---|---|
| 400 | `{"error": "Could not parse reference …"}` | Verwijzing aanpassen; test met `/api/v1/reference` |
| 401 | geen/ongeldig token | Vraag de gebruiker om een (nieuw) token |
| 404 | item bestaat niet, is privé van een ander, of is niet van deze gebruiker | id controleren |
| 413 | audiobestand te groot | kleiner bestand |
| 403 | `{"error":"email_not_verified"}` | het account moet eerst zijn e-mailadres bevestigen; privé opslaan kan wel |
| 429 | te veel verzoeken (600/min) | even wachten |

## 9. Publiek lezen (zonder token)

Deze eindpunten hebben **geen token** nodig en geven alleen openbare inhoud terug:

| Eindpunt | Geeft |
|---|---|
| `GET /api/v1/public/studies?user=<handle>&author=true&q=…` | openbare studies met `owner` (naam + profiel) |
| `GET /api/v1/public/studies/{id}` | één openbare **of unlisted** studie inclusief het verhaal (privé → 404) |
| `GET /api/v1/public/notes?reference=Psalm 82&user=<handle>` | openbare notities bij een passage |
| `GET /api/v1/public/users/{handle}` | openbaar profiel: naam, Author-label, studies, aantal notities |
| `GET /api/v1/people` · `/api/v1/people/{slug}` | personen + Bijbelverwijzingen, relaties, tijdlijn, studies, notities |
| `GET /api/v1/places` · `/api/v1/places/{slug}` | plaatsen incl. coördinaten en `locationConfidence` |
| `GET /api/v1/timeline?type=KING,PROPHET` · `/api/v1/timeline/{slug}` | tijdlijnitems met `datePrecision` en bron |
| `GET /api/v1/routes` · `/api/v1/routes/{slug}` | routes (reizen) met stops |

Privé-inhoud komt hier nooit in voor — ook niet via relaties of verwijzingen.

## 10. Naslagdata beheren (alleen beheerders)

Met een token van een **beheerder** kun je personen, plaatsen, tijdlijnitems, routes en relaties importeren:

```http
POST /api/v1/admin/reference-data
{ "people": [...], "places": [...], "timeline": [...], "routes": [...], "relations": [...] }
```

Zelfde vorm als `docs/examples/reference-data-elijah.json`. Upsert op `slug`, dus opnieuw draaien is veilig. Leg altijd **bron en onzekerheid** vast: `source`, `sourceUrl`, `confidence` (`HIGH|MEDIUM|LOW`), `datePrecision` (`EXACT|CIRCA|RANGE|UNKNOWN`) en `locationConfidence` (`CERTAIN|PROBABLE|DISPUTED|UNKNOWN`). Presenteer een reconstructie nooit als harde Bijbelse feiten.

## 11. Regels voor agents

1. Gebruik **batch** (`items`) of **`/api/v1/import`** als je meer dan een paar dingen toevoegt.
2. Plak **geen Bijbeltekst** van beschermde vertalingen in notities of studies — verwijs naar de tekst (de app toont hem). Korte citaten in een studie zijn prima.
3. Schrijf notities en studies in Markdown, **in het Nederlands (`content`) én het Engels (`contentEn`)**. Verwijzingen in de Engelse tekst schrijf je met Engelse boeknamen ("1 Kings 22").
4. **Schrijf Bijbelverwijzingen gewoon als tekst** ("Ezechiël 37:11"), niet als Markdown-link naar de site. De app maakt er zelf een klikbare link van, met de juiste boekcode — een zelfbedachte URL zoals `/bible/nld1939/EZE/37` wijst naar het verkeerde boek (Ezechiël is `EZK`).
4. Gebruik bestaande tags (`GET /api/v1/tags`) waar het kan, in plaats van bijna-dubbele namen.
5. Alles is **privé** en `draft` tenzij de gebruiker om publicatie vraagt; stuur dan pas `"visibility": "public"` (of `"unlisted"` om alleen een link te delen) en `"status": "published"`.
6. Meld na afloop aan de gebruiker wat je hebt toegevoegd (aantallen + eventuele fouten uit `results`), en wat openbaar staat.

---

### Instructie om in Hermes / een Custom GPT te plakken

```
Je hebt toegang tot mijn Bible Study-app via een REST-API.
Basis-URL: https://bible.sluijsjes.nl — lees eerst https://bible.sluijsjes.nl/api/v1/docs.
Authenticatie: header "Authorization: Bearer <MIJN_TOKEN>".
Verwijzingen mag je in gewone taal geven ("Psalm 89:6-8", "1 Kon. 22:19-23").
Gebruik POST /api/v1/notes (met {"items": [...]}) voor notities, POST /api/v1/highlights voor markeringen
met tags, POST /api/v1/studies voor studies (Markdown-verhaal) en POST /api/v1/import om alles tegelijk
toe te voegen. Alles is standaard privé en draft; stuur alleen "visibility": "public"/"unlisted" en
"status": "published" als ik daar expliciet om vraag. Schrijf Bijbelverwijzingen als gewone tekst,
niet als link.
Openbare inhoud lezen kan zonder token via /api/v1/public/... .
Rapporteer daarna kort wat je hebt toegevoegd en wat er openbaar staat.
```

**ChatGPT (Custom GPT → Actions):** kies *Import from URL* → `https://bible.sluijsjes.nl/api/v1/openapi.json`, Authentication → *API Key* → *Bearer*, en plak het token.
