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

# quickstart
Three steps: get the key, make one read call, make one write call.

# 1 - get the key
Source    inTouch app > Settings > App & Media > inTouch API > Generate key
Format    itk_ + 64 hex characters
Scope     one key per user, valid for every capability, no expiry
Note      there is no API endpoint that mints keys - this is deliberate

# 2 - first request (read, safe, works before anything was pushed)
GET /api/addons/vocab/profile

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

200 {
  "success": true,
  "supported_types": ["translate","multiple_choice","fill_gap",
                      "match_pairs","sentence_order"],
  "active_set": null,
  "streak": 0
}

401  no X-API-Key header
403  key unknown or rotated away
"active_set": null  means nothing has been pushed for this user yet.
             Ask the user what they want to learn, then POST /vocab/profile.

# 3 - first write (one dish into the feed)
POST /api/addons/recipe/suggest

curl -X POST https://api.in-touch.cc/api/addons/recipe/suggest \
  -H "X-API-Key: itk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipes":[{"meal_category":"dinner","title":"Oven Salmon with Herbs",
       "duration":"25 min","difficulty":"Easy","servings":2,
       "ingredients":["2 salmon fillets","olive oil","dill","lemon"],
       "steps":["Heat oven to 200°C","Season and bake 18 min","Finish with lemon"]}]}'

200 { "success": true, "inserted": 1, "rejected": 0, "plan_date": "2026-07-25" }

The card is now in the user's feed.

# key handling
Anything holding the key can write into the user's app and read their history.
Do not embed it in a prompt file; read it from an environment variable.
If it leaks, the user rotates it in the app and the old key dies immediately.

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