Clients

Full CRUD over clients. Projects link to a client by name via the project's clientName field.

A client is a lightweight directory entry — a name plus optional notes — shared across the organization. Projects link to a client through the project's free-text clientName: when you create or update a project with a clientName, a matching client is found-or-created automatically and the project's clientId is set. Renaming a client updates the linked projects' label; deleting one keeps the projects and just clears their clientId.

Endpoints

Method	Path	Notes
`GET`	`/api/v1/clients`	List. Supports `query`, offset paging.
`POST`	`/api/v1/clients`	Create. Org owner or admin only. Accepts `Idempotency-Key`.
`GET`	`/api/v1/clients/{id}`	Returns the client plus its linked projects.
`PATCH`	`/api/v1/clients/{id}`	Update. Org owner or admin only.
`DELETE`	`/api/v1/clients/{id}`	Delete. Org owner or admin only.

Client model

{
  "id": "9b1c…",
  "organizationId": "1f3c…",
  "name": "Acme Corp",
  "phone": null,
  "status": "active",
  "notes": "Primary retainer client.",
  "createdAt": "2026-05-01T08:30:00.000Z",
  "updatedAt": "2026-05-19T14:22:11.000Z"
}

Field	Type	Notes
`name`	string	1–150 chars.
`notes`	string \| null	Free text, ≤ 2000 chars.
`phone`	string \| null	Reserved; not editable via this API.
`status`	enum	`active` · `inactive`. Reserved; defaults to `active`.

Listing clients

GET /api/v1/clients?query=acme&limit=25&offset=0

Param	Type	Notes
`limit`	int 1–100	Default 50.
`offset`	int ≥ 0	Default 0.
`query`	string	Case-insensitive search over `name`.

Returns { data, total }, newest first.

Creating a client

POST /api/v1/clients
{
  "name": "Acme Corp",
  "notes": "Primary retainer client."
}

Required:

Field	Type	Constraint
`name`	string	1–150 chars

Optional:

Field	Type	Constraint
`notes`	string	≤ 2000 chars

Response: 201 Created with the new client.

Retrieving a client

GET /api/v1/clients/{id}

Returns the client plus projectsCount and a linkedProjects array (id, name, status, createdAt), newest first.

Updating a client

PATCH /api/v1/clients/{id}
{ "name": "Acme Incorporated", "notes": null }

All fields are optional. Pass null to clear notes. Renaming a client also updates the clientName label on every linked project. Org owner or admin only.

Deleting a client

DELETE /api/v1/clients/{id}

Returns { "data": { "success": true } }. Linked projects are kept — their clientId is set to null (the clientName text is preserved). Org owner or admin only.