The API contract evolves incrementally as each epic is implemented. This page documents endpoint specifications, request/response shapes, and error patterns for all routes.

GET /api/health

Auth required: No

Response (200 OK):

{
  "status": "ok",
  "timestamp": "2026-02-07T12:00:00.000Z"
}

GET /api/health is a liveness check only: it touches neither the database nor password hashing.

GET /api/health/ready

Auth required: No

Response (200 OK):

{
  "status": "ready",
  "timestamp": "2026-02-07T12:00:00.000Z"
}

Error responses:

Behavior:

• Every call runs SELECT 1 against the database.
• The password-hashing self-check (hash a fixed string with the current scrypt parameters, then verify it) runs once per process, on the first call, and only a success is cached. A failure clears the cache, so the next call retries it. Concurrent first calls share one self-check. One hash costs about 128 MiB (ADR-010, Amendments), which is why it is not repeated on every probe.
• The Docker image's HEALTHCHECK calls this endpoint every 30 seconds (Dockerfile). The sample docker-compose.yml healthcheck calls GET /api/health instead.

GET /api/config

Auth required: No

Returns deployment-level configuration that the client needs for rendering. This endpoint is public because the client needs configuration (e.g., display currency) before authentication.

Response (200 OK):

{
  "currency": "EUR",
  "vatRate": 0.19,
  "autoItemizeEnabled": false,
  "llmEnabled": false
}

Which flag to use. llmEnabled and autoItemizeEnabled are always equal — both mean "LLM_BASE_URL, LLM_API_KEY, and LLM_MODEL are all set". llmEnabled is the preferred field for any new LLM-backed feature; autoItemizeEnabled is retained only for the existing auto-itemize UI and should be treated as deprecated. New code must not introduce a third alias — if the two ever need to diverge (per-feature LLM toggles), that is a contract change requiring an ADR, not a new boolean.

Environment variables:

Notes:

• This endpoint always returns 200. It cannot fail.
• The currency value is set at deployment time and applies to all users in the instance.
• The client fetches this once at startup and uses the value for all Intl.NumberFormat currency formatting.
• autoItemizeEnabled is false by default. All three LLM env vars (LLM_BASE_URL, LLM_API_KEY, LLM_MODEL) must be set to enable auto-itemize. The LLM API key is never returned to the client; only the boolean flag is surfaced.
• See ADR-031 for the full LLM integration design and security posture.

Cornerstone supports two authentication methods:

1. Local authentication -- Email/password login for the initial admin account (setup flow) and as a fallback
2. OIDC authentication -- OpenID Connect sign-in for existing accounts. By default OIDC never creates accounts (opt-in just-in-time provisioning of member accounts via OIDC_JIT_PROVISIONING, default false; see ADR-035's #2142 amendment): a first OIDC login links the provider identity to the existing account whose email matches the provider's verified email claim (see GET /api/auth/oidc/callback and ADR-035)

All authenticated API requests use a server-side session. The session token is delivered as an HttpOnly cookie (cornerstone_session). There are no bearer tokens or API keys.

The cookie is set on successful login (local or OIDC) and cleared on logout.

OIDC is enabled when the three variables OIDC_ISSUER, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET are set (server/src/plugins/config.ts, oidcEnabled). If any of the three is missing, GET /api/auth/oidc/login returns 404 OIDC_NOT_CONFIGURED, GET /api/auth/oidc/callback redirects to /login?error=oidc_not_configured, and POST /api/users with authProvider: "oidc" (an SSO-only account) returns 400 OIDC_NOT_CONFIGURED.

OIDC_JIT_PROVISIONING does not take part in enabling OIDC and has no effect while OIDC is disabled. It accepts true or false (case-insensitive); any other value fails startup. With true, an OIDC sign-in that resolves to no account creates a member account (see the callback's Behavior, step 8). Enable it only with a provider that restricts who can sign in: there is no domain or email allow-list, so with an open provider such as consumer Google anyone who finds the login URL can register.

The callback URL is not configured through a dedicated environment variable — there is no OIDC_REDIRECT_URI, and the server never reads one. The redirect URI sent to the provider is derived per request as <EXTERNAL_URL>/api/auth/oidc/callback, falling back to the incoming request's own origin (request.protocol + request.host) when EXTERNAL_URL is unset. Behind a reverse proxy, set EXTERNAL_URL: both halves of the fallback are gated on TRUST_PROXY — request.protocol reads X-Forwarded-Proto and request.host reads X-Forwarded-Host only when TRUST_PROXY=true, so with it unset the fallback yields the container's own internal scheme and host, not the public one. A correct scheme is therefore not sufficient to make the fallback safe. The redirect URI registered with the OIDC provider must match the derived value exactly.

POST /api/auth/login is rate limited per client identity (see Rate-Limit Key below), configured via AUTH_RATE_LIMIT_MAX and AUTH_RATE_LIMIT_WINDOW. Exceeding the limit returns 429 with the standard error shape and code RATE_LIMIT_EXCEEDED, alongside the standard x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, and retry-after response headers. Behind a reverse proxy, TRUST_PROXY=true is required for the limit to be keyed on the real client address rather than the proxy's.

Separately from the login rate limit, every request that runs scrypt (ADR-010) goes through one in-process queue. That covers POST /api/auth/setup, POST /api/auth/login (including the dummy verification for unknown or password-less accounts), POST /api/users/me/password, POST /api/users for a local account, and the first GET /api/health/ready. At most two derivations run at once. When 50 callers are already waiting, a further request is rejected immediately with 429 RATE_LIMIT_EXCEEDED and the message Too many requests. Please try again shortly..

• The body is the same for every account, so it reveals nothing about which accounts exist.
• No rate-limit headers are sent, because this is a capacity limit, not a per-client quota.
• On login, a wrong password is recorded against the account before the extra dummy verification for legacy hashes runs, so a full queue cannot be used to skip the lockout counter.
• The best-effort rehash after a successful login swallows this error like any other, and the login still succeeds.

The key is not the raw client IP. It is request.ip passed through @fastify/rate-limit's normalizeIP:

The /64 truncation means every address within a client's IPv6 prefix shares a single bucket. This is required, not incidental: residential and hosting IPv6 allocations hand out a /64 (or larger) to a single subscriber, so a per-address key lets an attacker rotate through 2^64 addresses and defeat the limit entirely. A keyGenerator returning request.ip verbatim reintroduces exactly that bypass — this was CVE-2026-15144 (issue #1995).

The invariant: the rate-limit key must always be normalizeIP-normalized, at the same subnet width the plugin is configured with. rateLimitPlugin satisfies this with an explicit, exported key generator rather than the library's default:

const IPV6_SUBNET = 64;

export function rateLimitKeyGenerator(request: Pick<FastifyRequest, 'ip'>): string {
  return normalizeIP(request.ip ?? 'unknown', IPV6_SUBNET);
}

The same IPV6_SUBNET constant is passed to normalizeIP and to the plugin's own ipv6Subnet option, so the two cannot drift. Two hazards make this explicit generator necessary rather than merely equivalent to the library default:

• request.ip is typed string but is genuinely null when the socket carries no address metadata. normalizeIP dereferences its argument (ip.toLowerCase()), so a generator that forwards request.ip unguarded throws and turns every rate-limited endpoint into a 500. The ?? 'unknown' fallback puts such requests in one shared bucket instead.
• @fastify/rate-limit gates its own normalization on generator identity. It applies normalizeIP only when keyGenerator is the exact defaultKeyGenerator reference; every other generator is invoked as keyGenerator(req) with no subnet argument and no normalization wrapper. So any custom generator — including one that just wraps the default — silently loses the /64 truncation unless it calls normalizeIP itself. That gate is what made CVE-2026-15144 possible.

Invariants any change to rateLimitKeyGenerator MUST preserve:

• Call normalizeIP on every return path. Returning request.ip verbatim, or falling through to a raw address on a guard/error path, is exactly CVE-2026-15144.
• Pass the subnet width explicitly, from the same constant given to ipv6Subnet. Relying on normalizeIP's own parameter default makes the ipv6Subnet option silently ineffective and lets the two values drift apart.
• Keep the null guard. request.ip's string type is a lie at runtime; removing the fallback reintroduces the 500.
• Never parse X-Forwarded-For / X-Real-IP by hand. Redundant — TRUST_PROXY already makes request.ip reflect those headers — and such code typically bypasses normalizeIP on the fallback path, reintroducing the bypass for proxied requests only, which is harder to spot.

POST /api/auth/setup has a separate, fixed limit of 5 requests per 15 minutes (not configurable).

Returns the current authentication state. This is the first endpoint the client calls on app load to determine what UI to show.

Auth required: No (returns different shapes based on auth state)

Response (200 OK -- authenticated):

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "displayName": "Admin User",
    "role": "admin",
    "authProvider": "local",
    "oidcLinked": false,
    "createdAt": "2026-02-08T10:00:00.000Z"
  },
  "oidcEnabled": true
}

Response (200 OK -- not authenticated, setup required):

{
  "user": null,
  "setupRequired": true,
  "oidcEnabled": false
}

Response (200 OK -- not authenticated, setup complete):

{
  "user": null,
  "setupRequired": false,
  "oidcEnabled": true
}

Notes:

• This endpoint never returns 401. It always returns 200 with the current state.
• setupRequired: true means zero users exist in the database; the client should show the setup form.
• oidcEnabled tells the client whether to show the "Login with SSO" button.

Creates the first admin user. Only works when zero users exist in the database.

Auth required: No

Request body:

{
  "email": "[email protected]",
  "displayName": "Admin User",
  "password": "securepassword123"
}

Response (201 Created):

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "displayName": "Admin User",
    "role": "admin",
    "authProvider": "local",
    "oidcLinked": false,
    "createdAt": "2026-02-08T10:00:00.000Z"
  }
}

The response also sets the cornerstone_session cookie (the admin is logged in immediately after setup).

Error responses:

Authenticates a local user with email and password.

Auth required: No

Request body:

{
  "email": "[email protected]",
  "password": "securepassword123"
}

Response (200 OK):

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "displayName": "Admin User",
    "role": "admin",
    "authProvider": "local",
    "oidcLinked": false,
    "createdAt": "2026-02-08T10:00:00.000Z"
  }
}

The response also sets the cornerstone_session cookie.

Error responses:

Security notes:

• The INVALID_CREDENTIALS error uses a generic message ("Invalid email or password") that does not reveal whether the email exists or the password was wrong.
• Deactivated accounts that have a password receive ACCOUNT_DEACTIVATED to distinguish from invalid credentials (the user should contact an admin).
• Accounts without a password_hash (authProvider: "oidc": OIDC just-in-time provisioned, or admin-created SSO-only via POST /api/users) attempting local login receive INVALID_CREDENTIALS, including when they are deactivated. The no-password branch runs a dummy scrypt verify and returns before the deactivated and lockout checks, so the response (status, code, message and timing) is the same as for an unknown email and does not reveal that the address has an account.
• Unknown emails and accounts without a password are checked against a dummy scrypt hash made once per process with the current parameters, so their timing matches a real verification after the first such request.
• After a successful login, a password hash stored with the legacy scrypt parameters is rehashed with the current ones and saved (best-effort: a failure is logged and the login still succeeds). The response is unaffected. See ADR-010, Amendments.
• Local accounts that have been linked to OIDC (oidcLinked: true) keep their password and can still sign in here. Linking never changes an account's id, role, authProvider, or password_hash.

Destroys the current session and clears the session cookie.

Auth required: Yes

Request body: None

Response (204 No Content): Empty body. The cornerstone_session cookie is cleared.

Error responses:

Initiates the OIDC Authorization Code flow by redirecting the user to the OIDC provider.

Auth required: No

Query parameters:

redirect is accepted only when safeAppPath (@cornerstone/shared, shared/src/routes/safePath.ts) returns it unchanged. The value must be a string of 1 to 2048 characters (MAX_APP_PATH_LENGTH) that starts with /, does not start with //, and contains no \, no :// and no ASCII control character (U+0000 to U+001F, U+007F). Browsers read \ as / and strip tab and newline inside URLs, so /\evil.example or /<tab>/evil.example would otherwise become the off-site //evil.example. The rule validates and never rewrites: there is no decoding or normalization. An absent or rejected value falls back to the Home path, /. The client's sign-in page (/login?next=) sends its next value here, so the SSO sign-in lands on the deep link that the signed-out user asked for.

Response (302 Found): Redirects to the OIDC provider's authorization endpoint with:

• response_type=code
• client_id from config
• redirect_uri from config
• scope=openid email profile
• state = cryptographically random value (stored server-side temporarily for CSRF protection)

Error responses:

Handles the OIDC provider's redirect after the user authenticates.

Auth required: No

Query parameters (set by the OIDC provider):

Response (302 Found): On success, redirects to the app (the redirect value validated by GET /api/auth/oidc/login and stored with the state, or /). The cornerstone_session cookie is set.

Behavior:

1. Validates the state parameter against the stored value
2. Exchanges the code for tokens using the OIDC token endpoint. The redirect_uri sent in this exchange is derived by the same expression as the login leg (<EXTERNAL_URL> or the request origin, + /api/auth/oidc/callback, keeping the callback's query string) — see Environment Variables (Auth)
3. Extracts sub, email, email_verified, name and preferred_username from the ID token (only a boolean true counts as verified; an absent claim is unverified). The two name claims are used only by step 8 (provisioning)
4. Subject match. Looks up the user by oidc_subject = sub (any auth_provider). If found, that account signs in — neither an email claim nor email_verified is required on this path (the subject is already bound)
5. Email present. No subject match: an empty or missing email claim redirects with missing_email (error code OIDC_MISSING_EMAIL)
6. Verified-email gate. If email_verified !== true, redirects with oidc_email_unverified. This check runs before any email lookup, so an unverified token can never probe which emails have accounts
7. Email match. Looks up the account by email, case-insensitively. An exact (case-sensitive) match is preferred. If there is no exact match and more than one account matches case-insensitively, the result is ambiguous and treated as no match. A match continues at step 9; no match continues at step 8
8. No match: reject or provision. With OIDC_JIT_PROVISIONING unset or false (the default), redirects with oidc_no_matching_account: OIDC does not create the account, which only initial setup (POST /api/auth/setup) or an admin (POST /api/users) can do. With the flag true, the callback creates the account (outcome provisioned), except that it still redirects with oidc_no_matching_account when the email was ambiguous in step 7 (fail closed) or the users table is empty (initial setup has not run; provisioning a member first would permanently block POST /api/auth/setup). The new account has role = 'member' (never admin), authProvider = 'oidc', oidc_subject = sub, the claim's email, and no password. displayName is the first non-empty of name, preferred_username, then the email, trimmed and capped at 100 code points. The insert runs in the step 7 transaction. Transactions serialize within the process, so a second sign-in for the same sub finds the account at step 4 and never inserts. If a write from outside the process (another instance or an external tool) already bound the sub, the insert hits the unique index on oidc_subject. The violation is caught, the account is re-read by subject, and it signs in as a subject match. The server logs provisioning at info with the new userId only. Continues at step 11
9. Deactivated. If the matched account is deactivated, redirects with account_deactivated and does not link. (A deactivated account found in step 4 is refused the same way.) A deactivated match is never replaced by a provisioned account
10. Link. Sets the matched account's oidc_subject to sub. If the account was already linked to a different subject, the re-bind is accepted (gated by step 6) and logged at warn. id, role, authProvider, and password_hash are unchanged
11. Creates a session and sets the cookie
12. Redirects to the app

Error responses (all via redirect to /login?error=<code>, plus &next=<path> when the sign-in state is known):

next is the app redirect stored with the state, URL-encoded. It is appended only after a valid state was consumed (account_deactivated, missing_email, oidc_email_unverified, oidc_no_matching_account, and oidc_error from the token exchange), or on the provider-error branch when the provider's redirect carries a valid state. That branch now consumes the state, so the state can no longer be reused. next is never appended for oidc_not_configured or invalid_state (or a missing state), never when the stored value is the Home path /, and never when it fails safeAppPath. The key order is error, then next, so a redirect without next stays exactly /login?error=<code>. The login page keeps next for the next sign-in attempt; its error banner does not depend on it.

The redirect codes are exactly the OIDC_LOGIN_ERROR_CODES tuple in @cornerstone/shared (OidcLoginErrorCode). The server builds every redirect through a helper typed against it, and the login page translates only codes in the tuple (an unknown ?error= value renders no banner). Adding a code means adding it to the tuple; the client's I18N_UNION_KEYS.oidcLoginError locale-parity test then requires its translation.

Notes:

• OIDC callback errors redirect to the login page with a query parameter rather than returning JSON, because this endpoint is called via browser redirect (not AJAX).
• The three OIDC account-resolution rejections map to the error codes OIDC_MISSING_EMAIL (403), OIDC_EMAIL_UNVERIFIED (403), and OIDC_NO_MATCHING_ACCOUNT (403) in the Error Codes table; the endpoint surfaces them only as the redirect codes above.
• The earlier email_conflict redirect (and the EMAIL_CONFLICT error code) no longer exist: an OIDC identity whose verified email matches a local account is linked to it rather than rejected.

Returns the full profile of the currently authenticated user.

Auth required: Yes

Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "displayName": "Admin User",
  "role": "admin",
  "authProvider": "local",
  "oidcLinked": false,
  "createdAt": "2026-02-08T10:00:00.000Z",
  "updatedAt": "2026-02-08T10:00:00.000Z"
}

Error responses:

Updates the current user's profile. Only displayName can be changed by the user.

Auth required: Yes

Request body:

{
  "displayName": "New Display Name"
}

Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "displayName": "New Display Name",
  "role": "admin",
  "authProvider": "local",
  "oidcLinked": false,
  "createdAt": "2026-02-08T10:00:00.000Z",
  "updatedAt": "2026-02-08T12:00:00.000Z"
}

Error responses:

Changes the current user's password. Only available for local auth users.

Auth required: Yes

Request body:

{
  "currentPassword": "oldpassword123",
  "newPassword": "newpassword456"
}

Response (204 No Content): Empty body.

Error responses:

Notes:

• The 403 covers every authProvider: "oidc" account: OIDC just-in-time provisioned and admin-created SSO-only (POST /api/users with authProvider: "oidc"). It runs in the handler, after body schema validation, so such a user sending an invalid body gets 400, not 403.
• This is the only password endpoint, and it requires the current password. No endpoint sets a password for an account that has none, and authProvider never changes, so an SSO-only account stays SSO-only (#2122).

Returns a list of all users. Supports search filtering.

Auth required: Yes (any authenticated user; the route has no role check, so members can list users too)

Query parameters:

Response (200 OK):

{
  "users": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "displayName": "Admin User",
      "role": "admin",
      "authProvider": "local",
      "oidcLinked": false,
      "createdAt": "2026-02-08T10:00:00.000Z",
      "deactivatedAt": null
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "email": "[email protected]",
      "displayName": "Member User",
      "role": "member",
      "authProvider": "oidc",
      "oidcLinked": true,
      "createdAt": "2026-02-08T11:00:00.000Z",
      "deactivatedAt": null
    }
  ]
}

Notes:

• Returns both active and deactivated users (deactivated users have deactivatedAt set)
• No pagination needed for <5 users; will be revisited if the user count model changes
• The password_hash and oidc_subject fields are never exposed in API responses

Error responses:

Unknown query parameters are silently dropped, not rejected: the querystring schema declares additionalProperties: false, and Fastify's default AJV configuration (removeAdditional: true) strips the extra keys before the handler runs.

Creates a local account with a password, or (with authProvider: "oidc") an SSO-only account with no password. Besides initial setup (POST /api/auth/setup) and opt-in OIDC just-in-time provisioning (OIDC_JIT_PROVISIONING, see ADR-035), this is the only way an account is created.

Auth required: Yes (admin role)

Request body (email, displayName and role are required; password is required for a local account and forbidden for an SSO-only one; unknown properties are stripped, not rejected):

{
  "email": "[email protected]",
  "displayName": "Member User",
  "password": "a-long-password",
  "role": "member"
}

SSO-only account (requires OIDC to be enabled):

{
  "email": "[email protected]",
  "displayName": "Member User",
  "role": "member",
  "authProvider": "oidc"
}

Lengths are counted in code points (AJV minLength/maxLength).

Response (201 Created): the new user wrapped in a user key (unlike PATCH /api/users/:id, which returns the bare object). The shape is the User Response Shape.

{
  "user": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "email": "[email protected]",
    "displayName": "Member User",
    "role": "member",
    "authProvider": "local",
    "createdAt": "2026-10-01T10:00:00.000Z",
    "updatedAt": "2026-10-01T10:00:00.000Z",
    "deactivatedAt": null,
    "oidcLinked": false
  }
}

An SSO-only account is returned with "authProvider": "oidc" and "oidcLinked": false.

Error responses:

Notes:

• Check order: the authentication hook runs at preValidation (401), then body schema validation (400), then the admin role check at preHandler (403). A non-admin sending an invalid body therefore gets 400, not 403. The handler then applies, in this order: the password rule (400 VALIDATION_ERROR), the OIDC configuration check for "oidc" (400 OIDC_NOT_CONFIGURED), and the email conflict check (409). An "oidc" request that also carries a password gets VALIDATION_ERROR even while OIDC is disabled. No row is written on any error.
• The password rule is enforced in the handler, not in the JSON schema, so its two failures carry details.field rather than the schema's details.fields[]. Omitting password never silently creates an SSO-only account: authProvider: "oidc" must be explicit.
• OIDC_NOT_CONFIGURED is 400 here (the request is well-formed but the instance cannot satisfy it), unlike GET /api/auth/oidc/login, where the route itself is unavailable and it is 404.
• A local account's password is hashed with scrypt (ADR-010) before storage. No session is created for the new user and the calling admin's session is unchanged.
• SSO-only accounts are stored with auth_provider = 'oidc', password_hash = NULL and oidc_subject = NULL. They have oidcLinked: false until the user's first OIDC sign-in with a verified email that matches the account, which binds the subject (GET /api/auth/oidc/callback, link step). Until then, and whenever OIDC is disabled, the account cannot sign in at all. Local login answers INVALID_CREDENTIALS (see POST /api/auth/login), and POST /api/users/me/password answers 403.
• SSO-only is permanent. No endpoint sets a password for an account without one, and PATCH /api/users/:id cannot change authProvider. Because emails are never released (deactivation is a soft delete and the conflict check includes deactivated accounts), switching a person to a local account means: change the SSO-only account's email to a placeholder, deactivate it, then create a new local account with the real email. History stays on the old account. See ADR-035, Amendment (#2122).
• The uniqueness check is an exact, case-sensitive comparison (findByEmail), and it includes deactivated accounts: an email held by a deactivated user returns 409. Case variants ([email protected] vs [email protected]) can coexist, consistent with ADR-035.
• The limits match the rest of the API: displayName 1-100 as on PATCH /api/users/me and PATCH /api/users/:id, and a 12-character password minimum as on POST /api/users/me/password. This endpoint has no route-specific rate limit.

Updates a user's role or display name. Admins can also update a user's email.

Auth required: Yes (admin role)

Path parameters:

Request body (all fields optional, at least one required):

{
  "displayName": "Updated Name",
  "email": "[email protected]",
  "role": "admin"
}

Response (200 OK):

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "email": "[email protected]",
  "displayName": "Updated Name",
  "role": "admin",
  "authProvider": "oidc",
  "oidcLinked": true,
  "createdAt": "2026-02-08T11:00:00.000Z",
  "deactivatedAt": null
}

Error responses:

Deactivates a user account (soft delete). Sets deactivated_at and invalidates all active sessions.

Auth required: Yes (admin role)

Path parameters:

Response (204 No Content): Empty body.

Error responses:

Notes:

• This is a soft delete: the user record is retained with deactivated_at set to the current timestamp
• All active sessions for the deactivated user are deleted immediately
• Deactivated users cannot log in. Local login returns ACCOUNT_DEACTIVATED for an account with a password and INVALID_CREDENTIALS for one without (OIDC-provisioned or SSO-only, see POST /api/auth/login); the OIDC callback redirects with account_deactivated
• An already-deactivated user can be "re-deleted" without error (idempotent)

Clears a login lockout. Local login locks an account for 15 minutes after 10 consecutive failed attempts (423 ACCOUNT_LOCKED, see the Error Codes table); this endpoint resets failed_login_attempts to 0 and locked_until to NULL immediately.

Auth required: Yes (admin role)

Path parameters:

Request body: None (the route declares no body schema; a body, if sent, is ignored).

Response (204 No Content): Empty body.

Error responses:

Notes:

• Idempotent: unlocking an account that is not locked also returns 204 (and bumps updated_at).
• The endpoint does not check deactivated_at; unlocking a deactivated account returns 204 but does not reactivate it.
• Sessions are not touched.

All /api/* routes are protected by a Fastify preValidation hook (server/src/plugins/auth.ts), so an unauthenticated request gets 401 before body validation runs. Role checks (requireRole) run later, at preHandler, after validation. The hook skips these routes (PUBLIC_ROUTES, matched on the route pattern):

Admin-only routes additionally check user.role === 'admin' via a requireRole('admin') decorator.

Work items are the central entity of the application. All endpoints in this section require authentication. Both admin and member roles can perform all work item operations (no role restriction).

Work item summary (used in list responses):

interface WorkItemSummary {
  id: string;
  title: string;
  status: WorkItemStatus;
  startDate: string | null; // PLANNED start (stored, never floored to today); null for an undated task
  endDate: string | null; // PLANNED end
  projectedStartDate: string | null; // Forecast start (after the today floor); equals startDate unless late/held up; start of the forecast for an undated task
  projectedEndDate: string | null; // Forecast end; equals endDate unless late/held up
  isLate: boolean; // The today floor moved this item itself (never for completed or undated)
  lateDays: number | null; // >= 1 exactly when isLate
  isHeldUp: boolean; // Not late itself, but moved by an unfinished late predecessor
  actualStartDate: string | null; // Actual start date (YYYY-MM-DD)
  actualEndDate: string | null; // Actual end date (YYYY-MM-DD)
  durationDays: number | null;
  assignedUser: UserSummary | null;
  assignedVendor: VendorSummary | null;
  area: AreaSummary | null;
  createdAt: string;
  updatedAt: string;
}

Work item detail (used in single-item responses):

interface WorkItemDetail {
  id: string;
  title: string;
  description: string | null;
  status: WorkItemStatus;
  startDate: string | null; // PLANNED start (stored, never floored to today); null for an undated task
  endDate: string | null; // PLANNED end
  projectedStartDate: string | null; // Forecast start (after the today floor); equals startDate unless late/held up; start of the forecast for an undated task
  projectedEndDate: string | null; // Forecast end; equals endDate unless late/held up
  isLate: boolean; // The today floor moved this item itself (never for completed or undated)
  lateDays: number | null; // >= 1 exactly when isLate
  isHeldUp: boolean; // Not late itself, but moved by an unfinished late predecessor
  actualStartDate: string | null; // Actual start date (YYYY-MM-DD)
  actualEndDate: string | null; // Actual end date (YYYY-MM-DD)
  durationDays: number | null;
  startAfter: string | null;
  startBefore: string | null;
  assignedUser: UserSummary | null;
  assignedVendor: VendorSummary | null;
  area: AreaSummary | null;
  createdBy: UserSummary | null;
  subtasks: SubtaskResponse[];
  dependencies: {
    predecessors: DependencyResponse[];
    successors: DependencyResponse[];
  };
  budgets: WorkItemBudgetLine[];
  createdAt: string;
  updatedAt: string;
}

Supporting types:

type WorkItemStatus = 'not_started' | 'in_progress' | 'completed';
type DependencyType = 'finish_to_start' | 'start_to_start' | 'finish_to_finish' | 'start_to_finish';
type ConfidenceLevel = 'own_estimate' | 'professional_estimate' | 'quote' | 'invoice';

interface UserSummary {
  id: string;
  displayName: string;
  email: string;
}

interface AreaAncestor {
  id: string;
  name: string;
  color: string | null;
}

interface AreaSummary {
  id: string;
  name: string;
  color: string | null;
  /** Root-first ancestor chain. Does NOT include the area itself. Empty array for root-level areas. */
  ancestors: AreaAncestor[];
}

interface SubtaskResponse {
  id: string;
  title: string;
  isCompleted: boolean;
  sortOrder: number;
  createdAt: string;
  updatedAt: string;
}

interface DependencyResponse {
  workItem: WorkItemSummary;
  dependencyType: DependencyType;
  leadLagDays: number; // Lead (negative) or lag (positive) offset in days; default 0
}

interface WorkItemBudgetLine {
  id: string;
  workItemId: string;
  description: string | null;
  plannedAmount: number;
  confidence: ConfidenceLevel;
  confidenceMargin: number; // Computed: 0.20, 0.10, 0.05, or 0.00
  budgetCategory: BudgetCategoryResponse | null;
  budgetSource: BudgetSourceSummary | null;
  vendor: VendorSummary | null;
  actualCost: number; // Computed: sum of itemized amounts from ALL linked invoices, including quotations. See "Quotation handling for `actualCost`" below.
  actualCostPaid: number; // Computed: aggregates per-deposit 'paid'/'claimed' contributions (proportional split) + residual when parent invoice is 'paid'/'claimed'. Excludes quotations.
  invoiceCount: number; // Computed: count of linked invoices
  invoiceLink: BudgetLineInvoiceLink | null; // The (at most one) linked invoice; null if unlinked
  createdBy: UserSummary | null;
  createdAt: string;
  updatedAt: string;
}

interface BudgetLineInvoiceLink {
  invoiceBudgetLineId: string;
  invoiceId: string;
  invoiceNumber: string | null;
  invoiceDate: string;
  invoiceStatus: InvoiceStatus;
  itemizedAmount: number;
  vendorId: string | null; // Denormalized from the invoice's vendor
  vendorName: string | null; // Denormalized from the invoice's vendor (may be null only if the vendor row has no name)
}

interface BudgetSourceSummary {
  id: string;
  name: string;
  sourceType: string;
}

interface VendorSummary {
  id: string;
  name: string;
  trade: TradeSummary | null;
}

interface TradeSummary {
  id: string;
  name: string;
  color: string | null;
}

Notes on the detail response:

• area is the spatial location of the work item (nullable). Only id, name, and color are embedded.
• assignedVendor is the vendor assigned to this work item (nullable, mutually exclusive with assignedUser).
• subtasks are always embedded, sorted by sortOrder ascending.
• dependencies.predecessors lists work items that this item depends on. dependencies.successors lists work items that depend on this item. Both include a summary of the related work item.
• budgets are always embedded, listing all budget lines for the work item. Each budget line includes computed fields (confidenceMargin, actualCost, actualCostPaid, invoiceCount) derived from linked invoices and the confidence level enum.
• Notes are NOT embedded in the detail response. They are fetched separately via GET /api/work-items/:id/notes to allow independent pagination if needed in the future.
• The work item's trade is derived transitively: work_item.assignedVendor.trade. There is no direct trade field on work items.

Returns a paginated, filterable, sortable list of work items.

startDate/endDate are the planned dates. The forecast fields (projectedStartDate, projectedEndDate, isLate, lateDays, isHeldUp) come from the same read-time projection as GET /api/timeline (contract 4, #2199). start_date/end_date sorting and the four date filters use the shown date, actualStartDate ?? projectedStartDate (respectively end): the date every client surface displays. Rows without a shown date sort last in both directions; ties break on createdAt then id. A bounded date filter excludes rows without a shown date.

Auth required: Yes

Query parameters:

Response (200 OK):

{
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Foundation Work",
      "status": "in_progress",
      "startDate": "2026-03-01",
      "endDate": "2026-03-15",
      "actualStartDate": "2026-03-02",
      "actualEndDate": null,
      "durationDays": 14,
      "assignedUser": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "displayName": "Admin User",
        "email": "[email protected]"
      },
      "assignedVendor": null,
      "area": {
        "id": "area-kitchen",
        "name": "Kitchen",
        "color": "#F59E0B",
        "ancestors": [
          { "id": "area-ground-floor", "name": "Ground Floor", "color": "#3B82F6" },
          { "id": "area-living-spaces", "name": "Living Spaces", "color": "#10B981" }
        ]
      },
      "createdAt": "2026-02-15T10:00:00.000Z",
      "updatedAt": "2026-02-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "totalItems": 1,
    "totalPages": 1
  },
  "filterMeta": {
    "budgetLines": { "min": 0, "max": 5 }
  }
}

The filterMeta object contains min/max bounds for each numeric filterable column, computed from all rows matching the current non-numeric filters. Used by the frontend to set appropriate slider ranges on number filters. Returns { "min": 0, "max": 0 } per column when no rows match.

Error responses:

Creates a new work item.

Auth required: Yes

Request body:

{
  "title": "Foundation Work",
  "description": "Excavation and concrete pouring for the foundation",
  "status": "not_started",
  "startDate": "2026-03-01",
  "endDate": "2026-03-15",
  "durationDays": 14,
  "startAfter": "2026-02-28",
  "startBefore": "2026-03-10",
  "assignedUserId": "550e8400-e29b-41d4-a716-446655440000",
  "areaId": "area-kitchen"
}

The createdBy field is automatically set to the authenticated user's ID.

Response (201 Created):

Returns a WorkItemDetail object (same shape as GET /api/work-items/:id).

Error responses:

Returns a single work item with full detail including tags, subtasks, and dependencies.

Auth required: Yes

Path parameters:

Response (200 OK):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Foundation Work",
  "description": "Excavation and concrete pouring for the foundation",
  "status": "in_progress",
  "startDate": "2026-03-01",
  "endDate": "2026-03-15",
  "actualStartDate": "2026-03-02",
  "actualEndDate": null,
  "durationDays": 14,
  "startAfter": "2026-02-28",
  "startBefore": "2026-03-10",
  "assignedUser": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "displayName": "Admin User",
    "email": "[email protected]"
  },
  "assignedVendor": null,
  "area": { "id": "area-kitchen", "name": "Kitchen", "color": "#F59E0B", "ancestors": [] },
  "createdBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "displayName": "Admin User",
    "email": "[email protected]"
  },
  "subtasks": [
    {
      "id": "s1",
      "title": "Excavate site",
      "isCompleted": true,
      "sortOrder": 0,
      "createdAt": "2026-02-15T10:00:00.000Z",
      "updatedAt": "2026-02-16T08:00:00.000Z"
    },
    {
      "id": "s2",
      "title": "Pour concrete",
      "isCompleted": false,
      "sortOrder": 1,
      "createdAt": "2026-02-15T10:00:00.000Z",
      "updatedAt": "2026-02-15T10:00:00.000Z"
    }
  ],
  "dependencies": {
    "predecessors": [
      {
        "workItem": {
          "id": "prev-item-id",
          "title": "Site Survey",
          "status": "completed",
          "startDate": "2026-02-20",
          "endDate": "2026-02-22",
          "actualStartDate": "2026-02-20",
          "actualEndDate": "2026-02-22",
          "durationDays": 2,
          "assignedUser": null,
          "assignedVendor": null,
          "area": null,
          "createdAt": "2026-02-10T10:00:00.000Z",
          "updatedAt": "2026-02-22T10:00:00.000Z"
        },
        "dependencyType": "finish_to_start",
        "leadLagDays": 0
      }
    ],
    "successors": []
  },
  "budgets": [
    {
      "id": "b1",
      "workItemId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "description": "Foundation concrete materials",
      "plannedAmount": 8500.0,
      "confidence": "quote",
      "confidenceMargin": 0.05,
      "budgetCategory": {
        "id": "bc-materials",
        "name": "Materials",
        "description": "Raw materials and building supplies",
        "color": "#3B82F6",
        "sortOrder": 0,
        "createdAt": "2026-02-20T10:00:00.000Z",
        "updatedAt": "2026-02-20T10:00:00.000Z"
      },
      "budgetSource": {
        "id": "bs-1",
        "name": "ABC Bank Mortgage",
        "sourceType": "bank_loan"
      },
      "vendor": {
        "id": "v1",
        "name": "ABC Concrete",
        "trade": { "id": "trade-masonry", "name": "Masonry", "color": "#78716C" }
      },
      "actualCost": 2500.0,
      "actualCostPaid": 2500.0,
      "invoiceCount": 1,
      "createdBy": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "displayName": "Admin User",
        "email": "[email protected]"
      },
      "createdAt": "2026-02-15T10:00:00.000Z",
      "updatedAt": "2026-02-15T10:00:00.000Z"
    }
  ],
  "createdAt": "2026-02-15T10:00:00.000Z",
  "updatedAt": "2026-02-16T08:00:00.000Z"
}

Error responses:

Updates a work item. All fields are optional; only provided fields are updated. The updatedAt timestamp is set automatically.

Auth required: Yes

Path parameters:

Request body (all fields optional, at least one required):

{
  "title": "Updated Foundation Work",
  "description": "Updated description",
  "status": "completed",
  "startDate": "2026-03-01",
  "endDate": "2026-03-20",
  "actualStartDate": "2026-03-02",
  "actualEndDate": "2026-03-18",
  "durationDays": 19,
  "startAfter": null,
  "startBefore": null,
  "assignedUserId": "550e8400-e29b-41d4-a716-446655440000",
  "areaId": "area-kitchen"
}

Notes:

• Nullable fields can be explicitly set to null to clear the value.
• Actual dates auto-population: When status changes, actual dates are auto-populated as follows:
  • not_started -> in_progress: sets actualStartDate to today (if not explicitly provided)
  • in_progress -> completed: sets actualEndDate to today (if not explicitly provided)
  • not_started -> completed: sets actualEndDate to today (if not explicitly provided and not already set), and sets a missing actualStartDate to the resolved actual end date, the actualEndDate the work item has after the call (#2209; before, it was always today, which stored start > end for "Mark done" with a past date)
  • If actualStartDate or actualEndDate is explicitly included in the request body (even as null), the explicit value is used and auto-population is skipped for that field.
  • Backward moves (completed -> in_progress, in_progress -> not_started) keep both actual dates. Actual dates later than today are accepted.

Response (200 OK):

Returns the updated WorkItemDetail object. When the call changed status, actualStartDate or actualEndDate, the body also carries a top-level undo token (contract 11).

Error responses:

Deletes a work item. Cascades to notes, subtasks, budget lines, and dependencies.

Auth required: Yes

Path parameters:

Response (204 No Content): Empty body.

Error responses:

All tag endpoints have been removed in EPIC-18. Tags are replaced by structured Area and Trade dimensions. See ADR-028.

Areas provide hierarchical spatial organization of the construction project. The area list is expected to remain small (fewer than ~100 areas) so no pagination is used. All area endpoints require authentication. Both admin and member roles can perform all area operations.

Returns all areas as a flat list sorted by sort_order ascending, then name ascending. The client builds the tree structure using parentId references.

Auth required: Yes

Query parameters:

Response (200 OK):

{
  "areas": [
    {
      "id": "area-ground",
      "name": "Ground Floor",
      "parentId": null,
      "color": "#3B82F6",
      "description": "Main living level",
      "sortOrder": 0,
      "createdAt": "2026-03-19T10:00:00.000Z",
      "updatedAt": "2026-03-19T10:00:00.000Z"
    },
    {
      "id": "area-kitchen",
      "name": "Kitchen",
      "parentId": "area-ground",
      "color": "#F59E0B",
      "description": null,
      "sortOrder": 0,
      "createdAt": "2026-03-19T10:00:00.000Z",
      "updatedAt": "2026-03-19T10:00:00.000Z"
    }
  ]
}

Response type:

interface AreaResponse {
  id: string;
  name: string;
  parentId: string | null;
  color: string | null;
  description: string | null;
  sortOrder: number;
  createdAt: string;
  updatedAt: string;
}

Error responses:

Returns a single area.

Auth required: Yes

Path parameters:

Response (200 OK):

{
  "area": {
    "id": "area-kitchen",
    "name": "Kitchen",
    "parentId": "area-ground",
    "color": "#F59E0B",
    "description": null,
    "sortOrder": 0,
    "createdAt": "2026-03-19T10:00:00.000Z",
    "updatedAt": "2026-03-19T10:00:00.000Z"
  }
}

Error responses:

Creates a new area.

Auth required: Yes

Request body:

{
  "name": "Kitchen",
  "parentId": "area-ground",
  "color": "#F59E0B",
  "description": "Main kitchen area",
  "sortOrder": 0
}

Response (201 Created):

{
  "area": {
    "id": "area-kitchen",
    "name": "Kitchen",
    "parentId": "area-ground",
    "color": "#F59E0B",
    "description": "Main kitchen area",
    "sortOrder": 0,
    "createdAt": "2026-03-19T10:00:00.000Z",
    "updatedAt": "2026-03-19T10:00:00.000Z"
  }
}

Error responses:

Updates an area. All fields are optional; only provided fields are updated.

Auth required: Yes

Path parameters:

Request body (at least one field required):

{
  "name": "Updated Kitchen",
  "color": "#FFAA00"
}

Response (200 OK):

{
  "area": {
    "id": "area-kitchen",
    "name": "Updated Kitchen",
    "parentId": "area-ground",
    "color": "#FFAA00",
    "description": "Main kitchen area",
    "sortOrder": 0,
    "createdAt": "2026-03-19T10:00:00.000Z",
    "updatedAt": "2026-03-19T11:00:00.000Z"
  }
}

Error responses:

Deletes an area. Fails with 409 Conflict if the area or any of its descendant areas are referenced by work items or household items.

Auth required: Yes

Path parameters:

Response (204 No Content): Empty body.

Error responses:

Notes:

• AREA_IN_USE: details is not sent: the error is raised with suppressDetails (#315 hardening), so its counts reach only the server log and the response carries code and message alone. Server-side counts (log only): workItemCount, householdItemCount.
• Deletion cascades to all descendant areas (via ON DELETE CASCADE on parent_id), but only if the entire subtree has no item references.

Trades provide flat craft/skill classification. Trades are assigned to vendors and transitively to work items via vendor assignment. The trade list is expected to remain small (fewer than ~50 trades) so no pagination is used. All trade endpoints require authentication. Both admin and member roles can perform all trade operations.

Returns all trades sorted by sort_order ascending, then name ascending. Each item carries vendorCount (#2213), the number of companies whose trade_id is this trade; the Trades sheet shows it ("‹n› companies"), states it in the Merge dialog ("‹n› companies move to ‹kept trade›") and uses it to show Delete as blocked before the user confirms. Clients that display trades A–Z by their translated name sort client-side.

Auth required: Yes

Query parameters:

Response (200 OK):

{
  "trades": [
    {
      "id": "trade-plumbing",
      "name": "Plumbing",
      "color": "#0EA5E9",
      "description": "Water supply, drainage, gas piping",
      "translationKey": "trades.plumbing",
      "sortOrder": 0,
      "createdAt": "2026-03-19T10:00:00.000Z",
      "updatedAt": "2026-03-19T10:00:00.000Z",
      "vendorCount": 3
    }
  ]
}

Response type:

interface TradeResponse {
  id: string;
  name: string;
  color: string | null;
  description: string | null;
  translationKey: string | null; // built-in trades only; the client shows t(translationKey) with `name` as fallback
  sortOrder: number;
  createdAt: string;
  updatedAt: string;
}

// GET /api/trades items (#2213)
interface TradeListItem extends TradeResponse {
  vendorCount: number;
}

interface TradeListResponse {
  trades: TradeListItem[];
}

color, description and sortOrder stay in the data and the API, but since #2213 no view renders the colour or description and no screen edits the three (Architecture › Areas & Trades).

Error responses:

Returns a single trade.

Auth required: Yes

Path parameters:

Response (200 OK):

{
  "trade": {
    "id": "trade-plumbing",
    "name": "Plumbing",
    "color": "#0EA5E9",
    "description": "Water supply, drainage, gas piping",
    "sortOrder": 0,
    "createdAt": "2026-03-19T10:00:00.000Z",
    "updatedAt": "2026-03-19T10:00:00.000Z"
  }
}

Error responses:

Creates a new trade.

Auth required: Yes

Request body:

{
  "name": "Custom Trade",
  "color": "#FF5733",
  "description": "Description of the trade",
  "sortOrder": 15
}

Response (201 Created):

{
  "trade": {
    "id": "trade-uuid",
    "name": "Custom Trade",
    "color": "#FF5733",
    "description": "Description of the trade",
    "sortOrder": 15,
    "createdAt": "2026-03-19T10:00:00.000Z",
    "updatedAt": "2026-03-19T10:00:00.000Z"
  }
}

Error responses:

Updates a trade. All fields are optional; only provided fields are updated.

Auth required: Yes

Path parameters:

Request body (at least one field required):

{
  "name": "Updated Trade Name",
  "color": "#FFAA00"
}

Renaming a built-in trade (#2213). When name is given and its trimmed value differs from the stored name (case-sensitive), the server also sets translation_key to NULL, in the same UPDATE. Without it the client keeps showing t(translationKey) and the rename has no visible effect in any locale. The new name then shows as typed in every locale. A name equal to the stored one keeps the key. The same rule applies to PATCH /api/budget-categories/:id and PATCH /api/household-item-categories/:id.

Response (200 OK):

{
  "trade": {
    "id": "trade-plumbing",
    "name": "Updated Trade Name",
    "color": "#FFAA00",
    "description": "Water supply, drainage, gas piping",
    "sortOrder": 0,
    "createdAt": "2026-03-19T10:00:00.000Z",
    "updatedAt": "2026-03-19T11:00:00.000Z"
  }
}

Error responses:

Deletes a trade. Fails with 409 Conflict if the trade is referenced by any vendors.

Auth required: Yes

Path parameters:

Response (204 No Content): Empty body.

Error responses:

Notes:

• TRADE_IN_USE: details is not sent: the error is raised with suppressDetails (#315 hardening), so its counts reach only the server log and the response carries code and message alone. Server-side counts (log only): vendorCount.
• Trades with no vendor references can be freely deleted.
• The Trades sheet shows Delete as blocked up front from the list's vendorCount; the 409 above stays the authority (another user may have assigned the trade since the list loaded). Trades have no GET /api/delete-impact entry (EPIC-21 contract 19): a delete that succeeds affects nothing else.

Merges the trade :id (the duplicate) into targetTradeId (the trade to keep), #2213: every company whose trade_id is :id gets targetTradeId, then :id is deleted. Nothing else references trades (vendors.trade_id is the only foreign key), so no data is lost. Not undoable (no snapshot, no undo token); the confirm dialog states the consequence with the duplicate's vendorCount.

Auth required: Yes (member or admin)

Path parameters:

Request body:

{ "targetTradeId": "trade-electrical" }

Behaviour. One transaction:

1. :id must exist (404), targetTradeId must exist and differ from :id (400).
2. UPDATE vendors SET trade_id = :targetTradeId, updated_at = :now WHERE trade_id = :id (the moved companies' updated_at changes, like any edit of their trade).
3. DELETE FROM trades WHERE id = :id.

The kept trade's name, translationKey, color, description and sortOrder are unchanged.

Response (200 OK):

{
  "trade": {
    "id": "trade-electrical",
    "name": "Electrical",
    "color": null,
    "description": null,
    "translationKey": "trades.electrical",
    "sortOrder": 1,
    "createdAt": "2026-03-19T10:00:00.000Z",
    "updatedAt": "2026-03-19T10:00:00.000Z",
    "vendorCount": 5
  },
  "movedVendorCount": 2
}

interface TradeMergeRequest {
  targetTradeId: string;
}

interface TradeMergeResponse {
  trade: TradeListItem; // the kept trade, vendorCount after the merge
  movedVendorCount: number; // companies moved from :id (0 is valid)
}

Error responses:

A missing target is 400, not 404, matching how other bodies treat an unknown referenced id (e.g. tradeId on POST /api/vendors). A second merge of the same :id (double submit) returns 404.

Notes are nested under work items. All note endpoints require the parent work item to exist.

Returns all notes for a work item, sorted by created_at descending (newest first).

Auth required: Yes

Path parameters:

Response (200 OK):

{
  "notes": [
    {
      "id": "n1",
      "content": "Foundation concrete has cured successfully.",
      "createdBy": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "displayName": "Admin User"
      },
      "createdAt": "2026-02-16T14:00:00.000Z",
      "updatedAt": "2026-02-16T14:00:00.000Z"
    }
  ]
}

The createdBy object contains id and displayName only (not the full user response). If the creating user has been deleted (SET NULL), createdBy is null.

Error responses:

Adds a note to a work item. The createdBy is automatically set to the authenticated user.

Auth required: Yes

Path parameters:

Request body:

{
  "content": "Foundation concrete has cured successfully."
}

Response (201 Created):

{
  "id": "n1",
  "content": "Foundation concrete has cured successfully.",
  "createdBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "displayName": "Admin User"
  },
  "createdAt": "2026-02-16T14:00:00.000Z",
  "updatedAt": "2026-02-16T14:00:00.000Z"
}

Error responses:

Updates a note's content. Only the note's author or an admin can edit a note.

Auth required: Yes

Path parameters:

Request body:

{
  "content": "Updated note content."
}

Response (200 OK): Returns the updated note object.

Error responses:

Deletes a note. Only the note's author or an admin can delete a note.

Auth required: Yes

Path parameters:

Response (204 No Content): Empty body.

Error responses:

Subtasks are nested under work items. All subtask endpoints require the parent work item to exist.

Returns all subtasks for a work item, sorted by sort_order ascending.

Auth required: Yes

Path parameters:

Response (200 OK):

{
  "subtasks": [
    {
      "id": "s1",
      "title": "Excavate site",
      "isCompleted": true,
      "sortOrder": 0,
      "createdAt": "2026-02-15T10:00:00.000Z",
      "updatedAt": "2026-02-16T08:00:00.000Z"
    },
    {
      "id": "s2",
      "title": "Pour concrete",
      "isCompleted": false,
      "sortOrder": 1,
      "createdAt": "2026-02-15T10:00:00.000Z",
      "updatedAt": "2026-02-15T10:00:00.000Z"
    }
  ]
}

Error responses:

Adds a subtask to a work item. If sortOrder is not provided, the subtask is appended to the end (max sort_order + 1).

Auth required: Yes

Path parameters:

Request body:

{
  "title": "Excavate site",
  "sortOrder": 0
}

Response (201 Created):

{
  "id": "s1",
  "title": "Excavate site",
  "isCompleted": false,
  "sortOrder": 0,
  "createdAt": "2026-02-15T10:00:00.000Z",
  "updatedAt": "2026-02-15T10:00:00.000Z"
}

Error responses:

Updates a subtask's title, completion status, and/or sort order.

Auth required: Yes

Path parameters:

Request body (at least one field required):

{
  "title": "Updated subtask title",
  "isCompleted": true,
  "sortOrder": 2
}

Response (200 OK): Returns the updated subtask object.

Error responses:

Deletes a subtask.

Auth required: Yes

Path parameters:

Response (204 No Content): Empty body.

Error responses:

Bulk reorders all subtasks for a work item. Accepts an ordered array of subtask IDs and updates the sort_order of each subtask to match the array index.

Auth required: Yes

Path parameters:

Request body:

{
  "subtaskIds": ["s2", "s1", "s3"]
}

Each subtask's sort_order is set to its index in the array (0-indexed). All subtask updatedAt timestamps are updated.

Response (200 OK):

{
  "subtasks": [
    {
      "id": "s2",
      "title": "Pour concrete",
      "isCompleted": false,
      "sortOrder": 0,
      "createdAt": "...",
      "updatedAt": "..."
    },
    {
      "id": "s1",
      "title": "Excavate site",
      "isCompleted": true,
      "sortOrder": 1,
      "createdAt": "...",
      "updatedAt": "..."
    },
    {
      "id": "s3",
      "title": "Inspect foundation",
      "isCompleted": false,
      "sortOrder": 2,
      "createdAt": "...",
      "updatedAt": "..."
    }
  ]
}

Error responses:

Dependencies define predecessor/successor relationships between work items for scheduling.

Returns both predecessors and successors for a work item.

Auth required: Yes

Path parameters:

Response (200 OK):

{
  "predecessors": [
    {
      "workItem": {
        "id": "prev-item-id",
        "title": "Site Survey",
        "status": "completed",
        "startDate": "2026-02-20",
        "endDate": "2026-02-22",
        "actualStartDate": "2026-02-20",
        "actualEndDate": "2026-02-22",
        "durationDays": 2,
        "assignedUser": null,
        "assignedVendor": null,
        "area": null,
        "createdAt": "2026-02-10T10:00:00.000Z",
        "updatedAt": "2026-02-22T10:00:00.000Z"
      },
      "dependencyType": "finish_to_start",
      "leadLagDays": 0
    }
  ],
  "successors": [
    {
      "workItem": {
        "id": "next-item-id",
        "title": "Framing",
        "status": "not_started",
        "startDate": null,
        "endDate": null,
        "actualStartDate": null,
        "actualEndDate": null,
        "durationDays": null,
        "assignedUser": null,
        "assignedVendor": null,
        "area": null,
        "createdAt": "2026-02-10T10:00:00.000Z",
        "updatedAt": "2026-02-10T10:00:00.000Z"
      },
      "dependencyType": "finish_to_start",
      "leadLagDays": 0
    }
  ]
}

Error responses:

Adds a dependency to a work item. The work item identified by :id becomes the successor (it depends on predecessorId).

Auth required: Yes

Path parameters:

Request body:

{
  "predecessorId": "prev-item-id",
  "dependencyType": "finish_to_start",
  "leadLagDays": 3
}

Circular dependency detection: Before creating the dependency, the server performs a depth-first traversal of the dependency graph starting from the predecessor, following the successor direction. If the traversal reaches the current work item (:id), a cycle would be created and the request is rejected.

Response (201 Created):

{
  "predecessorId": "prev-item-id",
  "successorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "dependencyType": "finish_to_start",
  "leadLagDays": 3
}

Error responses:

Updates a dependency's properties (dependency type and/or lead/lag days).

Auth required: Yes

Path parameters:

Request body (at least one field required):

{
  "dependencyType": "start_to_start",
  "leadLagDays": -2
}

Response (200 OK):

{
  "predecessorId": "prev-item-id",
  "successorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "dependencyType": "start_to_start",
  "leadLagDays": -2
}

Error responses:

Removes a dependency from a work item.

Auth required: Yes

Path parameters:

Response (204 No Content): Empty body.

Error responses:

Budget lines are nested under work items. Each budget line represents a cost estimate or allocation with its own confidence level, optional vendor, budget category, and budget source. All budget line endpoints require the parent work item to exist. Budget lines are NOT paginated (a work item typically has fewer than ~20 budget lines).

Returns all budget lines for a work item.

Auth required: Yes

Path parameters:

Response (200 OK):

{
  "budgets": [
    {
      "id": "b1",
      "workItemId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "description": "Foundation concrete materials",
      "plannedAmount": 8500.0,
      "confidence": "quote",
      "confidenceMargin": 0.05,
      "budgetCategory": {
        "id": "bc-materials",
        "name": "Materials",
        "description": "Raw materials and building supplies",
        "color": "#3B82F6",
        "sortOrder": 0,
        "createdAt": "2026-02-20T10:00:00.000Z",
        "updatedAt": "2026-02-20T10:00:00.000Z"
      },
      "budgetSource": {
        "id": "bs-1",
        "name": "ABC Bank Mortgage",
        "sourceType": "bank_loan"
      },
      "vendor": {
        "id": "v1",
        "name": "ABC Concrete",
        "trade": { "id": "trade-masonry", "name": "Masonry", "color": "#78716C" }
      },
      "actualCost": 2500.0,
      "actualCostPaid": 2500.0,
      "invoiceCount": 1,
      "createdBy": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "displayName": "Admin User",
        "email": "[email protected]"
      },
      "createdAt": "2026-02-15T10:00:00.000Z",
      "updatedAt": "2026-02-15T10:00:00.000Z"
    }
  ]
}

Error responses:

Creates a new budget line for a work item. The createdBy is automatically set to the authenticated user.

Auth required: Yes

Path parameters:

Request body:

{
  "description": "Foundation concrete materials",
  "plannedAmount": 8500.0,
  "confidence": "quote",
  "budgetCategoryId": "bc-materials",
  "budgetSourceId": "bs-1",
  "vendorId": "v1"
}

Response (201 Created):

{
  "budget": {
    "id": "b1",
    "workItemId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "description": "Foundation concrete materials",
    "plannedAmount": 8500.0,
    "confidence": "quote",
    "confidenceMargin": 0.05,
    "budgetCategory": {
      "id": "bc-materials",
      "name": "Materials",
      "description": "Raw materials and building supplies",
      "color": "#3B82F6",
      "sortOrder": 0,
      "createdAt": "2026-02-20T10:00:00.000Z",
      "updatedAt": "2026-02-20T10:00:00.000Z"
    },
    "budgetSource": {
      "id": "bs-1",
      "name": "ABC Bank Mortgage",
      "sourceType": "bank_loan"
    },
    "vendor": {
      "id": "v1",
      "name": "ABC Concrete",
      "trade": { "id": "trade-masonry", "name": "Masonry", "color": "#78716C" }
    },
    "actualCost": 0,
    "actualCostPaid": 0,
    "invoiceCount": 0,
    "createdBy": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "displayName": "Admin User",
      "email": "[email protected]"
    },
    "createdAt": "2026-02-20T14:00:00.000Z",
    "updatedAt": "2026-02-20T14:00:00.000Z"
  }
}

Error responses:

Updates a budget line. All fields are optional; only provided fields are updated. The updatedAt timestamp is set automatically. This endpoint supports same-table moves only (move within work items) — to move a budget line to a household item, use PATCH /api/invoices/:invoiceId/budget-lines/:id instead.

Auth required: Yes

Path parameters:

Request body (all fields optional, at least one required):

{
  "description": "Updated description",
  "plannedAmount": 9000.0,
  "confidence": "invoice",
  "budgetCategoryId": "bc-materials",
  "budgetSourceId": null,
  "vendorId": "v1"
}

Response (200 OK):

Returns the updated WorkItemBudgetLine object wrapped in { "budget": ... }.

Error responses:

Notes:

• Cross-table moves (work item to household item or vice versa) are not supported by this endpoint. Use PATCH /api/invoices/:invoiceId/budget-lines/:id to move budget lines between work items and household items.

Deletes a budget line. Fails with 409 Conflict if the budget line has invoices linked to it.

Auth required: Yes

Path parameters:

Response (204 No Content): Empty body.

Error responses:

Notes:

• BUDGET_LINE_IN_USE: details is not sent: the error is raised with suppressDetails (#315 hardening), so its counts reach only the server log and the response carries code and message alone. Server-side counts (log only): invoiceCount.
• Budget lines with no linked invoices can be freely deleted.
• The budget line must belong to the specified work item. If the budget line exists but belongs to a different work item, a 404 is returned.

Calculates the expected subsidy payback range for a specific work item. Returns the total min/max payback amounts and a per-subsidy breakdown. Only non-rejected subsidies linked to the work item are included.

Auth required: Yes

Path parameters:

Response (200 OK):

{
  "workItemId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "minTotalPayback": 8500.0,
  "maxTotalPayback": 12500.0,
  "subsidies": [
    {
      "subsidyProgramId": "sp-001",
      "name": "Energy Efficiency Grant",
      "reductionType": "percentage",
      "reductionValue": 15,
      "minPayback": 6000.0,
      "maxPayback": 10000.0
    },
    {
      "subsidyProgramId": "sp-002",
      "name": "Regional Housing Support",
      "reductionType": "fixed",
      "reductionValue": 2500,
      "minPayback": 2500.0,
      "maxPayback": 2500.0
    }
  ]
}

Response type definitions:

interface WorkItemSubsidyPaybackResponse {
  workItemId: string;
  /** Minimum total payback across all non-rejected linked subsidies. */
  minTotalPayback: number;
  /** Maximum total payback across all non-rejected linked subsidies. */
  maxTotalPayback: number;
  /** Per-subsidy breakdown. Empty array when no subsidies are linked. */
  subsidies: WorkItemSubsidyPaybackEntry[];
}

interface WorkItemSubsidyPaybackEntry {
  subsidyProgramId: string;
  name: string;
  reductionType: 'percentage' | 'fixed';
  reductionValue: number;
  /** Minimum expected payback (lower bound based on confidence margins). */
  minPayback: number;
  /** Maximum expected payback (upper bound based on confidence margins). */
  maxPayback: number;
}

Error responses:

Notes:

• For percentage subsidies, the payback for each matching budget line is computed as: lineAmount * (reductionValue / 100). The min/max range reflects confidence margins on non-invoiced budget lines. For invoiced lines, the actual cost is used (minPayback === maxPayback for that line).
• lineAmount for a non-invoiced line is the VAT-effective planned amount: a net line (includesVat: false) is grossed up by 1 + VAT_RATE (server config vatRate, default 0.19, exposed by GET /api/config) and rounded to cents before the confidence margin and the subsidy percentage apply; a gross line is used as stored. This matches GET /api/budget/overview (subsidySummary) and GET /api/budget/breakdown (subsidyPayback), so the same line yields the same payback on every endpoint.
• For fixed subsidies, the payback is the fixed amount regardless of budget line values: minPayback === maxPayback === reductionValue.
• A subsidy matches a budget line if: (a) the subsidy is linked to the work item, (b) the subsidy is not rejected, and (c) the subsidy's applicable categories include the budget line's category (or the subsidy has no category restrictions, making it universal).
• When no subsidies are linked to the work item, all totals are 0 and subsidies is an empty array.
• The confidence margin ranges are: own_estimate (plus/minus 20%), professional_estimate (plus/minus 10%), quote (plus/minus 5%), invoice (plus/minus 0%).

Returns all household items that depend on this work item (via household_item_deps). This is the reverse direction of the GET /api/household-items/:id/dependencies endpoint. Not paginated.

Auth required: Yes

Path parameters:

Response (200 OK):

{
  "householdItems": [
    {
      "id": "hi-001",
      "name": "Kitchen Faucet",
      "category": "hic-fixtures",
      "status": "ordered",
      "targetDeliveryDate": "2026-05-15",
      "earliestDeliveryDate": "2026-05-10",
      "latestDeliveryDate": "2026-05-20"
    }
  ]
}

Response type definitions:

interface WorkItemDependentHouseholdItemsResponse {
  householdItems: WorkItemLinkedHouseholdItemSummary[];
}

interface WorkItemLinkedHouseholdItemSummary {
  id: string;
  name: string;
  category: HouseholdItemCategory;
  status: HouseholdItemStatus;
  targetDeliveryDate: string | null; // Computed by scheduling engine from constraints & dependencies
  earliestDeliveryDate: string | null; // User-editable constraint
  latestDeliveryDate: string | null; // User-editable constraint
}

Error responses:

Notes:

• Returns an empty array when no household items depend on this work item.
• The response shape is a lightweight summary (no vendor, area, quantity, or budget info). Use GET /api/household-items/:id for full details on a specific household item.

Budget management endpoints for tracking construction costs, vendors, invoices, financing sources, and subsidy programs. All endpoints in this section require authentication. Both admin and member roles can perform all budget operations (no role restriction).

interface BudgetCategoryResponse {
  id: string;
  name: string;
  description: string | null;
  color: string | null;
  sortOrder: number;
  createdAt: string; // ISO 8601
  updatedAt: string; // ISO 8601
}

Budget categories are a small, finite collection (typically 10-20 items). They are NOT paginated.

Returns all budget categories sorted by sort_order ascending, then name ascending (#2215: the name tie-break makes the order deterministic when rows share a sort_order).

Auth required: Yes

Response (200 OK):

{
  "categories": [
    {
      "id": "bc-materials",
      "name": "Materials",
      "description": "Raw materials and building supplies",
      "color": "#3B82F6",
      "sortOrder": 0,
      "createdAt": "2026-02-20T10:00:00.000Z",
      "updatedAt": "2026-02-20T10:00:00.000Z"
    },
    {
      "id": "bc-labor",
      "name": "Labor",
      "description": "Contractor and worker labor costs",
      "color": "#EF4444",
      "sortOrder": 1,
      "createdAt": "2026-02-20T10:00:00.000Z",
      "updatedAt": "2026-02-20T10:00:00.000Z"
    }
  ]
}

Error responses:

Creates a new budget category.

Auth required: Yes

Request body:

{
  "name": "Appliances",
  "description": "Kitchen and household appliances",
  "color": "#F472B6",
  "sortOrder": 10
}

Default position (#2215). When sortOrder is omitted the new category is appended: sort_order = MAX(sort_order) + 1 over the list (0 when the list is empty). Before #2215 the default was 0, which put a new row at the top among the rows sharing 0.

Response (201 Created):

{
  "budgetCategory": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Appliances",
    "description": "Kitchen and household appliances",
    "color": "#F472B6",
    "translationKey": null,
    "sortOrder": 10,
    "createdAt": "2026-02-20T14:00:00.000Z",
    "updatedAt": "2026-02-20T14:00:00.000Z"
  }
}

Error responses:

Saves the whole order of the list in one request (#2215). Body { "ids": string[] } with every id of the list exactly once; 200 OK with { "categories": [...] } in the new order; 409 REORDER_SET_MISMATCH when the ids are not exactly the current set. Full specification: Reference List Reorder.

Returns a single budget category.

Auth required: Yes

Path parameters:

Response (200 OK):

{
  "budgetCategory": {
    "id": "bc-materials",
    "name": "Materials",
    "description": "Raw materials and building supplies",
    "color": "#3B82F6",
    "translationKey": "budgetCategories.materials",
    "sortOrder": 0,
    "createdAt": "2026-02-20T10:00:00.000Z",
    "updatedAt": "2026-02-20T10:00:00.000Z"
  }
}

Error responses:

Updates a budget category's name, description, color, and/or sort order.

Auth required: Yes

Path parameters:

Request body (at least one field required):

{
  "name": "Building Materials",
  "description": "Updated description",
  "color": "#2563EB",
  "sortOrder": 0
}

Renaming a built-in category (#2213). Same rule as PATCH /api/trades/:id: when name is given and its trimmed value differs from the stored name (case-sensitive), the server sets translation_key to NULL in the same UPDATE, so the typed name shows in every locale. A name equal to the stored one keeps the key.

Response (200 OK):

{
  "budgetCategory": {
    "id": "bc-materials",
    "name": "Building Materials",
    "description": "Updated description",
    "color": "#2563EB",
    "translationKey": null,
    "sortOrder": 0,
    "createdAt": "2026-02-20T10:00:00.000Z",
    "updatedAt": "2026-02-20T15:00:00.000Z"
  }
}

Error responses:

Deletes a budget category. Fails with 409 Conflict if the category is referenced by work item budget lines (via work_item_budgets.budget_category_id), by household item budget lines (via household_item_budgets.budget_category_id) or by subsidy programs (via subsidy_program_categories).

Auth required: Yes

Path parameters:

Response (204 No Content): Empty body.

Error responses:

Notes:

• CATEGORY_IN_USE: details is not sent: the error is raised with suppressDetails (#315 hardening), so its counts reach only the server log and the response carries code and message alone. Server-side counts (log only): subsidyProgramCount, budgetLineCount, householdBudgetCount.

Vendor summary (used in list responses):

interface VendorResponse {
  id: string;
  name: string;
  trade: TradeSummary | null;
  phone: string | null;
  email: string | null;
  address: string | null;
  notes: string | null;
  createdBy: UserSummary | null;
  createdAt: string; // ISO 8601
  updatedAt: string; // ISO 8601
}

Vendor detail (used in single-item responses, adds computed fields):

interface VendorDetailResponse extends VendorResponse {
  invoiceCount: number;
  outstandingBalance: number;
}

Notes on computed fields:

• invoiceCount is the total number of invoices for this vendor (all statuses).
• outstandingBalance is ADR-039 "Still to pay": pending invoices minus their non-refund progress payments, plus pending progress payments (also on offers). Paid and claimed (submitted) invoices never count. Uses the same helper as the Invoices page open-payable figure. Returns 0 if nothing is left to pay. (changed in #2194, D-06; previously summed pending + claimed invoice amounts)

Vendors/contractors are a core budget management entity. The vendor list may grow to dozens of entries for a large construction project, so pagination is used. All vendor endpoints require authentication. Both admin and member roles can perform all vendor operations (no role restriction).

Returns a paginated, searchable list of vendors (companies) sorted by name ascending. The Companies list (/companies, story 1.7, #2213) reads it.

Auth required: Yes

Query parameters:

Search (q, #2213). The list uses the same matcher as the vendor group of GET /api/search (EPIC-21 contract 6), with one field list shared by both, so a company the command search finds for a text is also in the list for that text. After trimming, an empty q is no filter. A company matches when fold(q) is a substring of fold() of any of: its name, its trade's stored name, its phone, its e-mail, or the name, phone or e-mail of any of its contact persons. When q holds at least 3 digits, it also matches when digits(q) is a substring of digits() of the company's phone or of any contact person's phone, so a digit run typed without spaces or separators finds a number stored with them. fold/digits are the SQL functions in Architecture › SQL functions (ä/ae, ö/oe, ü/ue, ß/ss and case fold alike); the client does no folding. q filters only; it does not change the sort (no relevance rank, unlike /api/search). The trade text matched is the stored trades.name; translated names are covered by tradeIds.

Trade ids (tradeIds, #2213). The translated display name of a built-in trade (t(translationKey)) exists only in the client, so the server cannot match it. The client therefore folds the typed text with foldSearchText and compares it (substring) with the folded display name of every trade it holds (useTrades), and sends the ids of the trades that match as tradeIds. The server then treats a company as matching q when the text match above holds or vendors.trade_id IN (tradeIds). Rules (shared with GET /api/search, one parser):

• Comma-separated; entries trimmed, empties dropped, duplicates removed. Absent or empty = no trade term.
• At most 50 entries after de-duplication and each 1–64 characters; otherwise 400 VALIDATION_ERROR with details.tradeIds. (Trades are a small list, see Trade Endpoints; 50 bounds the IN (…) list.)
• Ids are bound parameters. Unknown ids are ignored (they match no company); no existence check, no error.
• Only used together with a non-empty q. It widens the text match; it never filters on its own. tradeId stays the filter and still combines with AND, so tradeId=A&q=x&tradeIds=B returns companies of trade A that match x by text (B can't add any, since they are not in A).
• The client sends it whenever at least one trade matches; an English stored name matching twice (text and id) is harmless.

Sort. last_on_site sorts by lastOnSite; companies without one come last in both directions. Every sort breaks ties by name ascending, then id ascending, so paging is stable.

Response (200 OK):

{
  "vendors": [
    {
      "id": "v1",
      "name": "ABC Plumbing",
      "trade": { "id": "trade-plumbing", "name": "Plumbing", "color": "#0EA5E9" },
      "phone": "+1-555-0100",
      "email": "[email protected]",
      "address": "123 Main St, Springfield",
      "notes": "Licensed and insured",
      "firstContactPhone": null,
      "contactCount": 2,
      "lastOnSite": "2026-02-18",
      "createdBy": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "displayName": "Admin User",
        "email": "[email protected]"
      },
      "createdAt": "2026-02-20T10:00:00.000Z",
      "updatedAt": "2026-02-20T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "totalItems": 1,
    "totalPages": 1
  }
}