Requests & Responses Both

This guide covers the request and response conventions shared across TapTidy API endpoints.

Identifiers

All resource identifiers are UUIDs (v4). The API distinguishes between two identity concepts in household contexts:

• userId — the authenticated account. Used for ownership, billing, and session management.
• memberId — the household member performing an action. Used for task assignments, chore rotation, points, and activity attribution.

Adult sessions derive memberId from the member record linked to their userId. Child PIN sessions receive a dedicated memberId directly. When assigning or comparing tasks, always use memberId, never userId.

Household Context

Household-scoped endpoints accept an X-Household-Id header to identify the target household. This header is required when the authenticated user belongs to multiple households. Omitting it when the user has exactly one household causes the API to use that household by default.

Date & Time Formats

The API uses ISO 8601 for all date-time fields:

All-Day Tasks

Tasks have a dueDate (UTC timestamp) and a dueDateHasTime boolean. When dueDateHasTime is false, the task is an all-day item — display the dueDateRaw field (YYYY-MM-DD) as the local date without timezone conversion. This avoids date shifts when users change time zones.

Timezones

Each user has a stored timezone preference (IANA identifier, e.g. America/New_York). The server resolves this from the user's settings, falling back to UTC. Date range queries on the user's local calendar are converted to UTC windows server-side using date-fns-tz.

Concurrency & Conflict Resolution

The API provides several concurrency mechanisms:

• Idempotency keys — send Idempotency-Key: <UUID> on POST/PUT/PATCH/DELETE to /tasks, /projects, or /tags. Duplicate requests replay the original response.
• Optimistic versioning — household settings mutations accept baseVersion. A stale version returns 409 Conflict. Omitting baseVersion defaults to last-write-wins.
• CalDAV ETags — the CalDAV server returns ETag headers for conditional If-Match updates.
• Sync sequence numbers — the change log uses monotonic seq values and per-change idempotencyKey UUIDs for deterministic replay.

Response Envelope

Successful responses return the resource or resource list directly. Error responses use a standard envelope:

{
  "code": "VALIDATION_ERROR",
  "message": "Human-readable explanation",
  "requestId": "req-abc123"
}

Some errors include a reason field for finer-grained classification (e.g. insufficient_scope) and a details object with field-level validation errors. See API Errors for the full error code reference.

Request Validation

All request bodies are validated against Zod schemas before reaching the handler. Invalid payloads return 400 with VALIDATION_ERROR and a details array describing each field failure.