Dries Peeters
96955aee62
Add VersionService to fetch and cache the latest GitHub release, compare it to the installed semver (APP_VERSION when valid, else setup.py), and expose admin-only GET /api/version/check and POST /api/version/dismiss on the legacy /api blueprint (session or Bearer token). Persist per-user dismissal in users.dismissed_release_version (Alembic 148) and show a non-blocking update card in base.html for administrators. Add packaging for semver parsing and tests for comparison, service, and routes. Document configuration in docs/admin/deployment/VERSION_MANAGEMENT.md and endpoints in docs/api/REST_API.md and docs/API.md.
3.4 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) |
Access is controlled by scopes (e.g. read:projects, write:time_entries). 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.
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