> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcnaid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HouseholdOS HTTP route inventory

> Implemented HouseholdOS HTTP routes in the reviewed source snapshot.

# HouseholdOS HTTP route inventory

This is an implementation inventory, not a promise of a stable public API. The reviewed source contains no OpenAPI document, API version prefix, or external-consumer SDK. Request and response examples are omitted except for the source-verified public health check. Most routes below belong to the application service; the final contact route belongs to the separate marketing site.

## Authentication

On the application origin, `GET /api/health` is public and `GET /api/health/db` uses separate readiness authorization. The read-only calendar subscription at `GET /api/integrations/calendar/feed/:secret.ics` also does not require an application session: its unguessable URL is the access credential. Anyone with the complete URL can read the feed, so keep it private and regenerate it if it is exposed. All other `/api/*` routes first authenticate the caller; household routes then apply membership and permission checks where relevant. Browser mutations with a cross-origin `Origin` are rejected unless the origin is allowed by application configuration.

The primary browser flow uses the same-origin session established by `/auth/login` and `/auth/callback`. Supported non-browser credentials are validated before route dispatch.

## Public health check

```bash theme={null}
curl https://app.householdos.pndsvcs.com/api/health
```

The implemented response is `{"status":"ok"}`.

## API routes

| Method | Path | Implemented purpose |
| - | - | - |
| `GET` | `/api/health` | Process health |
| `GET` | `/api/health/db` | Credential-gated database readiness |
| `GET` | `/api/admin/diagnostics` | Platform-admin runtime diagnostics |
| `GET` | `/api/me` | Current authenticated application user |
| `GET` | `/api/households` | Active households for the caller |
| `POST` | `/api/households` | Create a household and owner membership |
| `PATCH` | `/api/households/:householdId` | Update an authorized household profile |
| `GET` | `/api/households/:householdId/members` | List active members |
| `POST` | `/api/households/:householdId/members` | Bootstrap the members collection |
| `PATCH` | `/api/households/:householdId/members/:userId` | Update a member role or custom permissions |
| `DELETE` | `/api/households/:householdId/members/:userId` | Deactivate a membership |
| `POST` | `/api/households/:householdId/bootstrap` | Save initial members, chore templates, and rewards |
| `POST` | `/api/invitations` | Create a household invitation |
| `GET` | `/api/invitations/preview?token=...` | Preview an invitation for the signed-in caller |
| `POST` | `/api/invitations/:token/redeem` | Accept an invitation |
| `POST` | `/api/invitations/:invitationId/revoke` | Revoke an invitation |
| `GET` | `/api/notifications?limit=...` | List the caller's notifications |
| `POST` | `/api/notifications/:notificationId/read` | Mark one notification read |
| `POST` | `/api/notifications/mark-all-read` | Mark all of the caller's notifications read |
| `POST` | `/api/notifications/:notificationId/clear` | Clear a single notification |
| `POST` | `/api/notifications/clear-all?householdId=...` | Clear all of the caller's notifications |
| `GET` | `/api/search?q=...&householdId=...` | Search readable household collections |
| `POST` | `/api/analytics/capture` | Queue a server-side analytics event |
| `POST` | `/api/notifications/email` | Send email through the configured provider |
| `POST` | `/api/notifications/sms` | Send SMS through the configured provider |
| `POST` | `/api/ai/respond` | Create an AI response through the configured provider or fallback |
| `GET` | `/api/account/authentication-methods` | List the caller's identity-provider authentication methods |
| `POST` | `/api/account/authentication-methods` | Start authentication-method enrollment |
| `POST` | `/api/account/authentication-methods/:methodId/verify` | Verify an enrollment |
| `DELETE` | `/api/account/authentication-methods/:methodId` | Remove an authentication method |
| `GET` | `/api/kv?householdId=...` | List readable KV keys (optional prefix filter) |
| `GET` | `/api/kv/export?householdId=...` | Export readable KV records |
| `POST` | `/api/kv/import?householdId=...` | Import writable KV records |
| `GET` | `/api/kv/:key` | Read an authorized household or user key |
| `PUT` | `/api/kv/:key` | Create or replace an authorized key |
| `DELETE` | `/api/kv/:key` | Delete an authorized key |
| `POST` | `/api/files?purpose=...&filename=...&householdId=...` | Upload a permitted file |
| `GET` | `/api/files/:objectKey` | Download an authorized file |
| `GET` | `/api/integrations/ical?householdId=...` | Export readable household events as iCalendar |
| `GET` | `/api/integrations/calendar` | List calendar integrations |
| `POST` | `/api/integrations/calendar/google/sync` | Trigger Google Calendar push sync |
| `DELETE` | `/api/integrations/calendar/google` | Disconnect Google Calendar integration |
| `POST` | `/api/integrations/calendar/apple-feed` | Create or regenerate Apple Calendar ICS feed |
| `DELETE` | `/api/integrations/calendar/apple-feed` | Disconnect Apple Calendar integration |
| `GET` | `/api/integrations/calendar/feed/:secret.ics` | Public read-only ICS feed (bearer-secret URL; no session required) |
| `GET` | `/api/integrations/stripe/financial-connections?householdId=...` | List linked bank accounts with metadata and balances |
| `POST` | `/api/integrations/stripe/financial-connections` | Create a Financial Connections session |
| `POST` | `/api/integrations/stripe/financial-connections/complete` | Complete session and link bank accounts |
| `GET` | `/api/integrations/stripe/financial-connections/accounts/:fcaId/transactions?householdId=...&limit=...` | Page imported bank transactions |

## Marketing Pages Function

| Method | Origin and path | Implemented purpose |
| - | - | - |
| `POST` | `householdos.pndsvcs.com/api/contact` | Validate a marketing contact submission and optionally notify the team |

The form sends name, email, topic, and message fields. `Partnerships` is one of the implemented topic choices. The function returns a service-unavailable response if it can neither persist nor email a valid submission.

## Browser authentication and webhook routes

| Route | Implemented purpose |
| - | - |
| `/auth/login` | Begin Auth0 OIDC authorization with PKCE |
| `/auth/step-up` | Re-authenticate an existing user for account-security management when configured |
| `/auth/callback` | Validate the OIDC transaction and establish the session |
| `/auth/logout` | Clear the application session and complete identity-provider logout when configured |
| `POST /webhooks/resend` | Verify and process signed Resend delivery events |
| `POST /webhooks/stripe-financial-connections` | Verify and process Stripe Financial Connections webhook events |

> [!WARNING]
>
> Do not infer endpoints by analogy. For example, the implemented upload path is `/api/files`; this source snapshot contains no `/api/uploads` route.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.