Create a project

Create a project under an active client in the key’s workspace. The creator is assigned in the same transaction, so a project needs no prior time entries or active timer. Creation does not start a timer.

Request

POST https://www.tracktimer.app/api/v1/projects with bearer authentication, projects:write, and Content-Type: application/json. The current workspace role must be owner or admin. Existing keys need replacement to receive the new scope.

• clientId: required UUID of an active client in this workspace.
• name: required project name, trimmed, 1–200 characters.
• color: optional supported color or null to inherit the client color.

Unknown properties are rejected. The server chooses the workspace and creator from the key.

curl --request POST "https://www.tracktimer.app/api/v1/projects" \
  --header "Authorization: Bearer $TRACKTIMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"clientId":"11111111-1111-4111-8111-111111111111","name":"Website refresh"}'

Response — 201

project contains its UUID, parent client UUID, name, and resolved color.

{"project":{"id":"22222222-2222-4222-8222-222222222222","clientId":"11111111-1111-4111-8111-111111111111","name":"Website refresh","color":"#ff5c35"}}

Use the returned project ID to start a timer. Normal member rate requirements still apply. The creator can later remove their assignment through workspace member management.

Errors and retries

This endpoint is not idempotent and does not use Idempotency-Key. Never automatically retry project creation after a timeout, server error, or lost response: the project may already exist. List projects for the client and reconcile before deciding to create again.

Missing scope or a non-admin role returns 403. An unknown, archived, or other-workspace client returns 404. Invalid input returns 400. See shared errors.