API reference

Every route below is mounted from one array, API_ROUTES in packages/server/src/api/v1/routes-table.ts, and this page and the OpenAPI document are both generated from it. A route cannot exist here and not in the server, or in the server and not here.

All paths are relative to https://api.trackyourtime.dev/api/v1. Every route but /openapi.json needs Authorization: Bearer tt_…. Parameters says where a route's input goes: query for a GET filter, body for JSON, path for the id in the URL. Full field-level shapes live in the OpenAPI document.

Entries

Method	Path	Scope	Parameters	What it does
GET	/entries	entries:read	query	List time entries overlapping a date range.
GET	/entries/current	entries:read	—	The caller's running timer in this workspace, or null when none is running here.
GET	/entries/:id	entries:read	path	One time entry.
POST	/entries	entries:write	body	Create a completed entry with an explicit start and end.
PATCH	/entries/:id	entries:write	body	Edit an entry. Author-only, and refused once it is invoiced.
DELETE	/entries/:id	entries:write	path	Delete an entry. Author-only, and refused once it is invoiced.
POST	/entries/start	entries:write	body	Start a timer, stopping this workspace's running one first. Answers 409 when the timer is running in another workspace, which this token may not stop.
POST	/entries/stop	entries:write	body	Stop the timer running in this workspace.

Clients

Method	Path	Scope	Parameters	What it does
GET	/clients	catalog:read	query	List clients.
GET	/clients/:id	catalog:read	path	One client.
POST	/clients	catalog:write	body	Create a client.
PATCH	/clients/:id	catalog:write	body	Edit a client.
POST	/clients/:id/archive	catalog:write	body	Archive or unarchive a client.
DELETE	/clients/:id	catalog:write	path	Delete a client. Its projects keep their time and lose the link.

Projects

Method	Path	Scope	Parameters	What it does
GET	/projects	catalog:read	query	List projects with rolled-up totals and budget progress.
GET	/projects/:id	catalog:read	path	One project with its totals and budget progress.
POST	/projects	catalog:write	body	Create a project.
PATCH	/projects/:id	catalog:write	body	Edit a project.
POST	/projects/:id/archive	catalog:write	body	Archive or unarchive a project.
DELETE	/projects/:id	catalog:write	path	Delete a project and its tasks. Entries keep their time.

Tasks

Method	Path	Scope	Parameters	What it does
GET	/tasks	catalog:read	query	List tasks, optionally narrowed to one project.
GET	/tasks/:id	catalog:read	path	One task.
POST	/tasks	catalog:write	body	Create a task inside a project.
PATCH	/tasks/:id	catalog:write	body	Edit a task.
POST	/tasks/:id/archive	catalog:write	body	Archive or unarchive a task.
DELETE	/tasks/:id	catalog:write	path	Delete a task. Entries keep their time and lose the link.

Tags

Method	Path	Scope	Parameters	What it does
GET	/tags	catalog:read	query	List tags with usage counts.
GET	/tags/:id	catalog:read	path	One tag.
POST	/tags	catalog:write	body	Create a tag.
PATCH	/tags/:id	catalog:write	body	Edit a tag.
DELETE	/tags/:id	catalog:write	path	Delete a tag, or archive it when tracked time still carries it.

Reports

Method	Path	Scope	Parameters	What it does
GET	/reports/summary	reports:read	query	Totals, a grouped breakdown, and a zero-filled daily series.
GET	/reports/detailed	reports:read	query	A paginated entry log; totals span the whole filtered range.
GET	/reports/weekly	reports:read	query	A seven-day timesheet grid, one row per project and task.

Meta

Method	Path	Scope	Parameters	What it does
GET	/me	any valid token	—	The calling token, its workspace, its scopes and what it may see.
GET	/openapi.json	none — public	—	This API's OpenAPI 3.1 document.

The document itself

• openapi.json — the committed copy this site serves.
• GET /api/v1/openapi.json — the live one, unauthenticated, generated per request from the running server's own route table. Point a client generator at it.