Integrations & personal API

ArktIQ Coach has a read-only personal API so your own tools - a Home Assistant dashboard, a spreadsheet, a script - can read your programs, today's tasks, badges and latest measurements. It never exposes anyone else's data, and it cannot change anything in your account.

1. Create an API key

In the app: Settings → Personal API → Create key. Name it (e.g. “Home Assistant”) and copy the token (akq_…) when it is shown - it is shown exactly once and stored hashed on our side. Revoking the key in Settings cuts the integration off immediately. Keys are read-only: they cannot log in, change data or manage keys.

A key covers either all programs (the default, including ones you create later) or a selection you pick when creating it - and, independently, all or selected measurements (e.g. only body weight). You can change both any time via Edit on the key, and deleting a program or measurement removes it from every key automatically. The app streak and streak badges are always included.

2. Endpoints

Send the key in the X-Api-Key header:

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

Endpoint	Payload (abridged)
`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 }`

Task, badge and metric names come back in your profile language. The surface is versioned: these shapes are stable, and breaking changes would ship as /integration/v2.

3. Example: Home Assistant

Home Assistant's built-in REST platform needs no custom component. Put the key in secrets.yaml:

# secrets.yaml
arktiq_api_key: akq_your-token-here

Then add sensors for today's tasks:

# 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 }}'

Restart Home Assistant and the sensors appear. A small automation can nudge you:

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. Notes & limits

Polling: the API is rate-limited per IP address. Intervals of 5–60 minutes are plenty; don't poll faster than once a minute.
Timezone: today is computed in your profile timezone.
Security: treat the key like a password and only use HTTPS. If it leaks, revoke it in Settings - a replacement is one click away.