Conventions & errors

{ "success": true,  "inserted": 3, "rejected": 0 }
{ "success": false, "error": "Maximal 50 Rezepte pro Anfrage" }

{
  "success": true,
  "accepted": 4,
  "rejected": 1,
  "errors": [
    { "index": 2, "error": "multiple_choice: \"correct_index\" liegt außerhalb von \"options\"" }
  ]
}

# intouch api
base    https://api.in-touch.cc
auth    X-API-Key: itk_<64 hex>   one key per user, no expiry, no scopes
docs    https://docs.in-touch.cc
format  every response is JSON and carries "success"

# conventions
One response shape, one set of status codes, one way of reporting partial batches.

# envelope
Every response is JSON and always carries "success".
On failure an "error" string is included; on success the payload sits alongside.

{ "success": true,  "inserted": 3, "rejected": 0 }
{ "success": false, "error": "Maximal 50 Rezepte pro Anfrage" }

A 200 does not mean everything landed: a batch can succeed overall while
individual items are rejected. Always read "success" and the counters.

# status
200  request handled          read "success" and any per-item "errors"
400  nothing usable in it     fix the body; the message names the field
401  no X-API-Key header      add the header
403  key unknown or rotated   get a fresh key from the app
404  unknown route            check path and method
500  server error             retry; if it persists the payload hit an edge case

# partial acceptance
Batch endpoints are not all-or-nothing. Valid items are stored, invalid ones are
reported by their index in the array you sent, so you can fix and resend those.

{
  "success": true,
  "accepted": 4,
  "rejected": 1,
  "errors": [ { "index": 2, "error": "multiple_choice: \"correct_index\" liegt außerhalb von \"options\"" } ]
}

A request is only a 400 when NOTHING in it was usable.

# limits
POST /api/addons/recipe/suggest   50 recipes per request
POST /api/addons/vocab/push       50 questions per set
GET  /api/addons/vocab/history    limit 1-500, default 100
No request rate limit today. Be reasonable - these endpoints write into
somebody's home screen.

# dates
calendar day (plan_date, set_date)      YYYY-MM-DD    2026-07-25
timestamp (answered_at, created_at)     ISO 8601      2026-07-25T18:22:10Z
Day boundaries and streaks are evaluated in UTC on the server.
Omitting a date field means "today".

# language of errors
"error" strings are German because the backend speaks German internally.
They are developer-facing. Branch on the status code and on errors[].index,
never on the message text.

# pages
/                  overview, capability list
/quickstart        get a key, first request
/authentication    key format, rotation, failure modes
/conventions       envelope, status codes, limits, dates
/recipes           recipes capability
/vocabulary        vocabulary capability
/roadmap           capability anatomy, what is planned
every page is also plain text: append .txt  (e.g. https://docs.in-touch.cc/vocabulary.txt)
all pages at once: /llms.txt (index) and /llms-full.txt (everything)

# for agents
- Use only the endpoints listed here; do not invent paths, fields or values.
- Check "success" in the body, not just the HTTP status.
- Error strings are German and developer-facing; branch on the status code.
- Batches are accepted partially: read "rejected" and "errors[].index".
- Dates are UTC. Calendar days are YYYY-MM-DD, timestamps are ISO 8601.
- The API key is a credential: never log it, never pass it to a third party.
- Ask the user before writing content into their app for the first time.