Dries Peeters
6de7035b4a
Introduce a dedicated My productivity page at /dashboard/productivity with streaks, focus metrics, project breakdown, a 12-week heatmap, and Chart.js charts backed by ProductivityService (user-timezone-aware). Expose GET /api/productivity/stats with a 5-minute cache when no active timer is running. Document the feature and related session JSON routes.
3.8 KiB
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
- Log in as an administrator.
- Go to Admin → Security & Access → Api-tokens (or
/admin/api-tokens). - Click Create Token, set name, user, and scopes (read/write per resource).
- 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 |
| Admin version check | /api/version/check, /api/version/dismiss |
Compare install to latest GitHub release; dismiss per version (admin only; session or API token; not under /api/v1) |
| Dashboard (session) | /api/stats/value-dashboard, /api/productivity/stats, /api/projects/<id>/forecast, /api/ai/suggest, … |
JSON used by the logged-in web UI (session cookie); see REST API reference for fields and caching |
Access is controlled by scopes (e.g. read:projects, write:time_entries) on /api/v1 routes. Create a token with the scopes you need; see API Token Scopes. The admin version endpoints do not require a specific scope but require an administrator user. Legacy /api/... dashboard JSON routes require a normal logged-in session, not 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
- REST API reference — All endpoints, request/response formats, pagination, errors
- API Consistency Audit — Response contracts, error format, pagination
- API Token Scopes — Scopes and permissions
- API Versioning — Versioning policy and usage