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

# overview
inTouch is an iOS app with a feed. This API lets an external tool or AI assistant
write content into that feed and read back what the user did with it.
One personal key, one namespace per capability, the same shape everywhere.

# capabilities
recipes     stable   meal suggestions into the feed, preferences back out
vocabulary  stable   language exercises in, right and wrong answers back out
more capabilities are planned; the key you hold already covers them

# the shape of every capability
GET  /api/addons/<capability>/profile   read context: what does this user want?
POST /api/addons/<capability>/...       write content into the app
GET  /api/addons/<capability>/history   read feedback: what happened with it?

# endpoints available today
POST /api/addons/recipe/suggest    push meal suggestions        -> /recipes.txt
GET  /api/addons/recipe/history    liked / disliked / open      -> /recipes.txt
GET  /api/addons/vocab/profile     status: active set, streak   -> /vocabulary.txt
POST /api/addons/vocab/push        replace the active set       -> /vocabulary.txt
GET  /api/addons/vocab/history     every answer, right or wrong -> /vocabulary.txt

# getting a key
The key is minted inside the app only: Settings > App & Media > inTouch API.
There is no endpoint that creates keys. Ask the user to paste theirs.

# asked to "set it up" for a user?
Both capabilities carry a full self-setup brief for agents - prompt file, first
push, guard script, scheduler per operating system - in the "self-setup" section
of /vocabulary.txt and /recipes.txt. Read the page before you touch anything.
Nothing about the user's preferences is stored server-side: those briefs write a
local prompt file instead.

# minimal example
curl "https://api.in-touch.cc/api/addons/vocab/profile" -H "X-API-Key: itk_YOUR_KEY"

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