mirror of
https://github.com/DRYTRIX/TimeTracker.git
synced 2026-05-17 10:29:49 -05:00
Dries Peeters
7aeef629db
Document session-auth GET /api/stats/value-dashboard in REST_API.md (response shape, last_7_days, estimated value fields, 10-minute Redis cache). Link dashboard session JSON routes from docs/API.md and note that /api/v1 scopes do not apply to those legacy paths. Update the comprehensive API test so GET /api/projects/<id>/tasks is expected to return every task status, including done and cancelled, which matches the time-entry UI. Changelog: record the documentation update and the test correction.
80 lines
3.7 KiB
Markdown
80 lines
3.7 KiB
Markdown
# 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):**
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
|
|
https://your-domain.com/api/v1/projects
|
|
```
|
|
|
|
**API key header:**
|
|
|
|
```bash
|
|
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/dashboard/stats`, … | JSON used by the logged-in web UI (session cookie); see [REST API reference](api/REST_API.md) for `value-dashboard` 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](api/API_TOKEN_SCOPES.md). 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:**
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
|
|
https://your-domain.com/api/v1/projects
|
|
```
|
|
|
|
**Create a time entry:**
|
|
|
|
```bash
|
|
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](api/REST_API.md)** — All endpoints, request/response formats, pagination, errors
|
|
- **[API Consistency Audit](api/API_CONSISTENCY_AUDIT.md)** — Response contracts, error format, pagination
|
|
- **[API Token Scopes](api/API_TOKEN_SCOPES.md)** — Scopes and permissions
|
|
- **[API Versioning](api/API_VERSIONING.md)** — Versioning policy and usage
|