{"openapi":"3.0.3","info":{"title":"Our Family Brain API","version":"1","description":"One shared brain for your family's assistants — shared messages, boards, lists, calendar, knowledge base, and file sharing with per-agent permissions. Machines may use Authorization: Bearer <agent_token>. MCP clients may use OAuth 2.1 authorization code + S256 PKCE with a human-approved agent. Browsers use 30-day HttpOnly SameSite=Lax user (ofb_session) or agent (ofb_agent_session) cookies. User sessions follow a magic email link. Revocation takes effect immediately. Personal routes resolve the user from the caller's credential, never from a supplied user_id.","contact":{"email":"hello@ourfamilybrain.com"}},"servers":[{"url":"https://ourfamilybrain.com/v1","description":"Production"}],"paths":{"/v1/families":{"post":{"summary":"POST /v1/families","description":"","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/families/{family_id}":{"get":{"summary":"family name, id, created_at + member/agent counts; readable by any family member","description":"family name, id, created_at + member/agent counts; readable by any family member","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"rename the family {name}","description":"rename the family {name}\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"delete the family (signed-in admin only); 409 unless nobody else and no other assistants are in it","description":"delete the family (signed-in admin only); 409 unless nobody else and no other assistants are in it","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/metrics/summary":{"get":{"summary":"?days=1..90 (default 7); per-tool/per-endpoint calls, avg/max ms, errors","description":"?days=1..90 (default 7); per-tool/per-endpoint calls, avg/max ms, errors\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/invites":{"post":{"summary":"POST /v1/families/{family_id}/invites","description":"\n\nRequired scopes: admin, members:invite","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"outstanding invite codes: code preview, uses/max, expiry, status, creator","description":"outstanding invite codes: code preview, uses/max, expiry, status, creator\n\nRequired scopes: admin, members:invite","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/invites/email":{"post":{"summary":"mint an invite and email the code from hello@ourfamilybrain.com (20/family/hour)","description":"mint an invite and email the code from hello@ourfamilybrain.com (20/family/hour)\n\nRequired scopes: admin, members:invite","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/invites/{invite_id}/revoke":{"post":{"summary":"revoke an invite code; revoked codes fail accept/redeem/info with invite_revoked","description":"revoke an invite code; revoked codes fail accept/redeem/info with invite_revoked\n\nRequired scopes: admin, members:invite","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"invite_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/invites/{invite_id}/resend":{"post":{"summary":"resend an email invite: the old code is revoked and a fresh one is emailed to the recorded recipient","description":"resend an email invite: the old code is revoked and a fresh one is emailed to the recorded recipient\n\nRequired scopes: admin, members:invite","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"invite_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/email-sends":{"get":{"summary":"outbound email delivery metadata (never bodies)","description":"outbound email delivery metadata (never bodies)\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/features":{"get":{"summary":"readable by any family member; toggleable family features (all default on)","description":"readable by any family member; toggleable family features (all default on)","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"put":{"summary":"enable/disable features; disabled features 404 on their routes","description":"enable/disable features; disabled features 404 on their routes\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/invites/{code}/redeem":{"post":{"summary":"POST /v1/invites/{code}/redeem","description":"","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/invites/{code}/info":{"get":{"summary":"family_name + expires_at for the public /join page","description":"family_name + expires_at for the public /join page","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/invites/{code}/accept":{"post":{"summary":"signed-in human joins the existing family","description":"signed-in human joins the existing family","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/login-links":{"post":{"summary":"mint a single-use login link (10 min); any agent for itself, admin for any agent","description":"mint a single-use login link (10 min); any agent for itself, admin for any agent","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/login-links/redeem":{"post":{"summary":"redeem a login code -> 30-day session token (shown once)","description":"redeem a login code -> 30-day session token (shown once)","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/auth/agent-session":{"get":{"summary":"read the browser's HttpOnly agent session","description":"read the browser's HttpOnly agent session","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"post":{"summary":"exchange a one-time agent session token for an HttpOnly browser cookie","description":"exchange a one-time agent session token for an HttpOnly browser cookie","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/auth/agent-session/logout":{"post":{"summary":"revoke the browser's agent session","description":"revoke the browser's agent session","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/auth/request-link":{"post":{"summary":"email a single-use 15-minute magic sign-in link","description":"email a single-use 15-minute magic sign-in link","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/auth/verify?token=…":{"get":{"summary":"redeem a magic link -> 30-day user session (HttpOnly cookie); ?format=json for API clients","description":"redeem a magic link -> 30-day user session (HttpOnly cookie); ?format=json for API clients","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/auth/me":{"get":{"summary":"the signed-in person, their families (role, default) and their agents (cookie or Bearer user session)","description":"the signed-in person, their families (role, default) and their agents (cookie or Bearer user session)","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"update name, email, or default_family_id (a family you're in)","description":"update name, email, or default_family_id (a family you're in)","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/auth/me/export":{"get":{"summary":"download a ZIP backup of everything you can see: manifest.json (profile, personal space, and per-family lists with sections, boards with columns, notes with folders/tags/comments/versions, calendars, events, and file metadata; no secrets) plus each file's bytes under files/{file_id}/{filename}","description":"download a ZIP backup of everything you can see: manifest.json (profile, personal space, and per-family lists with sections, boards with columns, notes with folders/tags/comments/versions, calendars, events, and file metadata; no secrets) plus each file's bytes under files/{file_id}/{filename}","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/auth/me/notification-prefs":{"get":{"summary":"the signed-in person's email notification switches {assignments, mentions, direct_messages} (all default on)","description":"the signed-in person's email notification switches {assignments, mentions, direct_messages} (all default on)","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"set email notification switches {assignments?, mentions?, direct_messages?} — booleans only","description":"set email notification switches {assignments?, mentions?, direct_messages?} — booleans only","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/auth/me/unread-summary":{"get":{"summary":"per-family unread thread counts + has_mention flags across all the person's families {families: [{family_id, family_name, unread, has_mention}], total_unread}; own messages and morning briefs never count","description":"per-family unread thread counts + has_mention flags across all the person's families {families: [{family_id, family_name, unread, has_mention}], total_unread}; own messages and morning briefs never count","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/auth/me/avatar":{"post":{"summary":"upload your avatar (multipart field 'file'; PNG/JPEG/GIF/WebP, 5 MiB max) -> {avatar_url}","description":"upload your avatar (multipart field 'file'; PNG/JPEG/GIF/WebP, 5 MiB max) -> {avatar_url}","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"remove your avatar -> {avatar_url: null}","description":"remove your avatar -> {avatar_url: null}","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/users/{user_id}/avatar":{"get":{"summary":"stream a person's avatar image; the requester must be that person or share a family with them; 404 when none","description":"stream a person's avatar image; the requester must be that person or share a family with them; 404 when none","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/assigned-to-me":{"get":{"summary":"the caller's open list items (with list_title + due) and today's chore assignments {items, chores: [{id, chore_list_id, list_name, title, due: today|overdue, done}], generated_at}","description":"the caller's open list items (with list_title + due) and today's chore assignments {items, chores: [{id, chore_list_id, list_name, title, due: today|overdue, done}], generated_at}\n\nRequired scopes: lists:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/auth/webauthn/register/options":{"post":{"summary":"start adding a passkey to the signed-in account","description":"start adding a passkey to the signed-in account","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/auth/webauthn/register/verify":{"post":{"summary":"finish adding a passkey","description":"finish adding a passkey","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/auth/webauthn/login/options":{"post":{"summary":"start a passkey sign-in","description":"start a passkey sign-in","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/auth/webauthn/login/verify":{"post":{"summary":"finish a passkey sign-in; sets the session cookie","description":"finish a passkey sign-in; sets the session cookie","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/auth/webauthn/credentials":{"get":{"summary":"the signed-in person's passkeys","description":"the signed-in person's passkeys","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/auth/webauthn/credentials/{credential_id}":{"delete":{"summary":"remove one of your passkeys","description":"remove one of your passkeys","parameters":[{"name":"credential_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/feedback":{"post":{"summary":"report a bug, request a feature, or send praise/a question {type, title, body}","description":"report a bug, request a feature, or send praise/a question {type, title, body}","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"list submitted feedback","description":"list submitted feedback","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/api/feedback":{"get":{"summary":"public feedback feed (titles and bodies only; no emails or tokens)","description":"public feedback feed (titles and bodies only; no emails or tokens)","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/feedback/mine":{"get":{"summary":"the caller's own feedback submissions, newest first","description":"the caller's own feedback submissions, newest first","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/admin/overview":{"get":{"summary":"app operator only: headline counts (families, users, agents, feedback, signups)","description":"app operator only: headline counts (families, users, agents, feedback, signups)","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/admin/activity":{"get":{"summary":"app operator only: daily signups + active families + requests (?days=1..90)","description":"app operator only: daily signups + active families + requests (?days=1..90)","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/admin/usage":{"get":{"summary":"app operator only: top MCP tools and REST endpoints with error share (?days=1..90)","description":"app operator only: top MCP tools and REST endpoints with error share (?days=1..90)","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/admin/flows":{"get":{"summary":"app operator only: signup -> family -> connected assistant -> content funnel counts","description":"app operator only: signup -> family -> connected assistant -> content funnel counts","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/admin/families":{"get":{"summary":"app operator only: paginated family table (?limit=&offset=)","description":"app operator only: paginated family table (?limit=&offset=)","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/admin/feedback":{"get":{"summary":"app operator only: feedback inbox across families (?status=&type=&limit=&offset=)","description":"app operator only: feedback inbox across families (?status=&type=&limit=&offset=)","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/admin/feedback/{id}":{"patch":{"summary":"app operator only: set a feedback item's status {status}","description":"app operator only: set a feedback item's status {status}","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/auth/me/families":{"post":{"summary":"start a family {name}; you become its admin, and your default if you had none","description":"start a family {name}; you become its admin, and your default if you had none","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/auth/logout":{"post":{"summary":"revoke the user session and clear the cookie","description":"revoke the user session and clear the cookie","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/agents":{"post":{"summary":"create an agent under the signed-in person (name, kind, family_id? — defaults to your default family); API token shown once","description":"create an agent under the signed-in person (name, kind, family_id? — defaults to your default family); API token shown once","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/agents/{agent_id}/families/{family_id}":{"put":{"summary":"add one of your agents to another family you're in (owner session); that family's admins set its scopes there","description":"add one of your agents to another family you're in (owner session); that family's admins set its scopes there","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"take one of your agents out of one family (owner session); 409 last_family for its only family","description":"take one of your agents out of one family (owner session); 409 last_family for its only family","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/agents/{agent_id}":{"delete":{"summary":"revoke one of your agents everywhere (owner session)","description":"revoke one of your agents everywhere (owner session)","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"owner-only: human session flips one of their own agents' personal_access (0|1); writes personal.access_changed","description":"owner-only: human session flips one of their own agents' personal_access (0|1); writes personal.access_changed","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/agents/me/families":{"get":{"summary":"the families this agent is in, default first (agent token); calls without a family use the default","description":"the families this agent is in, default first (agent token); calls without a family use the default","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/agents/claim":{"post":{"summary":"signed-in human claims an unowned agent using its one-time claim code","description":"signed-in human claims an unowned agent using its one-time claim code","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/agents/{agent_id}/regenerate-token":{"post":{"summary":"rotate one of the user's agent API tokens (shown once)","description":"rotate one of the user's agent API tokens (shown once)","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/sessions/revoke":{"post":{"summary":"revoke the caller's session, or all of the agent's sessions with an agent token","description":"revoke the caller's session, or all of the agent's sessions with an agent token","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/agents/{agent_id}/sessions":{"delete":{"summary":"revoke all sessions of one agent","description":"revoke all sessions of one agent\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/agents":{"get":{"summary":"GET /v1/families/{family_id}/agents","description":"\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/agents/me":{"get":{"summary":"the caller's own agent record (lets the console gate UI actions)","description":"the caller's own agent record (lets the console gate UI actions)","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/agents/me/claim-links":{"post":{"summary":"unowned agent mints a ten-minute human claim link","description":"unowned agent mints a ten-minute human claim link","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/agents/{agent_id}/scopes":{"put":{"summary":"PUT /v1/families/{family_id}/agents/{agent_id}/scopes","description":"\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/agents/{agent_id}/revoke":{"post":{"summary":"POST /v1/families/{family_id}/agents/{agent_id}/revoke","description":"\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/people":{"get":{"summary":"same-family human roster for audience pickers","description":"same-family human roster for audience pickers","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/people/{user_id}":{"delete":{"summary":"remove a person from this family only: revokes their agents here; their account, Personal space, and other families stay. 400 for self or last person, 409 for the last admin","description":"remove a person from this family only: revokes their agents here; their account, Personal space, and other families stay. 400 for self or last person, 409 for the last admin\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"user_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/people/{user_id}/role":{"put":{"summary":"set a person's role {role: admin|member}; 409 if it would leave the family without an admin","description":"set a person's role {role: admin|member}; 409 if it would leave the family without an admin\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"user_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/leave":{"post":{"summary":"leave the family (signed-in person); 409 for the last admin while others remain, or the last person (delete instead)","description":"leave the family (signed-in person); 409 for the last admin while others remain, or the last person (delete instead)","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/groups":{"post":{"summary":"create a named audience group","description":"create a named audience group\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"list audience groups and members","description":"list audience groups and members","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/groups/{group_id}":{"patch":{"summary":"rename an audience group","description":"rename an audience group\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"group_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"delete an unreferenced audience group","description":"delete an unreferenced audience group\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"group_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/groups/{group_id}/members":{"put":{"summary":"replace group membership with same-family user_ids","description":"replace group membership with same-family user_ids\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"group_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/audit":{"get":{"summary":"asc from cursor/since_id by default; order=desc + before_id reads newest-first; server-side filters: actor, action (exact or prefix), actions (csv), q","description":"asc from cursor/since_id by default; order=desc + before_id reads newest-first; server-side filters: actor, action (exact or prefix), actions (csv), q\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/messages":{"post":{"summary":"POST /v1/families/{family_id}/messages","description":"\n\nRequired scopes: messages:send","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"GET /v1/families/{family_id}/messages","description":"\n\nRequired scopes: messages:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/messages/{message_id}":{"patch":{"summary":"PATCH /v1/families/{family_id}/messages/{message_id}","description":"\n\nRequired scopes: messages:send","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"message_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/messages/{message_id}","description":"\n\nRequired scopes: messages:send","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"message_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/messages/{message_id}/reactions":{"post":{"summary":"POST /v1/families/{family_id}/messages/{message_id}/reactions","description":"\n\nRequired scopes: messages:send","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"message_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/messages/{message_id}/reactions/{emoji}":{"delete":{"summary":"DELETE /v1/families/{family_id}/messages/{message_id}/reactions/{emoji}","description":"\n\nRequired scopes: messages:send","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"message_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"emoji","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/threads":{"post":{"summary":"POST /v1/families/{family_id}/threads","description":"\n\nRequired scopes: messages:send","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"GET /v1/families/{family_id}/threads","description":"\n\nRequired scopes: messages:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/threads/{thread_id}":{"patch":{"summary":"PATCH /v1/families/{family_id}/threads/{thread_id}","description":"\n\nRequired scopes: messages:send","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/threads/{thread_id}","description":"\n\nRequired scopes: messages:send","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/protocol":{"get":{"summary":"GET /v1/protocol","description":"","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/health":{"get":{"summary":"GET /v1/health","description":"","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/families/{family_id}/boards":{"post":{"summary":"POST /v1/families/{family_id}/boards","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"GET /v1/families/{family_id}/boards","description":"\n\nRequired scopes: boards:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/boards/{board_id}":{"get":{"summary":"GET /v1/families/{family_id}/boards/{board_id}","description":"\n\nRequired scopes: boards:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/boards/{board_id}","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"PATCH /v1/families/{family_id}/boards/{board_id}","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/boards/{board_id}/lists":{"get":{"summary":"GET /v1/families/{family_id}/boards/{board_id}/lists","description":"\n\nRequired scopes: boards:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"post":{"summary":"POST /v1/families/{family_id}/boards/{board_id}/lists","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/boards/{board_id}/lists/{list_id}":{"patch":{"summary":"PATCH /v1/families/{family_id}/boards/{board_id}/lists/{list_id}","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/boards/{board_id}/lists/{list_id}","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/boards/{board_id}/labels":{"get":{"summary":"GET /v1/families/{family_id}/boards/{board_id}/labels","description":"\n\nRequired scopes: boards:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"post":{"summary":"POST /v1/families/{family_id}/boards/{board_id}/labels","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/boards/{board_id}/labels/{label_id}":{"patch":{"summary":"PATCH /v1/families/{family_id}/boards/{board_id}/labels/{label_id}","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"label_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/boards/{board_id}/labels/{label_id}","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"label_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/boards/{board_id}/cards/{card_id}/labels/{label_id}":{"post":{"summary":"POST /v1/families/{family_id}/boards/{board_id}/cards/{card_id}/labels/{label_id}","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"card_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"label_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/boards/{board_id}/cards/{card_id}/labels/{label_id}","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"card_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"label_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/boards/{board_id}/cards/{card_id}/checklists":{"get":{"summary":"GET /v1/families/{family_id}/boards/{board_id}/cards/{card_id}/checklists","description":"\n\nRequired scopes: boards:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"card_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"post":{"summary":"POST /v1/families/{family_id}/boards/{board_id}/cards/{card_id}/checklists","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"card_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/boards/{board_id}/cards/{card_id}/checklists/{checklist_id}":{"patch":{"summary":"PATCH /v1/families/{family_id}/boards/{board_id}/cards/{card_id}/checklists/{checklist_id}","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"card_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"checklist_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/boards/{board_id}/cards/{card_id}/checklists/{checklist_id}","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"card_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"checklist_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/boards/{board_id}/cards/{card_id}/checklists/{checklist_id}/items":{"post":{"summary":"POST /v1/families/{family_id}/boards/{board_id}/cards/{card_id}/checklists/{checklist_id}/items","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"card_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"checklist_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/boards/{board_id}/cards/{card_id}/checklists/{checklist_id}/items/{item_id}":{"patch":{"summary":"PATCH /v1/families/{family_id}/boards/{board_id}/cards/{card_id}/checklists/{checklist_id}/items/{item_id}","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"card_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"checklist_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/boards/{board_id}/cards/{card_id}/checklists/{checklist_id}/items/{item_id}","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"card_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"checklist_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/boards/{board_id}/cards":{"post":{"summary":"POST /v1/families/{family_id}/boards/{board_id}/cards","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/boards/{board_id}/cards/{card_id}":{"patch":{"summary":"PATCH /v1/families/{family_id}/boards/{board_id}/cards/{card_id}","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"card_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/boards/{board_id}/cards/{card_id}","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"card_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/boards/{board_id}/cards/{card_id}/comments":{"post":{"summary":"POST /v1/families/{family_id}/boards/{board_id}/cards/{card_id}/comments","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"card_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"GET /v1/families/{family_id}/boards/{board_id}/cards/{card_id}/comments","description":"\n\nRequired scopes: boards:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"card_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/boards/{board_id}/cards/{card_id}/comments/{comment_id}":{"patch":{"summary":"PATCH /v1/families/{family_id}/boards/{board_id}/cards/{card_id}/comments/{comment_id}","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"card_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"comment_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/boards/{board_id}/cards/{card_id}/comments/{comment_id}","description":"\n\nRequired scopes: boards:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"board_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"card_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"comment_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/lists":{"post":{"summary":"POST /v1/families/{family_id}/lists","description":"\n\nRequired scopes: lists:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"GET /v1/families/{family_id}/lists","description":"\n\nRequired scopes: lists:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/recipes":{"post":{"summary":"create a recipe: title, description, ingredients[], instructions[], prep/cook minutes, servings","description":"create a recipe: title, description, ingredients[], instructions[], prep/cook minutes, servings\n\nRequired scopes: meals:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"GET /v1/families/{family_id}/recipes","description":"\n\nRequired scopes: meals:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/recipes/{recipe_id}":{"get":{"summary":"GET /v1/families/{family_id}/recipes/{recipe_id}","description":"\n\nRequired scopes: meals:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"recipe_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"PATCH /v1/families/{family_id}/recipes/{recipe_id}","description":"\n\nRequired scopes: meals:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"recipe_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/recipes/{recipe_id}","description":"\n\nRequired scopes: meals:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"recipe_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/recipes/{recipe_id}/add-to-list":{"post":{"summary":"add a recipe's ingredients as items to a grocery list; body: { list_id }","description":"add a recipe's ingredients as items to a grocery list; body: { list_id }\n\nRequired scopes: meals:read, lists:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"recipe_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/meal-ideas":{"post":{"summary":"create a meal idea (a combinable component, not a full recipe); body: { name, role?: main|side|other }","description":"create a meal idea (a combinable component, not a full recipe); body: { name, role?: main|side|other }\n\nRequired scopes: meals:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"GET /v1/families/{family_id}/meal-ideas","description":"\n\nRequired scopes: meals:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/meal-ideas/{idea_id}":{"patch":{"summary":"update a meal idea; body: { name?, role? }","description":"update a meal idea; body: { name?, role? }\n\nRequired scopes: meals:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"idea_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/meal-ideas/{idea_id}","description":"\n\nRequired scopes: meals:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"idea_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/meal-plans":{"post":{"summary":"create a weekly meal plan; body: { week_start: YYYY-MM-DD (Monday) }","description":"create a weekly meal plan; body: { week_start: YYYY-MM-DD (Monday) }\n\nRequired scopes: meals:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"GET /v1/families/{family_id}/meal-plans","description":"\n\nRequired scopes: meals:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/meal-plans/{plan_id}":{"get":{"summary":"includes entries: day 0-6 (Monday=0), meal_type breakfast/lunch/dinner; each entry has items[] (kind recipe|idea|text, with recipe_title / idea_name+idea_role resolved) plus legacy recipe_id/notes","description":"includes entries: day 0-6 (Monday=0), meal_type breakfast/lunch/dinner; each entry has items[] (kind recipe|idea|text, with recipe_title / idea_name+idea_role resolved) plus legacy recipe_id/notes\n\nRequired scopes: meals:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"plan_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/meal-plans/{plan_id}","description":"\n\nRequired scopes: meals:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"plan_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/meal-plans/{plan_id}/entries":{"post":{"summary":"set a meal slot to a single recipe/note; body: { day, meal_type, recipe_id?, notes? }; upserts the (day, meal_type) cell and replaces its items","description":"set a meal slot to a single recipe/note; body: { day, meal_type, recipe_id?, notes? }; upserts the (day, meal_type) cell and replaces its items\n\nRequired scopes: meals:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"plan_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/meal-plans/{plan_id}/items":{"post":{"summary":"append one item to a meal slot (cells hold multiple items); body: { day, meal_type, kind: recipe|idea|text, recipe_id?|idea_id?|text? }","description":"append one item to a meal slot (cells hold multiple items); body: { day, meal_type, kind: recipe|idea|text, recipe_id?|idea_id?|text? }\n\nRequired scopes: meals:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"plan_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/meal-plans/{plan_id}/items/{item_id}":{"delete":{"summary":"remove one item from a meal slot","description":"remove one item from a meal slot\n\nRequired scopes: meals:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"plan_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/lists/import":{"post":{"summary":"create a list from pasted markdown/plain text; headings/bare headers become sections, ✓/☐ markers set done state; {dry_run:true} returns the parse plan (sections, counts, warnings) and writes nothing; {list_id} appends, matching sections by name","description":"create a list from pasted markdown/plain text; headings/bare headers become sections, ✓/☐ markers set done state; {dry_run:true} returns the parse plan (sections, counts, warnings) and writes nothing; {list_id} appends, matching sections by name\n\nRequired scopes: lists:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/chores":{"post":{"summary":"create a chore list (e.g. Morning routine)","description":"create a chore list (e.g. Morning routine)\n\nRequired scopes: chores:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"GET /v1/families/{family_id}/chores","description":"\n\nRequired scopes: chores:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/chores/{list_id}":{"get":{"summary":"list with items and today's completions","description":"list with items and today's completions\n\nRequired scopes: chores:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"put":{"summary":"rename the chore list","description":"rename the chore list\n\nRequired scopes: chores:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/chores/{list_id}","description":"\n\nRequired scopes: chores:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/chores/{list_id}/items":{"post":{"summary":"add a chore item; optional assignee_person_id","description":"add a chore item; optional assignee_person_id\n\nRequired scopes: chores:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/chores/{list_id}/items/{item_id}":{"put":{"summary":"PUT /v1/families/{family_id}/chores/{list_id}/items/{item_id}","description":"\n\nRequired scopes: chores:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/chores/{list_id}/items/{item_id}","description":"\n\nRequired scopes: chores:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/chores/{list_id}/items/{item_id}/complete":{"post":{"summary":"mark done for today; optional person_id (defaults to caller)","description":"mark done for today; optional person_id (defaults to caller)\n\nRequired scopes: chores:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/chores/{list_id}/items/{item_id}/uncomplete":{"post":{"summary":"remove today's completion","description":"remove today's completion\n\nRequired scopes: chores:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/chores/{list_id}/streaks":{"get":{"summary":"current consecutive-day streak per person per item","description":"current consecutive-day streak per person per item\n\nRequired scopes: chores:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/lists/{list_id}":{"get":{"summary":"GET /v1/families/{family_id}/lists/{list_id}","description":"\n\nRequired scopes: lists:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"rename; also toggles ordered/favorite/archived","description":"rename; also toggles ordered/favorite/archived\n\nRequired scopes: lists:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"tombstones the list and descendants; retained rows are hidden from reads for privacy-safe restore/retention","description":"tombstones the list and descendants; retained rows are hidden from reads for privacy-safe restore/retention\n\nRequired scopes: lists:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/lists/{list_id}/sections":{"get":{"summary":"paged, audience-filtered section collection","description":"paged, audience-filtered section collection\n\nRequired scopes: lists:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"post":{"summary":"create a section with title and optional audience","description":"create a section with title and optional audience\n\nRequired scopes: lists:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/lists/{list_id}/sections/{section_id}":{"patch":{"summary":"PATCH /v1/families/{family_id}/lists/{list_id}/sections/{section_id}","description":"\n\nRequired scopes: lists:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"section_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"delete a section; items remain and become unsectioned","description":"delete a section; items remain and become unsectioned\n\nRequired scopes: lists:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"section_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/lists/{list_id}/items":{"post":{"summary":"text plus optional parent_item_id, section_id, priority, due_at, notes, recurrence, reminder_minutes, labels, assignee_agent_id or assignee_user_id (a family member; naming one clears the other), and audience","description":"text plus optional parent_item_id, section_id, priority, due_at, notes, recurrence, reminder_minutes, labels, assignee_agent_id or assignee_user_id (a family member; naming one clears the other), and audience\n\nRequired scopes: lists:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/lists/{list_id}/items/reorder":{"post":{"summary":"item_ids in order, or item_id + position","description":"item_ids in order, or item_id + position\n\nRequired scopes: lists:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/lists/{list_id}/items/{item_id}":{"patch":{"summary":"edit text/done/assignee, parent_item_id, section_id, priority, due_at, notes, recurrence, reminder_minutes, labels, or audience","description":"edit text/done/assignee, parent_item_id, section_id, priority, due_at, notes, recurrence, reminder_minutes, labels, or audience\n\nRequired scopes: lists:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"tombstones the item and descendants; response does not reveal hidden descendants","description":"tombstones the item and descendants; response does not reveal hidden descendants\n\nRequired scopes: lists:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/calendars":{"post":{"summary":"POST /v1/families/{family_id}/calendars","description":"\n\nRequired scopes: calendar:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"GET /v1/families/{family_id}/calendars","description":"\n\nRequired scopes: calendar:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/calendars/{calendar_id}":{"get":{"summary":"GET /v1/families/{family_id}/calendars/{calendar_id}","description":"\n\nRequired scopes: calendar:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"PATCH /v1/families/{family_id}/calendars/{calendar_id}","description":"\n\nRequired scopes: calendar:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/calendars/{calendar_id}","description":"\n\nRequired scopes: calendar:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/calendars/{calendar_id}/ics":{"get":{"summary":"public ICS feed; ?token=<feed_token> is the credential","description":"public ICS feed; ?token=<feed_token> is the credential","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/families/{family_id}/calendar-feeds/{feed_id}.ics":{"get":{"summary":"personal ICS feed; ?token=<one-time personal feed token> is the credential; current family membership and audiences are re-evaluated per request","description":"personal ICS feed; ?token=<one-time personal feed token> is the credential; current family membership and audiences are re-evaluated per request","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"feed_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/v1/families/{family_id}/calendars/{calendar_id}/ics/rotate":{"post":{"summary":"replace the public ICS feed token; previous URL stops working","description":"replace the public ICS feed token; previous URL stops working\n\nRequired scopes: admin, calendar:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/calendars/{calendar_id}/events":{"post":{"summary":"calendar_id '-' uses/creates the default Family calendar","description":"calendar_id '-' uses/creates the default Family calendar\n\nRequired scopes: calendar:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"?from=&to= ISO timestamps; recurring events expanded","description":"?from=&to= ISO timestamps; recurring events expanded\n\nRequired scopes: calendar:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/calendars/{calendar_id}/events/{event_id}":{"get":{"summary":"GET /v1/families/{family_id}/calendars/{calendar_id}/events/{event_id}","description":"\n\nRequired scopes: calendar:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"event_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"PATCH /v1/families/{family_id}/calendars/{calendar_id}/events/{event_id}","description":"\n\nRequired scopes: calendar:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"event_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/calendars/{calendar_id}/events/{event_id}","description":"\n\nRequired scopes: calendar:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"event_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/events/upcoming":{"get":{"summary":"family-wide upcoming feed (?days=14)","description":"family-wide upcoming feed (?days=14)\n\nRequired scopes: calendar:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/calendars/{calendar_id}/events/{event_id}/attendees":{"post":{"summary":"POST /v1/families/{family_id}/calendars/{calendar_id}/events/{event_id}/attendees","description":"\n\nRequired scopes: calendar:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"event_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/calendars/{calendar_id}/events/{event_id}/attendees/{attendee_id}":{"patch":{"summary":"PATCH /v1/families/{family_id}/calendars/{calendar_id}/events/{event_id}/attendees/{attendee_id}","description":"\n\nRequired scopes: calendar:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"event_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"attendee_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/calendars/{calendar_id}/events/{event_id}/attendees/{attendee_id}","description":"\n\nRequired scopes: calendar:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"event_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"attendee_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/calendars/{calendar_id}/events/{event_id}/reminders":{"post":{"summary":"POST /v1/families/{family_id}/calendars/{calendar_id}/events/{event_id}/reminders","description":"\n\nRequired scopes: calendar:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"event_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/calendars/{calendar_id}/events/{event_id}/reminders/{reminder_id}":{"delete":{"summary":"DELETE /v1/families/{family_id}/calendars/{calendar_id}/events/{event_id}/reminders/{reminder_id}","description":"\n\nRequired scopes: calendar:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"event_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"reminder_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/calendars/{calendar_id}/events/{event_id}/duplicate":{"post":{"summary":"POST /v1/families/{family_id}/calendars/{calendar_id}/events/{event_id}/duplicate","description":"\n\nRequired scopes: calendar:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"event_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/calendars/{calendar_id}/subscriptions":{"post":{"summary":"mirror an external ICS feed URL","description":"mirror an external ICS feed URL\n\nRequired scopes: calendar:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"GET /v1/families/{family_id}/calendars/{calendar_id}/subscriptions","description":"\n\nRequired scopes: calendar:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/calendars/{calendar_id}/subscriptions/{subscription_id}":{"delete":{"summary":"DELETE /v1/families/{family_id}/calendars/{calendar_id}/subscriptions/{subscription_id}","description":"\n\nRequired scopes: calendar:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/calendars/{calendar_id}/subscriptions/{subscription_id}/sync":{"post":{"summary":"POST /v1/families/{family_id}/calendars/{calendar_id}/subscriptions/{subscription_id}/sync","description":"\n\nRequired scopes: calendar:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/calendars/{calendar_id}/import-ics":{"post":{"summary":"{ics} one-time import into this calendar; dedupes on uid / uid#recurrence-id within the calendar; returns {imported, updated, skipped, updated_or_skipped, failed, total, truncated}","description":"{ics} one-time import into this calendar; dedupes on uid / uid#recurrence-id within the calendar; returns {imported, updated, skipped, updated_or_skipped, failed, total, truncated}\n\nRequired scopes: calendar:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/calendars/{calendar_id}/export-ics":{"get":{"summary":"authenticated download of the full calendar as .ics — all events including past ones (unlike the tokenized publish feed)","description":"authenticated download of the full calendar as .ics — all events including past ones (unlike the tokenized publish feed)\n\nRequired scopes: calendar:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"calendar_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/links":{"get":{"summary":"?from_type=note|event|list|card&from_id=; returns {links, backlinks} with audience-aware titles; card endpoints carry board_id, event endpoints carry calendar_id","description":"?from_type=note|event|list|card&from_id=; returns {links, backlinks} with audience-aware titles; card endpoints carry board_id, event endpoints carry calendar_id","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"post":{"summary":"{from_type, from_id, to_type, to_id}; requires write scope of the from_type module","description":"{from_type, from_id, to_type, to_id}; requires write scope of the from_type module","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/links/{link_id}":{"delete":{"summary":"requires write scope of the link's from_type module","description":"requires write scope of the link's from_type module","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"link_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/kb":{"post":{"summary":"accepts folder_id, tags[], pinned, archived","description":"accepts folder_id, tags[], pinned, archived\n\nRequired scopes: kb:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"?q, ?folder_id (id|root), ?tag, ?trashed=1; entries carry folder_id, tags[], pinned, archived","description":"?q, ?folder_id (id|root), ?tag, ?trashed=1; entries carry folder_id, tags[], pinned, archived\n\nRequired scopes: kb:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/kb/import":{"post":{"summary":"batch-create entries: {folder_id, entries:[{title, body}]} (max 100); per-entry results + {created, failed} summary; a bad entry fails alone","description":"batch-create entries: {folder_id, entries:[{title, body}]} (max 100); per-entry results + {created, failed} summary; a bad entry fails alone\n\nRequired scopes: kb:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/kb/{entry_id}":{"get":{"summary":"GET /v1/families/{family_id}/kb/{entry_id}","description":"\n\nRequired scopes: kb:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"entry_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"title/body/folder_id/tags/pinned/archived; title/body edits snapshot a version","description":"title/body/folder_id/tags/pinned/archived; title/body edits snapshot a version\n\nRequired scopes: kb:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"entry_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"soft-delete (trash)","description":"soft-delete (trash)\n\nRequired scopes: kb:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"entry_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/kb/{entry_id}/restore":{"post":{"summary":"POST /v1/families/{family_id}/kb/{entry_id}/restore","description":"\n\nRequired scopes: kb:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"entry_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/kb/{entry_id}/purge":{"delete":{"summary":"permanent delete","description":"permanent delete\n\nRequired scopes: kb:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"entry_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/kb/folders":{"get":{"summary":"GET /v1/families/{family_id}/kb/folders","description":"\n\nRequired scopes: kb:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"post":{"summary":"POST /v1/families/{family_id}/kb/folders","description":"\n\nRequired scopes: kb:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/kb/folders/{folder_id}":{"patch":{"summary":"PATCH /v1/families/{family_id}/kb/folders/{folder_id}","description":"\n\nRequired scopes: kb:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"folder_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"entries move to Unfiled","description":"entries move to Unfiled\n\nRequired scopes: kb:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"folder_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/kb/tags":{"get":{"summary":"GET /v1/families/{family_id}/kb/tags","description":"\n\nRequired scopes: kb:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"post":{"summary":"POST /v1/families/{family_id}/kb/tags","description":"\n\nRequired scopes: kb:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/kb/tags/{tag_id}":{"delete":{"summary":"DELETE /v1/families/{family_id}/kb/tags/{tag_id}","description":"\n\nRequired scopes: kb:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"tag_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/kb/{entry_id}/versions":{"get":{"summary":"GET /v1/families/{family_id}/kb/{entry_id}/versions","description":"\n\nRequired scopes: kb:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"entry_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/kb/{entry_id}/comments":{"get":{"summary":"GET /v1/families/{family_id}/kb/{entry_id}/comments","description":"\n\nRequired scopes: kb:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"entry_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"post":{"summary":"POST /v1/families/{family_id}/kb/{entry_id}/comments","description":"\n\nRequired scopes: kb:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"entry_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/kb/{entry_id}/comments/{comment_id}":{"delete":{"summary":"DELETE /v1/families/{family_id}/kb/{entry_id}/comments/{comment_id}","description":"\n\nRequired scopes: kb:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"entry_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"comment_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/kb/templates":{"get":{"summary":"GET /v1/families/{family_id}/kb/templates","description":"\n\nRequired scopes: kb:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"post":{"summary":"POST /v1/families/{family_id}/kb/templates","description":"\n\nRequired scopes: kb:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/kb/templates/{template_id}":{"patch":{"summary":"PATCH /v1/families/{family_id}/kb/templates/{template_id}","description":"\n\nRequired scopes: kb:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"template_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/kb/templates/{template_id}","description":"\n\nRequired scopes: kb:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"template_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/files":{"post":{"summary":"multipart/form-data (field 'file'); optional folder_id field; 25MB max","description":"multipart/form-data (field 'file'); optional folder_id field; 25MB max\n\nRequired scopes: files:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"?folder_id={id|root}&trashed=1&q=&limit=","description":"?folder_id={id|root}&trashed=1&q=&limit=\n\nRequired scopes: files:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/files/{file_id}":{"get":{"summary":"GET /v1/families/{family_id}/files/{file_id}","description":"\n\nRequired scopes: files:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"rename / move {filename?, folder_id? (null = root)}","description":"rename / move {filename?, folder_id? (null = root)}\n\nRequired scopes: files:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"hard delete (bytes removed)","description":"hard delete (bytes removed)\n\nRequired scopes: files:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/files/{file_id}/download":{"get":{"summary":"GET /v1/families/{family_id}/files/{file_id}/download","description":"\n\nRequired scopes: files:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/files/{file_id}/trash":{"post":{"summary":"soft-delete (move to trash)","description":"soft-delete (move to trash)\n\nRequired scopes: files:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/files/{file_id}/restore":{"post":{"summary":"POST /v1/families/{family_id}/files/{file_id}/restore","description":"\n\nRequired scopes: files:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/trash/empty":{"post":{"summary":"permanently delete all trashed files","description":"permanently delete all trashed files\n\nRequired scopes: files:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/file-folders":{"get":{"summary":"GET /v1/families/{family_id}/file-folders","description":"\n\nRequired scopes: files:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"post":{"summary":"{name, parent_id?}","description":"{name, parent_id?}\n\nRequired scopes: files:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/file-folders/{folder_id}":{"patch":{"summary":"{name?, parent_id? (null = root)}","description":"{name?, parent_id? (null = root)}\n\nRequired scopes: files:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"folder_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"deletes the folder tree; files move to root","description":"deletes the folder tree; files move to root\n\nRequired scopes: files:write","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"folder_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/search":{"get":{"summary":"q required; each result type gated by its own read scope","description":"q required; each result type gated by its own read scope","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/webhooks":{"post":{"summary":"POST /v1/families/{family_id}/webhooks","description":"\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"GET /v1/families/{family_id}/webhooks","description":"\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/webhooks/{webhook_id}":{"delete":{"summary":"DELETE /v1/families/{family_id}/webhooks/{webhook_id}","description":"\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/webhooks/{webhook_id}/test":{"post":{"summary":"POST /v1/families/{family_id}/webhooks/{webhook_id}/test","description":"\n\nRequired scopes: admin","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/connectors":{"post":{"summary":"register a shared MCP server (URL + auth, encrypted); tests it immediately","description":"register a shared MCP server (URL + auth, encrypted); tests it immediately\n\nRequired scopes: connectors:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"list connections without secrets; each row says whether you may use it","description":"list connections without secrets; each row says whether you may use it","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/connectors/{connector_id}":{"get":{"summary":"detail + cached tool list; grants included for connectors:manage","description":"detail + cached tool list; grants included for connectors:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connector_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"PATCH /v1/families/{family_id}/connectors/{connector_id}","description":"\n\nRequired scopes: connectors:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connector_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/connectors/{connector_id}","description":"\n\nRequired scopes: connectors:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connector_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/connectors/{connector_id}/test":{"post":{"summary":"initialize + tools/list; updates status","description":"initialize + tools/list; updates status\n\nRequired scopes: connectors:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connector_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/connectors/{connector_id}/tools":{"get":{"summary":"tool list for a connection you may use","description":"tool list for a connection you may use\n\nRequired scopes: connectors:use","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connector_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/connectors/{connector_id}/call":{"post":{"summary":"invoke a tool through the hub; the hub forwards with the stored credentials","description":"invoke a tool through the hub; the hub forwards with the stored credentials\n\nRequired scopes: connectors:use","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connector_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/connectors/{connector_id}/grants":{"post":{"summary":"set the per-agent allowlist {agent_ids}","description":"set the per-agent allowlist {agent_ids}\n\nRequired scopes: connectors:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connector_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/connectors/{connector_id}/reveal":{"post":{"summary":"decrypt the stored credentials (audit-logged)","description":"decrypt the stored credentials (audit-logged)\n\nRequired scopes: connectors:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connector_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/smart-home/connection":{"put":{"summary":"connect Home Assistant {base_url, token}; token encrypted at rest, connection tested, devices synced","description":"connect Home Assistant {base_url, token}; token encrypted at rest, connection tested, devices synced\n\nRequired scopes: smart_home:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"connection status (never the token)","description":"connection status (never the token)\n\nRequired scopes: smart_home:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"disconnect and drop the cached device list","description":"disconnect and drop the cached device list\n\nRequired scopes: smart_home:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/smart-home/sync":{"post":{"summary":"re-pull the device inventory from Home Assistant","description":"re-pull the device inventory from Home Assistant\n\nRequired scopes: smart_home:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/smart-home/devices":{"get":{"summary":"?domain=; only devices your role may see; each row says whether you may control it","description":"?domain=; only devices your role may see; each row says whether you may control it\n\nRequired scopes: smart_home:use","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/smart-home/devices/{entity_id}":{"patch":{"summary":"set per-device access {access: everyone|adults|hidden} and/or allowed_services (subset of the domain's services; null restores default; [] = view-only)","description":"set per-device access {access: everyone|adults|hidden} and/or allowed_services (subset of the domain's services; null restores default; [] = view-only)\n\nRequired scopes: smart_home:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/smart-home/devices/{entity_id}/grants":{"get":{"summary":"list per-member/per-agent grants for one device","description":"list per-member/per-agent grants for one device\n\nRequired scopes: smart_home:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"put":{"summary":"upsert a grant {grantee_kind: user|agent, grantee_id, can_view, can_control}; replaces the access level for that grantee","description":"upsert a grant {grantee_kind: user|agent, grantee_id, can_view, can_control}; replaces the access level for that grantee\n\nRequired scopes: smart_home:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/smart-home/devices/{entity_id}/grants/{grantee_kind}/{grantee_id}":{"delete":{"summary":"remove a grant","description":"remove a grant\n\nRequired scopes: smart_home:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"grantee_kind","in":"path","required":true,"schema":{"type":"string"}},{"name":"grantee_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/smart-home/control":{"post":{"summary":"{entity_id, service, service_data?}; policy-checked and audit-logged","description":"{entity_id, service, service_data?}; policy-checked and audit-logged\n\nRequired scopes: smart_home:use","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/smart-home/logbook":{"get":{"summary":"?hours= (1-168, default 24); human-readable recent activity, filtered to devices you may see","description":"?hours= (1-168, default 24); human-readable recent activity, filtered to devices you may see\n\nRequired scopes: smart_home:use","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/smart-home/devices/{entity_id}/history":{"get":{"summary":"?hours= (1-168, default 24); compact state history points plus min/max/avg stats for numeric sensors","description":"?hours= (1-168, default 24); compact state history points plus min/max/avg stats for numeric sensors\n\nRequired scopes: smart_home:use","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/smart-home/automations":{"post":{"summary":"create a native Home Assistant automation {name, description?, triggers[], conditions?[], actions[]}","description":"create a native Home Assistant automation {name, description?, triggers[], conditions?[], actions[]}\n\nRequired scopes: smart_home:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/smart-home/automations/{entity_id}":{"delete":{"summary":"delete a config-managed automation","description":"delete a config-managed automation\n\nRequired scopes: smart_home:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/smart-home/members":{"get":{"summary":"family humans and their smart-home roles (adult|kid), plus the family's agents (grantee picker for per-device grants)","description":"family humans and their smart-home roles (adult|kid), plus the family's agents (grantee picker for per-device grants)\n\nRequired scopes: smart_home:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/smart-home/members/{user_id}":{"put":{"summary":"set a member's smart-home role {role}","description":"set a member's smart-home role {role}\n\nRequired scopes: smart_home:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"user_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/secrets":{"post":{"summary":"store a shared secret (encrypted); family members can add entries, agents need vault:manage","description":"store a shared secret (encrypted); family members can add entries, agents need vault:manage\n\nRequired scopes: vault:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"names and notes only — never values","description":"names and notes only — never values\n\nRequired scopes: vault:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/secrets/{secret_id}/value":{"get":{"summary":"decrypt one secret (audit-logged); people reveal as a family admin, the entry's creator, or when explicitly in the entry's audience","description":"decrypt one secret (audit-logged); people reveal as a family admin, the entry's creator, or when explicitly in the entry's audience\n\nRequired scopes: vault:read","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"secret_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/families/{family_id}/secrets/{secret_id}":{"patch":{"summary":"PATCH /v1/families/{family_id}/secrets/{secret_id}","description":"\n\nRequired scopes: vault:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"secret_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/families/{family_id}/secrets/{secret_id}","description":"\n\nRequired scopes: vault:manage","parameters":[{"name":"family_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"secret_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/personal/items":{"post":{"summary":"create a personal note or memory {kind, title?, body}","description":"create a personal note or memory {kind, title?, body}\n\nRequired scopes: personal:write","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"?q=&kind= search; each item carries hidden_agent_ids","description":"?q=&kind= search; each item carries hidden_agent_ids\n\nRequired scopes: personal:read","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/personal/items/{item_id}":{"get":{"summary":"GET /v1/personal/items/{item_id}","description":"\n\nRequired scopes: personal:read","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"PATCH /v1/personal/items/{item_id}","description":"\n\nRequired scopes: personal:write","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/personal/items/{item_id}","description":"\n\nRequired scopes: personal:write","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/personal/calendar-feeds":{"post":{"summary":"human session only; mint a human-owned ICS feed token; the raw token is returned once","description":"human session only; mint a human-owned ICS feed token; the raw token is returned once","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"paginated feed ids and revocation state (?limit=&cursor=); raw tokens are never returned","description":"paginated feed ids and revocation state (?limit=&cursor=); raw tokens are never returned\n\nRequired scopes: personal:read","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/personal/calendar-feeds/{feed_id}":{"delete":{"summary":"human session only; revoke one of the caller's personal ICS feeds","description":"human session only; revoke one of the caller's personal ICS feeds","parameters":[{"name":"feed_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/personal/items/{item_id}/hidden":{"post":{"summary":"per-item opt-out {agent_id}; hidden agents get 404","description":"per-item opt-out {agent_id}; hidden agents get 404\n\nRequired scopes: personal:write","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/personal/items/{item_id}/hidden/{agent_id}":{"delete":{"summary":"DELETE /v1/personal/items/{item_id}/hidden/{agent_id}","description":"\n\nRequired scopes: personal:write","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/personal/items/{item_id}/copy-to-family":{"post":{"summary":"deprecated: returns 409 review_required; create and review a Personal share draft instead","description":"deprecated: returns 409 review_required; create and review a Personal share draft instead","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/personal/share-drafts":{"post":{"summary":"propose a frozen Personal item/list share; agents may suggest but only the human owner may publish","description":"propose a frozen Personal item/list share; agents may suggest but only the human owner may publish\n\nRequired scopes: personal:write","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"get":{"summary":"list the owner's Personal share drafts; hidden source items remain hidden from agents","description":"list the owner's Personal share drafts; hidden source items remain hidden from agents\n\nRequired scopes: personal:read","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/personal/share-drafts/{draft_id}":{"get":{"summary":"GET /v1/personal/share-drafts/{draft_id}","description":"\n\nRequired scopes: personal:read","parameters":[{"name":"draft_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"edit the frozen proposed title/body/list snapshot or audience while pending","description":"edit the frozen proposed title/body/list snapshot or audience while pending\n\nRequired scopes: personal:write","parameters":[{"name":"draft_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"discard a pending draft; publication is human-only","description":"discard a pending draft; publication is human-only\n\nRequired scopes: personal:write","parameters":[{"name":"draft_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/personal/share-drafts/{draft_id}/publish":{"post":{"summary":"human session only; family_id is REQUIRED (?family_id= or body) — no default-family fallback; atomically publishes the reviewed copy into that family and marks the draft published; response names family_id","description":"human session only; family_id is REQUIRED (?family_id= or body) — no default-family fallback; atomically publishes the reviewed copy into that family and marks the draft published; response names family_id","parameters":[{"name":"draft_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/personal/audit":{"get":{"summary":"?limit=; personal events only (user_id set, family_id NULL)","description":"?limit=; personal events only (user_id set, family_id NULL)\n\nRequired scopes: personal:read","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/personal/lists":{"get":{"summary":"personal lists (visibility=personal, family_id NULL, owned by the caller)","description":"personal lists (visibility=personal, family_id NULL, owned by the caller)\n\nRequired scopes: personal:read","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"post":{"summary":"{title, ordered?}; the list is personal at creation and carries no family (family_id NULL)","description":"{title, ordered?}; the list is personal at creation and carries no family (family_id NULL)\n\nRequired scopes: personal:write","parameters":[],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/personal/lists/{list_id}":{"get":{"summary":"returns {list, items}","description":"returns {list, items}\n\nRequired scopes: personal:read","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"rename; also toggles ordered/favorite/archived","description":"rename; also toggles ordered/favorite/archived\n\nRequired scopes: personal:write","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/personal/lists/{list_id}","description":"\n\nRequired scopes: personal:write","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/personal/lists/{list_id}/share-to-family":{"post":{"summary":"deprecated: returns 409 review_required; create and review a Personal share draft instead","description":"deprecated: returns 409 review_required; create and review a Personal share draft instead","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/personal/lists/{list_id}/items":{"post":{"summary":"{text}","description":"{text}\n\nRequired scopes: personal:write","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/personal/lists/{list_id}/items/reorder":{"post":{"summary":"item_ids in order, or item_id + position","description":"item_ids in order, or item_id + position\n\nRequired scopes: personal:write","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}},"/v1/personal/lists/{list_id}/items/{item_id}":{"patch":{"summary":"{text?, done?}","description":"{text?, done?}\n\nRequired scopes: personal:write","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"DELETE /v1/personal/lists/{list_id}/items/{item_id}","description":"\n\nRequired scopes: personal:write","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}},"security":[{"bearerAuth":[]}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"agent token"}}}}