# 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"

# roadmap
The API is built to grow. New capabilities arrive as their own namespace under
/api/addons/ and their own page here, reusing the key you already hold.

# anatomy of a capability
role            shape                  recipes            vocabulary
read context    GET  .../profile       -                  /vocab/profile
write content   POST ...               /recipe/suggest    /vocab/push
read feedback   GET  .../history       /recipe/history    /vocab/history

All of them authenticate with the same X-API-Key header and return the same
response envelope. Write an integration against one and the next is familiar.

# available today
recipes     stable   meal suggestions in, preferences out
vocabulary  stable   language exercises in, right-and-wrong answers out

# under consideration (nothing here is committed or dated)
reminders        idea   write items into a shared reminder area from outside
habits           idea   read a user's goals and streaks; suggest new ones
daily challenge  idea   supply the puzzle of the day
news             idea   push curated items into the news addon

Do not build against anything in this section - these endpoints do not exist.

# what will not change
- One personal key per user, sent as X-API-Key. New capabilities never need
  new credentials.
- The { "success": ... } envelope and the status codes on /conventions.
- Partial acceptance with per-index errors[] instead of all-or-nothing batches.

# 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.