Public API overview

TimeLogger ends at approved hours — it never computes pay. The public REST API is how your payroll, billing or BI tools pick those hours up. This page is a public overview; the full, always-current reference with every endpoint, parameter and example lives inside the app.

Get started#

1. Create a key

   In WorkspaceSettings, on the API keys card, choose New key, name it after the integration, and tick only the scopes it needs. The secret is shown once — store it in your secrets manager.

2. Send it as a Bearer token

   Every request carries Authorization: Bearer tl_live_…. The base URL is your TimeLogger address followed by /api/v1.

3. Read approved timesheets

   Filter timesheets to status=approved — these are the hours your approvers signed off.

curl -s "https://timelogger.example.com/api/v1/timesheets?status=approved&limit=50" \
  -H "Authorization: Bearer $TIMELOGGER_API_KEY"

{
  "results": [
    {
      "id": "51050378-…",
      "member_id": "9f686e4d-…",
      "member_name": "Ananya Iyer",
      "period_start": "2026-09-14",
      "period_end": "2026-09-20",
      "status": "approved",
      "approved_by_name": "Neha Kapoor",
      "approved_at": "2026-09-24T21:06:13Z",
      …
    }
  ],
  "next_cursor": "bz0xMDA"
}

Scopes#

Write scopes don’t include read — tick both if an integration needs both.

Export approved hours#

GET /exports/approved-hours returns only entries in approved or locked timesheets, with your workspace rounding applied. group_by picks the layout and format the file type (csv, xlsx, pdf, or json for rows inline).

curl -s -o approved-hours.csv \
  "https://timelogger.example.com/api/v1/exports/approved-hours?from=2026-09-01&to=2026-09-30&group_by=harvest&format=csv" \
  -H "Authorization: Bearer $TIMELOGGER_API_KEY"

Rate limits#

Each key can make 600 requests a minute. Over that, requests get 429 with a Retry-After header saying how many seconds to wait. Limits are per key, so separate integrations don’t slow each other down.

HTTP/1.1 429 Too Many Requests
Retry-After: 12
{ "error": "rate_limited", "message": "Request was throttled. Expected available in 12 seconds." }

Conventions#

Pagination#

Lists return { results, next_cursor }. Pass next_cursor back as cursor until it is null. limit defaults to 50, up to 200.

Formats#

Errors#

Every error has the same shape: a machine-readable error code, a readable message and optional details.

HTTP/1.1 403 Forbidden
{
  "error": "insufficient_scope",
  "message": "This API key needs the time:write scope.",
  "details": { "required_scope": "time:write", "key_scopes": ["timesheets:read", "exports:read"] }
}

The full reference#

Signed-in owners, admins and auditors can open the complete reference at WorkspacePublic API (/app/developers). It lists every endpoint a key can reach with its scope, parameters, request and response, a curl example, and a Try it button that runs read requests with your own session. It’s generated from the server, so it always matches what the API enforces. The raw OpenAPI schema is at /api/v1/schema, and an interactive explorer at /api/v1/docs.

Questions#