Horaka API (1.0.0)

Every endpoint except the specification itself needs a token, sent as Authorization: Bearer <token>. Tokens are created under Settings, API in the app (/app/einstellungen/api). The plain token is shown exactly once; the server only keeps a hash. A revoked or expired token answers 401.

• Personal tokens belong to one account and act with its role. Team members only see and change their own time entries and never see rates or amounts; owners and admins see everything in the workspace.
• Device tokens belong to a device (iOS Shortcut, NFC tag, Flic button, Stream Deck, anything else) of one account. They only carry the ability track, can be limited to certain projects and are counted against the device limit of the plan (Free 1, Standard 3, Premium unlimited).

The delta sync (/time-entries/changes) is part of Premium. A missing ability answers 403 with code insufficient_scope, a feature outside the plan answers 403 with code plan_required and the plan that includes it in meta.required_plan. A deactivated account answers account_deactivated, a suspended workspace workspace_suspended, a workspace whose deletion the owner has requested workspace_deletion_pending (until the request is revoked).

Per token and minute: read 600, write 120, track 60, billing 30 (webhooks counts as write). Every answer carries X-RateLimit-Limit and X-RateLimit-Remaining; above the limit the answer is 429 with Retry-After in seconds.

• Answers are {"data": …, "meta": …, "links": …}; errors are {"errors": [{"status", "code", "title", "detail", "source", "meta"}]}. Codes are stable and English, title and detail follow Accept-Language (en or de, default English).
• Times are ISO 8601 in UTC (2026-10-14T08:00:00Z). Times you send need an offset or Z. Calendar days (local_date, from, to) are YYYY-MM-DD in the time zone of the account.
• Amounts are integers in minor units (cents) with the ISO currency next to them.
• Rounding, breaks and amounts are calculated by the server when a time entry is saved and are read from stored values. A running timer has ended_at: null and no values yet.

Lists use keyset pagination: page[size] (default 50, at most 200) and page[cursor] with meta.next_cursor of the previous page. meta.has_more says whether another page follows, links.next is the ready-made address. Lists accept updated_since (ISO 8601) for incremental reads.

GET /time-entries/changes?cursor=<n> returns every time entry changed after cursor in the order of the change (sync_version), deletions included as tombstones with deleted_at set. Store meta.next_cursor and ask again with it; while meta.has_more is true, ask again at once. Without new changes the cursor stays the same and If-None-Match with the last ETag answers 304. Tombstones are kept for 90 days; a cursor older than the oldest kept tombstone answers 410 with the code cursor_expired: start again without a cursor and replace your copy.

POST /track/start, /track/stop, /track/toggle and /track/switch take {"project": <id or alias>, "activity": <id or name>, "note": "…"} and always answer with the current timers. If the account allows parallel timers (personal setting), several timers may run at once: start adds a timer (the same project and activity never runs twice). Otherwise a start ends the running timers at the same moment (meta.action is switched). stop without a project stops all running timers, switch stops all other running timers at the same moment. Send an Idempotency-Key header (any unique text, valid for 24 hours) to make a press count exactly once; the same key returns the stored answer, the same key with a different body answers 422. Without the header, a second press of the same account within two seconds is ignored (meta.debounced: true). Aliases are maintained under Settings, API.

Owners and admins register https endpoints (no private networks) under Settings, Webhooks or with POST /webhooks. Each delivery is a POST with a JSON body (see the webhook section) and the headers X-Horaka-Event, X-Horaka-Delivery-Id and X-Horaka-Signature: t=<unix time>,v1=<hex> where v1 is HMAC-SHA256 of <t>.<raw body> with the endpoint secret. Answer with any 2xx within 10 seconds. Failed deliveries are retried after 1 min, 5 min, 30 min, 2 h and 12 h; after 20 failures in a row the endpoint is switched off and the owner gets an email. Deliveries can be replayed in the app.

Verify the signature against the raw body and reject timestamps older than five minutes:

$header = $_SERVER['HTTP_X_HORAKA_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $header), $parts);
$expected = hash_hmac('sha256', $parts['t'].'.'.$body, getenv('HORAKA_WEBHOOK_SECRET'));
$valid = isset($parts['t'], $parts['v1'])
    && abs(time() - (int) $parts['t']) <= 300
    && hash_equals($expected, $parts['v1']);

// Node.js (Express with express.raw({ type: 'application/json' }))
import crypto from 'node:crypto';

function verify(req, secret) {
  const parts = Object.fromEntries(
    String(req.get('X-Horaka-Signature') || '').split(',').map((p) => p.split('=')),
  );
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${req.body}`).digest('hex');
  return Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300
    && parts.v1?.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

import hashlib, hmac, time

def verify(header: str, body: bytes, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(parts["t"])) <= 300 and hmac.compare_digest(expected, parts["v1"])

Start the timer on project MUE-WEB with curl:

curl -X POST https://api.horaka.com/v1/track/start \
  -H "Authorization: Bearer $HORAKA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"project": "MUE-WEB", "note": "Workshop"}'

• iOS Shortcuts: action "Get Contents of URL", method POST, URL …/v1/track/toggle, headers Authorization: Bearer <device token> and Content-Type: application/json, request body JSON with the key project. Run it from Siri, the home screen or an NFC automation. For a spoken status ("hours today"), call GET …/api/v1/track/status?format=text and pass the result to "Speak Text". The app has a gallery with ready requests under Settings, Shortcuts.
• Zapier: "Webhooks by Zapier", action "Custom Request" with the same URL, headers and body; as a trigger use "Catch Hook" and register its address as a webhook endpoint.
• Make: module "HTTP, Make a request" with the token as header; module "Webhooks, Custom webhook" to receive events.
• n8n: node "HTTP Request" with "Header Auth" (Authorization: Bearer …); node "Webhook" to receive events, then verify the signature in a "Code" node.

The version is part of the path (/v1). Additive changes (new fields, new endpoints, new events) come without a new version, so ignore fields you do not know. Endpoints that will be replaced get the headers Deprecation and Sunset well in advance.

This document as JSON and YAML, without a token.

Clients of the workspace (the customers you bill).

Projects belong to exactly one client.

Optional activities, per project or for the whole workspace.

Free tags of the workspace, assigned to time entries by name.

Accounts of the workspace.

Tracked time, the running timer and the delta sync.