API Reference

Timekeeper exposes a compact bearer-token API for automation around the same records the dashboard manages: punch-clock sessions, manual time entries, day comments, file receipts, audit history, audit reverts, and API token control. The reference is split by workflow so scripts can start from the overview, then jump directly to authentication, entry mutation, audit recovery, or recipes without scanning a long single page.

Use your deployed instance URL as the base URL, usually the value configured as NEXTAUTH_URL. Every request must include an Authorization: Bearer header with a Timekeeper token created in Settings, API Tokens. Tokens are intended for server-side scripts and personal automation; store them like passwords, revoke old values when they leave your control, and create separate named tokens for different jobs so audit trails stay readable. Responses are JSON unless a file download route says otherwise. Date parameters use YYYY-MM-DD, and datetimes use ISO strings.

curl -X POST "$NEXTAUTH_URL/api/checkin" \
  -H "Authorization: Bearer $TIMEKEEPER_TOKEN"

await fetch(`${process.env.NEXTAUTH_URL}/api/checkin`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TIMEKEEPER_TOKEN}`,
  },
});

import os
import requests

requests.post(
    f"{os.environ['NEXTAUTH_URL']}/api/checkin",
    headers={"Authorization": f"Bearer {os.environ['TIMEKEEPER_TOKEN']}"},
)