# Create a project

Source: https://www.tracktimer.app/docs/create-project

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

`POST /api/v1/projects`

Required scope: `projects:write`

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.

```sh
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.

```json
{"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](https://www.tracktimer.app/docs/start-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](https://www.tracktimer.app/docs/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](https://www.tracktimer.app/docs/errors-and-retries).

Examples use illustrative IDs and data. Use the values returned by your own workspace. [Review error handling and retry behavior.](https://www.tracktimer.app/docs/errors-and-retries)