# Build with the TrackTimer API.

Source: https://www.tracktimer.app/docs

Use the TrackTimer REST API to find accessible clients and projects, control your project timer, and read your time entries. Build a personal integration or connect tracked hours to your own tools.

Working with an AI agent? [Connect through the hosted MCP server](https://www.tracktimer.app/docs/mcp) to control timers, correct your time, and review monthly earnings.

## Base URL

`https://www.tracktimer.app/api/v1`

All endpoints require a bearer API key. Keys belong to one user and one workspace. Examples use placeholders, not real credentials.

## Make your first request

1. Sign in to your workspace and create a personal API key in Settings. Read [authentication and key management](https://www.tracktimer.app/docs/authentication) first.
2. Call [List clients](https://www.tracktimer.app/docs/list-clients), then [List projects](https://www.tracktimer.app/docs/list-projects) with a returned client ID.
3. [Start a timer](https://www.tracktimer.app/docs/start-timer) using a returned project ID and an idempotency key. Starting a timer can stop your existing active timer.
4. [Stop the timer](https://www.tracktimer.app/docs/stop-timer) and read the saved record through [List time entries](https://www.tracktimer.app/docs/list-time-entries).

```sh
curl "https://www.tracktimer.app/api/v1/clients" \
  --header "Authorization: Bearer $TRACKTIMER_API_KEY"
```

In these shell examples, TRACKTIMER_API_KEY is a local placeholder variable you supply securely. Keep credentials in your server-side secret store; do not embed them in a public website or commit them.

## Endpoint reference

### [Create a project](https://www.tracktimer.app/docs/create-project)

`POST /api/v1/projects`

Create a project as a workspace admin and automatically join it.

### [List clients](https://www.tracktimer.app/docs/list-clients)

`GET /api/v1/clients`

Discover active workspace clients according to the API key owner’s role.

### [List projects for a client](https://www.tracktimer.app/docs/list-projects)

`GET /api/v1/projects`

Find assigned, unarchived projects for a client in the key’s workspace.

### [Get the active timer](https://www.tracktimer.app/docs/get-active-timer)

`GET /api/v1/timer`

Read the key owner’s current timer in the bound workspace.

### [Start or switch a timer](https://www.tracktimer.app/docs/start-timer)

`POST /api/v1/timers/start`

Start a project timer and atomically complete any timer already running for the user.

### [Stop a timer](https://www.tracktimer.app/docs/stop-timer)

`POST /api/v1/timers/{timerId}/stop`

Complete a timer owned by the key user in the bound workspace.

### [List personal time entries](https://www.tracktimer.app/docs/list-time-entries)

`GET /api/v1/time-entries`

Read personal workspace history with project filtering and cursor pagination.

## What this API covers

V1 exposes the seven operations documented here, including [project creation](https://www.tracktimer.app/docs/create-project) for owners and admins. It does not expose client creation, invoices, or agency-wide financial reports. API access follows the key owner's current workspace membership and project access.

[Errors and safe retries](https://www.tracktimer.app/docs/errors-and-retries) · [Pagination](https://www.tracktimer.app/docs/pagination)

## Documentation downloads

- [Documentation index](https://www.tracktimer.app/llms.txt): A compact guide to the public documentation.
- [All documentation as Markdown](https://www.tracktimer.app/llms-full.txt): The complete public documentation in one file.
- [OpenAPI specification](https://www.tracktimer.app/openapi.json): The machine-readable REST API contract.