Integrasjoner og personlig API

ArktIQ Coach har et skrivebeskyttet personlig API slik at dine egne verktøy - et Home Assistant-panel, et regneark, et skript - kan lese programmene dine, dagens oppgaver, merker og siste målinger. Det eksponerer aldri andres data, og det kan ikke endre noe i kontoen din.

1. Opprett en API-nøkkel

I appen: Innstillinger → Personlig API → Opprett nøkkel. Gi den et navn (f.eks. «Home Assistant») og kopier tokenet (akq_…) når det vises - det vises nøyaktig én gang og lagres hashet hos oss. Trekker du tilbake nøkkelen i Innstillinger, kuttes integrasjonen umiddelbart. Nøkler er skrivebeskyttet: de kan ikke logge inn, endre data eller administrere nøkler.

En nøkkel dekker enten alle programmer (standard, også de du oppretter senere) eller et utvalg du velger når du oppretter den - og, uavhengig av det, alle eller utvalgte målinger (f.eks. bare kroppsvekt). Du kan endre begge deler når som helst via Endre på nøkkelen, og sletter du et program eller en måling, fjernes det automatisk fra alle nøkler. Appstreaken og streak-merker er alltid med.

2. Endepunkter

Send nøkkelen i X-Api-Key-headeren:

curl -H "X-Api-Key: akq_your-token-here" \
  https://coach.arktiq.no/api/integration/v1/today

Endepunkt	Svar (forkortet)
`GET /api/integration/v1/summary`	`{ goals: [{ title, goalTypeKey, level, planEndsAt }], streakDays, badgeCount }`
`GET /api/integration/v1/today`	`{ date, timezone, tasks: [{ title, status, dueAt, itemCount, checkedCount }], doneCount, totalCount }`
`GET /api/integration/v1/badges`	`[{ badgeKey, title, icon, awardedAt, … }]`
`GET /api/integration/v1/metrics/weight_kg/latest`	`{ key, name, unit, value, recordedAt }`

Navn på oppgaver, merker og målinger kommer tilbake på profilspråket ditt. Flaten er versjonert: formene er stabile, og endringer som bryter noe ville kommet som /integration/v2.

3. Eksempel: Home Assistant

Home Assistants innebygde REST-plattform trenger ingen egen komponent. Legg nøkkelen i secrets.yaml:

# secrets.yaml
arktiq_api_key: akq_your-token-here

Legg så til sensorer for dagens oppgaver:

# configuration.yaml
rest:
  - resource: https://coach.arktiq.no/api/integration/v1/today
    headers:
      X-Api-Key: !secret arktiq_api_key
    scan_interval: 300
    sensor:
      - name: 'Coach tasks done today'
        unique_id: arktiq_coach_tasks_done
        value_template: '{{ value_json.doneCount }}'
      - name: 'Coach tasks total today'
        unique_id: arktiq_coach_tasks_total
        value_template: '{{ value_json.totalCount }}'

Start Home Assistant på nytt, så dukker sensorene opp. En liten automasjon kan minne deg på gjenstående oppgaver:

automation:
  - alias: 'Coach: tasks still open at 19:00'
    trigger:
      - platform: time
        at: '19:00:00'
    condition:
      - condition: template
        value_template: >
          {{ states('sensor.coach_tasks_done_today') | int(0)
             < states('sensor.coach_tasks_total_today') | int(0) }}
    action:
      - service: notify.mobile_app_your_phone
        data:
          message: >
            {{ states('sensor.coach_tasks_total_today') | int(0)
               - states('sensor.coach_tasks_done_today') | int(0) }} coach task(s) left today.

4. Merknader og begrensninger

Spørrefrekvens: API-et er hastighetsbegrenset per IP-adresse. Intervaller på 5–60 minutter er rikelig; ikke spør oftere enn én gang i minuttet.
Tidssone: today beregnes i profiltidssonen din.
Sikkerhet: behandle nøkkelen som et passord og bruk kun HTTPS. Lekker den, trekk den tilbake i Innstillinger - en ny er ett klikk unna.