Skip to content

API.md

Latest commit

 

History

History
77 lines (54 loc) · 3.1 KB

API.md

File metadata and controls

77 lines (54 loc) · 3.1 KB

TimeTracker REST API

TimeTracker exposes a REST API for programmatic access to time tracking, projects, tasks, clients, reports, and more. The API is versioned under /api/v1, uses token-based authentication, and returns JSON.

Overview

Use the API to integrate with external tools, build custom dashboards, or drive the mobile and desktop apps. All endpoints require authentication via an API token (Bearer or X-API-Key header) unless noted. Pagination, filtering, and error responses are described in the full reference.

Getting an API Token

  1. Log in as an administrator.
  2. Go to Admin → Security & Access → Api-tokens (or /admin/api-tokens).
  3. Click Create Token, set name, user, and scopes (read/write per resource).
  4. Copy the token immediately; it is shown only once.

Token format: tt_ followed by 32 random characters.

Using the Token

Send the token on every request:

Bearer (recommended):

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     https://your-domain.com/api/v1/projects

API key header:

curl -H "X-API-Key: YOUR_API_TOKEN" \
     https://your-domain.com/api/v1/projects

Main Resources

Area Endpoints (examples) Description
Projects /api/v1/projects List, create, get, update, delete projects
Time entries /api/v1/time-entries List, create, get, update, delete time entries; timer start/stop
Tasks /api/v1/tasks List, create, get, update, delete tasks
Clients /api/v1/clients List, create, get, update, delete clients
Reports /api/v1/reports Run reports and export data
Deals & leads /api/v1/deals, /api/v1/leads CRM deals and leads
Contacts /api/v1/clients/<id>/contacts Client contacts
Search /api/v1/search Global search across projects, tasks, clients
Time approvals /api/v1/time-entry-approvals Approve, reject, request approval for time entries

Access is controlled by scopes (e.g. read:projects, write:time_entries). Create a token with the scopes you need; see API Token Scopes.

Quick Examples

List projects:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     https://your-domain.com/api/v1/projects

Create a time entry:

curl -X POST -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"project_id": 1, "start_time": "2025-01-27T09:00:00", "end_time": "2025-01-27T17:00:00", "notes": "Work on feature"}' \
     https://your-domain.com/api/v1/time-entries

Replace your-domain.com with your TimeTracker host and YOUR_API_TOKEN with your token.

Full Documentation