{
  "openapi": "3.0.3",
  "info": {
    "title": "FundlyHub API",
    "version": "3.2.0",
    "description": "Complete REST API for FundlyHub — the AI-powered fundraising platform.\n\n## Authentication\nThe web app authenticates with httpOnly session cookies (`access_token`,\n`id_token`, `refresh_token`) that `POST /cognito/signin` and the OAuth\ncallback set. Sign-in does **not** return tokens in its body.\n\nScripts and integrations authenticate with an **API key**: create one\nwith `POST /api-keys` from a signed-in session and send it as\n`Authorization: Bearer fh_live_…`. A Cognito JWT is also accepted in the\nsame header. An API key acts as its owner, with every permission the\nowner holds — treat it like a password. A key expires (at most one year\nafter it is created), cannot create or revoke API keys, and stops working\nwhile its owner's account is not active. Send one credential per\nrequest: either the session cookies or an `Authorization` header.\n\nA missing credential answers `401`, and so does a session token that is\npresent but invalid or expired (`Invalid token`, `code: TOKEN_INVALID`) or\nthat cannot be verified (`code: TOKEN_VERIFICATION_FAILED`): refresh the\nsession and retry. An API key that is unknown, expired or revoked, or whose\nowner's account is not active, answers `401` (`Invalid API key`). `403` is\nreserved for an authenticated caller who is not allowed to do something.\n\nOperations that show no `security` requirement are genuinely public. Where\nan operation lists both `BearerAuth` and `{}`, authentication is optional\nand changes what comes back — an owner sees their own drafts, a signed-in\ndonor gets the gift attributed to their account.\n\nSome endpoints additionally require a **specific permission**; where that\nis the case the permission is named in the operation's description, and a\nsession without it gets `403` with `required_permission` in the body.\nSeveral write endpoints also require a **verified email address**\n(`403` with `code: EMAIL_NOT_VERIFIED`) or sit behind a **feature flag**\n(`403` with `feature_key`). A flag with no stored setting counts as on.\n\n## Response envelopes\nMost read endpoints wrap their payload: a single object comes back as\n`{ \"data\": { … } }`, and a collection as `{ \"data\": [ … ] }`, with\npaginated collections adding `{ \"pagination\": { \"limit\", \"offset\",\n\"total\" } }`. This is a convention rather than a rule — a handful of\nendpoints return a bare object or a bare array, and each operation below\ndocuments the shape it actually returns. Errors are always unwrapped:\n`{ \"error\": \"…\", \"message\": \"…\" }`, sometimes with a machine-readable\n`code` or a `details` array of validation failures.\n\n## Rate limits\nA global limiter of **100 requests/minute per IP** covers the API.\nPublic browsing reads — campaign, organization, category, platform-stats\nand search reads, the profile reads, and the public reads of non-profits,\ncities, communities and success stories — are exempt from it, and most\nof them count against a **300/min per IP** bucket instead (an operation\nthat can answer `429` lists it). Other routes add a tighter bucket on\ntop of the global one:\n\n- **Authentication** (sign-up, sign-in, password reset and change, unsubscribe writes, platform tips): 10/min per IP\n- **Verification resends and private-contact changes**: 5/min per user (per IP for a signed-out resend)\n- **Public writes that send mail or store free text** (receipt emails, donor notes, DMCA notices, ambassador applications): 5/min per IP\n- **Financial and endorsement endpoints** (earnings, Stripe Connect, endorsements, receipt resends): 100/min per account\n- **Organization creation**: 5/hour per (IP, user)\n- **Organization member lookups and adds** (`GET /org-admin/{slug}/users/search`, `POST /org-admin/{slug}/members`): 30/min per user, one bucket for both\n- **Campaign media and outcome-report writes**: 30 per 15 minutes per (IP, user)\n- **Referral clicks**: 120/min per caller; **card share images**: 120/min per IP; **campaign presence heartbeats**: 4/min per IP and campaign\n- **AI endpoints**: 10/min per user, applied inside the handler\n- **AI image generation**: 10/hour and 30/day per user\n\nExceeding a limit returns `429` with `RateLimit-Policy`,\n`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and\n`Retry-After` headers. The AI endpoints' in-handler limit answers a bare\n`429` without them.\n",
    "contact": {
      "name": "FundlyHub Developer Support",
      "url": "https://fundlyhub.org"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://api.staging.fundlyhub.org/api/v1",
      "description": "Staging"
    },
    {
      "url": "https://api.fundlyhub.org/api/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Creator Hub",
      "description": "Private social projects, versioned templates, community sharing and authorized campaign assets."
    },
    {
      "name": "Non-profits",
      "description": "Non-profit organizations on FundlyHub: the directory, a non-profit's page and its tabs (Fundlies, team, activity, impact, public documents), following, link clicks and reports, joining the team by request or invite, giving to its general fund (the giving policy, a quote and checkout), the non-profits a signed-in person may start a Fundly for, and the add flow: an EIN lookup, a draft, proof of authority to act for the organization, and submission for review. A page's `{slug}` takes its current slug, an old one or its id; the add flow's paths take the id. A draft is visible only to its owner, and a page under review, rejected or suspended only to its team and staff; anyone else gets `404`. These endpoints' own refusals come as `{ \"error\": { \"code\", \"message\", \"details\" } }`, where `code` is the reason to branch on."
    },
    {
      "name": "Non-profits · Team settings",
      "description": "A non-profit's own team at work, under `/org-admin/{slug}`: what needs attention, the page's settings, links and programs, the team with its invites, join requests and ownership transfer, and the verification and tax status with an on-demand re-check. Every operation needs a signed-in session and an org-scoped permission on that organization, as under Organization Admin: `org.read` for the read-only views, `org.update_settings` for the page's settings, links and programs, and `nonprofit.team.manage` (the owner and admins) for the team. Only the owner transfers ownership, and only to an admin. An organization that is not a non-profit answers `404`."
    },
    {
      "name": "Sponsors",
      "description": "Local businesses that give perks to people who hold FundlyHub achievements. Sponsors never receive donations. The directory (by city, category, name or what you can use), a sponsor's page and its perks, locations, impact and updates, following a sponsor, a sticker's page, reporting wrong information, and a signed-in person's My perks. A sponsor's `{key}` takes its current slug, an old one or its id. A sponsor that is not live yet is visible only to its team and to staff; anyone else gets `404`. Every operation answers `403` while sponsors are switched off."
    },
    {
      "name": "Sponsors · Become a sponsor",
      "description": "Making a business a sponsor: finding it, a draft saved as you go through five steps, showing you run it (a code sent to a work email at the website's domain, or a document a person reviews), submitting it for review, asking to join an existing sponsor's team, telling FundlyHub a sponsor is your business, and accepting a team or owner invite. Needs a signed-in session."
    },
    {
      "name": "Sponsors · Workspace",
      "description": "A sponsor's own team at work, under `/sponsors/{key}/manage`: the page, perks and their versions, updates, locations with hours and closures, the team, counter devices, sticker kits, online code lists and settings. What each person may do follows their role: the owner does everything; admins everything except handing over ownership and leaving FundlyHub; managers keep hours, cashiers and counter devices at their locations; cashiers use the counter. A request beyond the role answers `403`; anyone not on the team gets `404`. Handing over ownership, leaving FundlyHub, adding an admin and pairing a counter device are confirmed with a code emailed to the person."
    },
    {
      "name": "Sponsors · Perks and the counter",
      "description": "Using a perk: a signed-in person's live in-store code (it changes every 30 seconds and works once, for 2 minutes), a one-time code for an online perk, receipts, and reporting a perk that wasn't honored. The counter at fundlyhub.org/counter: pairing a device to a location, checking a code and giving the perk, undoing it within 15 minutes. The business's side: perks used and answering reports. Sponsors see counts, times, places, perks and tiers, never who."
    },
    {
      "name": "Free stuff",
      "description": "Free stuff from neighbors: one-off things a person (or, once in a while, a non-profit, church, business or community they run) gives away, kept apart from providers' recurring giveaways. Free means free: no prices, deposits, trades or \"best offer\". Browsing needs no account and shows the area and a distance band (\"about 2 mi\"), never the pickup address or an exact point. Asking, giving, the pickup thread and reports need a signed-in person with a verified email and phone (`403` with `code` `EMAIL_NOT_VERIFIED` or `PHONE_NOT_VERIFIED`). The giver chooses who gets it (\"Let me choose\") or the first ask is chosen at once (\"First to ask\"); the pickup place and note are shared with the person chosen only. Limits held by the server: 5 open asks a person, 10 posts a day, 30 messages an hour per person per thread; two no-shows within 60 days pause asking for 14 days. A person the giver blocked can't see their items, ask or message them. Every operation answers `404` while `features.free_stuff` (or `features.resources`, which it sits under) is off. Refusals come as `{ \"error\": { \"code\", \"message\", \"details\" } }`."
    },
    {
      "name": "Resources",
      "description": "Find help: free and low-cost local help from non-profits, churches, businesses, communities and public programs. The search (a POST, so a sensitive topic never lands in a URL or a log), the topics with their hotlines and first steps, a provider's page, the \"Help we offer\" section other pages show, reporting a problem with a listing, and suggesting a place that helps. No account is needed. A confidential address never appears in any answer: only its city and that the address is given by phone. A private community's members-only help is shown only to its active members, and never in the search. Every operation answers `403` while Resources are switched off. Refusals come as `{ \"error\": { \"code\", \"message\", \"details\" } }`, where `code` is the reason to branch on."
    },
    {
      "name": "Communities",
      "description": "Communities, such as a church, a school, a workplace or a city: the directory and featured lists, a community's page and its tabs, joining (one tap, by request, or a paid membership), people, invites and invite links, roles (owner, leaders, volunteers, members), posts, sharing Fundlies to a community (with leader approval where it is required), the community fund and its Stripe account, and each person's community settings. A community is named by its slug or its uuid (`{key}`, or `{id}` under `/communities/`). Reads answer `404` for a deleted community, a draft (except to its owner) and a hidden or suspended community (except to its members); a suspended community is read-only. Moving the fund's money and opening its Stripe links need a real signed-in session: an API key or an impersonating admin cannot."
    },
    {
      "name": "Authentication",
      "description": "User registration, login, and session management via AWS Cognito"
    },
    {
      "name": "Fundraisers",
      "description": "Create and manage fundraising campaigns"
    },
    {
      "name": "Success Stories",
      "description": "What a Fundly did once it ended. Every public Fundly that ended with money raised has a story page, unless it is under review or reported, a gift to it is in an open dispute, or its organizer or organization is suspended. The public index (filtered by fully funded, ended or closed) and the story pages compute their figures live, such as the amount raised, the donors, the first gift and the payout; the story's words appear only once staff publish them. The organizer reads and edits their own Fundly's story and approves its words, and staff then publish it."
    },
    {
      "name": "Cities",
      "description": "The `/cities` index and map, one city's page, and following a city: a weekly digest and instant alerts by email, a one-click opt-out from either, and the list of cities you follow; plus the MapKit JS token and static map snapshots. A city gets a public page once it has one verified Fundly or one donor who lives there, unless staff override that; below it, the city still shows on the map. Donor counts are exact from the first donor (signed in, guest or anonymous), while the follower count and where a city's gifts go show only from 5 followers and 5 donors. Donors are never listed by city. Reading needs no account; following needs a signed-in session."
    },
    {
      "name": "Donations",
      "description": "Process and track donations"
    },
    {
      "name": "Categories",
      "description": "Browse fundraiser categories"
    },
    {
      "name": "Organizations",
      "description": "Manage nonprofit organizations"
    },
    {
      "name": "Users",
      "description": "User profiles and preferences"
    },
    {
      "name": "Search",
      "description": "Full-text search and autocomplete"
    },
    {
      "name": "Payouts",
      "description": "Earnings and payout management"
    },
    {
      "name": "Milestones",
      "description": "Campaign milestones and progress tracking"
    },
    {
      "name": "Payments",
      "description": "Stripe payment processing"
    },
    {
      "name": "App Attest",
      "description": "Apple App Attest for the FundlyHub iOS app. A request carrying a valid assertion may skip reCAPTCHA on `POST /payments/create-intent` and `POST /donations`, guest or signed in. See the Native Clients guide for the byte-level protocol."
    },
    {
      "name": "AI",
      "description": "AI-powered content tools"
    },
    {
      "name": "RBAC",
      "description": "The signed-in caller's own roles and permissions"
    },
    {
      "name": "Platform",
      "description": "Platform stats and health"
    },
    {
      "name": "Donors",
      "description": "A donor's own giving history, summary, and annual statements"
    },
    {
      "name": "Notifications",
      "description": "In-app notifications for the authenticated user. Which events also generate email is governed by the toggles on `/users/{id}/preferences`, not by anything under `/notifications`."
    },
    {
      "name": "Social",
      "description": "Following users and organizations"
    },
    {
      "name": "Comments",
      "description": "Fundraiser comments and replies"
    },
    {
      "name": "Updates",
      "description": "Project updates, milestones, and funding stats"
    },
    {
      "name": "Shares",
      "description": "Sharing a campaign: recording a share-button tap for a fundraiser or a profile (signed in or not), the campaign's PNG link-preview image, square poster and story card and the zip kit that bundles them, and what sharing has done for a campaign: visits through shared links and the gifts they led to, in total and per share channel. The images and the counts are public for a campaign anyone may open by its link."
    },
    {
      "name": "Organization Admin",
      "description": "The org-scoped admin panel at `/org-admin/{slug}/*`. Every operation needs a bearer session, resolves `{slug}` to an organization (an unknown or malformed slug answers `404 Organization not found`, never `403`), and then checks an **org-scoped permission** held through the caller's `org_owner`, `org_admin` or `org_viewer` role on that organization. A caller without the permission gets `403` with `message: \"Requires permission: <name>\"`.\n\nRole → permission map: `org_viewer` holds `org.read`, `org.read_donations`, `org.read_payouts` and `org.read_donors`. `org_admin` adds `org.update_settings`, `org.manage_members`, `org.manage_dbas`, `org.manage_locations` and `org.upload_documents`. `org_owner` adds `org.manage_children` and `org.manage_payouts`."
    },
    {
      "name": "Translations",
      "description": "The owner-side Translations tab: a campaign's, its milestones' and its updates' rows in the other supported locales (`en`, `ru`, `uk`, `es`), hand-edited or regenerated. The public read paths already serve the translated text; these endpoints are for authors."
    },
    {
      "name": "Endorsements",
      "description": "Ambassadors publicly vouching for other people's campaigns, and creators asking ambassadors to promote theirs."
    },
    {
      "name": "Media",
      "description": "A campaign's photo and video gallery. Behind the `features.fundraiser_video` flag."
    },
    {
      "name": "Images",
      "description": "Stock-photo search, AI cover generation and server-side image copying for the campaign builder, plus an allowlisted image proxy."
    },
    {
      "name": "Storage",
      "description": "Direct uploads of images to the platform's CDN bucket, and the record of the original and the crop behind each cropped image."
    },
    {
      "name": "Achievements",
      "description": "The public badge catalogue, single badges, the \"just earned\" feed, and individual earned cards with their share pictures and verify QR codes."
    },
    {
      "name": "Wallet",
      "description": "Apple Wallet passes: a card's holder downloads their earned card through a short-lived link, and anyone can download a pass for a fundraiser that can be opened by its link. Passes keep themselves current through the PassKit web service under `/passkit/v1`, which Wallet itself calls, with the pass's own token (`Authorization: ApplePass <token>`) where Apple's protocol asks for one. Passes come in English, Russian, Ukrainian or Spanish. Until the platform's Pass Type ID certificate is configured, every endpoint but `GET /wallet/status` answers `503` (`code: wallet_unavailable`)."
    },
    {
      "name": "API Keys",
      "description": "Long-lived `fh_live_…` keys for CLI and agent access. A key is sent as `Authorization: Bearer fh_live_…` and authenticates as the user who created it, on every endpoint that accepts a bearer session."
    },
    {
      "name": "Creator Subscriptions",
      "description": "Creator monetisation tiers (each mirrored to a Stripe Product and Prices) and the fan-side recurring subscriptions to them."
    },
    {
      "name": "Ambassadors",
      "description": "The ambassador programme: the public directory, invitations and applications, referral links and click tracking, and the ambassador portal under `/me/referrals/*`."
    },
    {
      "name": "Email Preferences",
      "description": "Public, token-authorised unsubscribe and resubscribe for any address FundlyHub mails, including guest donors with no account."
    },
    {
      "name": "Meta",
      "description": "Crawler-facing discovery files (`llms.txt`, sitemaps), generated from live data and proxied by the frontend at the site's public paths."
    },
    {
      "name": "DMCA",
      "description": "DMCA §512 takedown notices and counter-notices. Currently dark behind the `features.dmca_workflow` flag."
    },
    {
      "name": "Support",
      "description": "Live-chat (Chatwoot) identity for the signed-in user."
    },
    {
      "name": "Resources · Workspace",
      "description": "A provider's own team at work on the help it lists in Resources: one set of routes for a non-profit or church, a business, a community and (for staff) a public program. Each route checks the provider kind's own roles (lib/resources/access.ts): a non-profit's owners and admins manage (`nonprofit.resources.manage`) and fundraisers and viewers read (`org.read`); a business's owner and admins manage, a manager at their own locations, cashiers nothing; a community's owner and leaders manage, volunteers keep capacity and the stock note. Staff with manage_resources pass every action. Anyone not on the team gets `404`; a role too low `403`. Every operation answers `403` while Resources are switched off (features.resources), except to FundlyHub staff (review_resources or manage_resources) on a provider's, a resource's or a link's routes and the places search: Admin -> Resources opens the editor in staff mode and a resource's history through them, and staff routes skip the switch."
    },
    {
      "name": "Resources · Fundraisers",
      "description": "A fundraiser naming the help it raises money for (\"Help we're raising for\"), the provider's confirmation, direct payout and My help (#2424). A visitor sees confirmed links only; the fundraiser's organizer (its owner, as `PATCH /fundraisers/{id}` decides it) also sees requested, needs_confirmation and declined links, never a decline's reason. Where gifts go is always read from the fundraiser's own beneficiary (the columns checkout reads), never from a flag: \"Send gifts straight to\" changes that beneficiary to the provider's non-profit through the existing non-profit beneficiary path, and a transfer, merge or decline never touches it. Every operation answers `403` while Resources are switched off (features.resources)."
    },
    {
      "name": "Events",
      "description": "Events (#2483): the list of live events, an event page with its viewer block, and the forms on it (volunteer, sponsor this dinner, report). Behind features.events: while it is off every operation answers 404, except to staff with manage_events. Drafts, events in review and suspended events answer 404 to anyone but their hosts and staff. Refusals come as `EventError`."
    },
    {
      "name": "Events · Hosts",
      "description": "Hosting an event (#2483): start and edit it, its days and Fundly shares, ticket types, co-hosts, volunteers, sponsors, photos and recap, submit, duplicate, postpone and cancel; and the caller's own lists. An event's routes are for its accepted hosts (whoever acts for an accepted host row: the member, a non-profit or church's owners and admins, a community's owner and leaders, a sponsor's owner and admins) and staff with manage_events; anyone else gets 404. A rule's refusal is 409 `not_allowed` with `details.reason`, the same i18n key the page's viewer block shows. Behind features.events."
    },
    {
      "name": "Events · Tickets",
      "description": "Tickets (#2487): checkout (hold seats for 10 minutes, fill in, pay), the order and its receipt, cancelling and asking for a refund, the ticket (its code is the ticket), its Apple Wallet pass and calendar file, the waitlist, and a volunteer answering an invitation. One card payment on the platform account is split into one ordinary gift per linked Fundly by its share. Behind features.events. A rule's refusal is 409 `not_allowed` with `details.reason`."
    },
    {
      "name": "Events · People",
      "description": "People and the door (#2487): the hosts' guest list and export, adding people, approving requests, refunds and refund requests, the waitlist, messaging guests, and door check-in (also for volunteers whose role checks people in, during the event), offline with a batch sync. For an event's accepted hosts and staff with manage_events. Behind features.events."
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "In the browser, authentication rides on the httpOnly session cookies set by `/cognito/signin` or the Google / Apple sign-in at `/cognito/oauth/{provider}`. For scripts and for Swagger UI testing, paste an API key (`fh_live_…`, created with `POST /api-keys`); a Cognito JWT is accepted too. Sign-in does not return a token in its body."
      },
      "ApplePassAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Apple's PassKit web service scheme: `Authorization: ApplePass <authenticationToken>`, the token inside the pass itself. Sent by Wallet, never by a person."
      }
    },
    "schemas": {
      "AmbassadorSendState": {
        "type": "object",
        "description": "When an ambassador can email this business again (#2364).",
        "properties": {
          "sentAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "sendCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 3
          },
          "nextAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the next email is allowed; null once the address had its three."
          },
          "canSend": {
            "type": "boolean"
          }
        }
      },
      "SponsorMenu": {
        "type": "object",
        "description": "The sponsor entries of the header, the account menu and the footer. Signed out, both lists are empty; the answer itself still says sponsors are on.",
        "required": [
          "businesses",
          "counter"
        ],
        "properties": {
          "businesses": {
            "type": "array",
            "maxItems": 10,
            "description": "Every sponsor the caller is on the team of, closed ones aside: the running ones first (live, paused, suspended), then the ones on their way (under review, changes requested, not approved), then drafts; by name within each. At most 10.",
            "items": {
              "$ref": "#/components/schemas/SponsorMenuBusiness"
            }
          },
          "counter": {
            "type": "boolean",
            "description": "The caller is on the team of a live or paused sponsor, so the account menu offers Counter (fundlyhub.org/counter)."
          }
        }
      },
      "SponsorMenuBusiness": {
        "type": "object",
        "required": [
          "id",
          "slug",
          "name",
          "role",
          "status",
          "logo_url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string",
            "example": "fast-cat-coffee-bar"
          },
          "name": {
            "type": "string",
            "example": "Fast Cat Coffee Bar"
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "manager",
              "cashier"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "waiting_for_owner",
              "under_review",
              "changes_requested",
              "not_approved",
              "live",
              "paused",
              "suspended"
            ],
            "description": "A draft links to where it is being added; anything else to its workspace."
          },
          "logo_url": {
            "type": "string",
            "format": "uri",
            "nullable": true
          }
        }
      },
      "SponsorBadge": {
        "type": "object",
        "description": "What the Proud Sponsor web badge (fundlyhub.org/badge/sponsor/{slug}.svg) shows. `proud_sponsor` while the sponsor is live or paused, linked to its page; `plain` for anything else (suspended, closed, not approved yet, or no such sponsor), drawn as a plain FundlyHub link. A plain answer names nothing.",
        "required": [
          "badge"
        ],
        "properties": {
          "badge": {
            "type": "string",
            "enum": [
              "proud_sponsor",
              "plain"
            ]
          },
          "slug": {
            "type": "string",
            "description": "The current slug, also when the request named an old one. Only with `proud_sponsor`."
          },
          "name": {
            "type": "string",
            "description": "Only with `proud_sponsor`."
          }
        }
      },
      "LocationLabel": {
        "type": "string",
        "nullable": true,
        "description": "The campaign's place as every client prints it (#2090): \"City, ST\" in the US (\"Sacramento, CA\"), \"City, Country\" elsewhere (\"Kyiv, Ukraine\"), never a street, a ZIP or \"USA\". From the city the campaign is placed in, else its geocoded city, else the US city its typed `location` names, else that text without a ZIP or country. Null when it has no location.",
        "example": "Sacramento, CA"
      },
      "FundlyViewerAction": {
        "type": "object",
        "required": [
          "allowed"
        ],
        "properties": {
          "allowed": {
            "type": "boolean"
          },
          "reason": {
            "type": "string",
            "description": "Present when `allowed` is false. A short key the page translates.",
            "enum": [
              "not_owner",
              "staff_only",
              "deleted",
              "in_review",
              "not_live",
              "ended",
              "not_ended",
              "donations_closed",
              "donations_open",
              "hold",
              "has_donations",
              "not_applicable",
              "no_invite",
              "feature_off"
            ]
          }
        }
      },
      "FundlyCurrencyCents": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "currency",
          "cents"
        ],
        "properties": {
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "cents": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          }
        }
      },
      "FundlyPayeeFacts": {
        "type": "object",
        "nullable": true,
        "additionalProperties": false,
        "description": "Private current-recipient and campaign-attributed payout facts. Only the owner, staff or the currently linked beneficiary may receive this object. No bank details, invitation email or account-wide withdrawals. Unavailable facts are null, not zeros. Readiness is the locally observed account state; no Stripe request is made here.",
        "required": [
          "kind",
          "invite_state",
          "has_account",
          "accepted_at",
          "last_sent_at",
          "payout_state",
          "payout_observed_at",
          "campaign_paid_out",
          "next_known_arrival"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "self",
              "person",
              "nonprofit"
            ]
          },
          "invite_state": {
            "type": "string",
            "nullable": true,
            "enum": [
              "pending",
              "accepted",
              null
            ]
          },
          "has_account": {
            "type": "boolean"
          },
          "accepted_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "last_sent_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "payout_state": {
            "type": "string",
            "enum": [
              "unknown",
              "not_set_up",
              "on",
              "paused"
            ]
          },
          "payout_observed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "campaign_paid_out": {
            "type": "array",
            "description": "Confirmed paid bank payouts attributed to this Fundly, separated by currency.",
            "items": {
              "$ref": "#/components/schemas/FundlyCurrencyCents"
            }
          },
          "next_known_arrival": {
            "type": "object",
            "nullable": true,
            "additionalProperties": false,
            "description": "Earliest recorded pending/in-transit payout arrival, never a predicted schedule.",
            "required": [
              "currency",
              "date"
            ],
            "properties": {
              "currency": {
                "type": "string",
                "pattern": "^[A-Z]{3}$"
              },
              "date": {
                "type": "string",
                "format": "date"
              }
            }
          }
        }
      },
      "FundlyOrgAdminFacts": {
        "type": "object",
        "nullable": true,
        "additionalProperties": false,
        "description": "Private facts for this exact nonprofit-beneficiary Fundly. Requires an owner/admin organization role and scoped org.read_donations. Missing access or unavailable facts answer null. Display listing is independent of historical money and impact.",
        "required": [
          "org_id",
          "org_slug",
          "received",
          "receipts_sent",
          "gifts_this_week",
          "period_start",
          "period_end",
          "page_listed",
          "can_manage_listing"
        ],
        "properties": {
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "org_slug": {
            "type": "string"
          },
          "received": {
            "type": "array",
            "description": "Canonical recipient Raised for this Fundly, separated by currency.",
            "items": {
              "$ref": "#/components/schemas/FundlyCurrencyCents"
            }
          },
          "receipts_sent": {
            "type": "integer",
            "minimum": 0,
            "description": "Distinct gifts with confirmed receipt sends in available delivery records; queued attempts are excluded."
          },
          "gifts_this_week": {
            "type": "integer",
            "minimum": 0
          },
          "period_start": {
            "type": "string",
            "format": "date-time",
            "description": "Start of the reporting week in UTC."
          },
          "period_end": {
            "type": "string",
            "format": "date-time",
            "description": "Exclusive end of the reporting week in UTC."
          },
          "page_listed": {
            "type": "boolean"
          },
          "can_manage_listing": {
            "type": "boolean",
            "description": "The organization role can edit its page and holds scoped org.update_settings."
          }
        }
      },
      "FundlyViewer": {
        "type": "object",
        "description": "Detail reads only (#2485): who the caller is to this Fundly and what they may do on its page, computed per request (never cached across callers). Every action carries the rule its own endpoint enforces, so an allowed action is never refused for permission or state: `edit` and `post_update` (the owner; updates switched on), `end` and `stop_donations` (the owner or staff), `reopen_donations` (staff holding `manage_campaigns`), `unpublish` (the owner, nothing collected, no ending recorded), `delete` (the owner or a super admin, nothing collected), `change_beneficiary` (the owner raising for a person or with no beneficiary yet, before any money moves), `resend_beneficiary_invite` (the owner, with a pending invitation). A caller whose block cannot be read gets the guest block. Detail responses are private, no-store and vary by Cookie and Authorization; private facts never enter the internally cached campaign row or public listing projection.",
        "required": [
          "role",
          "roles",
          "donated_cents",
          "donated_at",
          "beneficiary_invite",
          "staff",
          "payee",
          "org_admin",
          "actions"
        ],
        "properties": {
          "role": {
            "type": "string",
            "description": "The most specific role, by priority staff, owner, beneficiary, org_admin, ambassador, donor, guest.",
            "enum": [
              "guest",
              "donor",
              "owner",
              "beneficiary",
              "org_admin",
              "ambassador",
              "staff"
            ]
          },
          "roles": {
            "type": "array",
            "description": "Every role that applies, most specific first; `[guest]` when none does. `org_admin` is an owner or admin of the Fundly's organization team; `ambassador` holds a referral code for it or a live endorsement of it; `beneficiary` is its linked account or the verified holder of its pending invitation; `donor` gave at least one completed gift.",
            "items": {
              "type": "string",
              "enum": [
                "guest",
                "donor",
                "owner",
                "beneficiary",
                "org_admin",
                "ambassador",
                "staff"
              ]
            }
          },
          "donated_cents": {
            "type": "integer",
            "nullable": true,
            "description": "What the caller gave in completed gifts to this Fundly, in cents, as their Given (the gift and their tip). 0 for a signed-in caller who has not given; null signed out."
          },
          "donated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Their latest completed gift to this Fundly; null with none."
          },
          "beneficiary_invite": {
            "type": "object",
            "nullable": true,
            "description": "The owner and staff only (null for everyone else, and with no invitation): the person beneficiary invitation, pending or accepted by the current beneficiary. Never the email.",
            "properties": {
              "state": {
                "type": "string",
                "enum": [
                  "pending",
                  "accepted"
                ]
              },
              "has_account": {
                "type": "boolean",
                "description": "A FundlyHub account holds the invited address, verified."
              },
              "sent_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "When the invitation email last went out."
              }
            }
          },
          "payee": {
            "$ref": "#/components/schemas/FundlyPayeeFacts"
          },
          "org_admin": {
            "$ref": "#/components/schemas/FundlyOrgAdminFacts"
          },
          "staff": {
            "type": "object",
            "nullable": true,
            "description": "Staff only, else null.",
            "properties": {
              "ai_decision": {
                "type": "string",
                "nullable": true
              },
              "payout_hold": {
                "type": "boolean",
                "description": "The owner's payouts are held (no Stripe account, or payouts not enabled)."
              },
              "open_reports": {
                "type": "integer",
                "minimum": 0,
                "description": "Reports against this Fundly waiting for review."
              },
              "featured_on_causes": {
                "type": "boolean",
                "description": "Current saved staff priority flag; omitted when metadata cannot be read."
              },
              "can_feature": {
                "type": "boolean",
                "description": "The caller holds manage_campaigns, as required by the metadata writer."
              }
            }
          },
          "actions": {
            "type": "object",
            "required": [
              "edit",
              "end",
              "stop_donations",
              "reopen_donations",
              "unpublish",
              "delete",
              "change_beneficiary",
              "post_update",
              "resend_beneficiary_invite"
            ],
            "properties": {
              "edit": {
                "$ref": "#/components/schemas/FundlyViewerAction"
              },
              "end": {
                "$ref": "#/components/schemas/FundlyViewerAction"
              },
              "stop_donations": {
                "$ref": "#/components/schemas/FundlyViewerAction"
              },
              "reopen_donations": {
                "$ref": "#/components/schemas/FundlyViewerAction"
              },
              "unpublish": {
                "$ref": "#/components/schemas/FundlyViewerAction"
              },
              "delete": {
                "$ref": "#/components/schemas/FundlyViewerAction"
              },
              "change_beneficiary": {
                "$ref": "#/components/schemas/FundlyViewerAction"
              },
              "post_update": {
                "$ref": "#/components/schemas/FundlyViewerAction"
              },
              "resend_beneficiary_invite": {
                "$ref": "#/components/schemas/FundlyViewerAction"
              }
            }
          }
        }
      },
      "FundraisingState": {
        "type": "object",
        "description": "A campaign's fundraising state, computed by the server for every client (#2039). Clients render it and never re-derive it: ended, why, whether donations are open, what was raised and what the donate button does.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "pending",
              "rejected",
              "active",
              "paused",
              "ended"
            ]
          },
          "kind": {
            "type": "string",
            "enum": [
              "cause",
              "project"
            ]
          },
          "is_ended": {
            "type": "boolean",
            "description": "True when the status is ended, and for a live campaign whose end date has passed."
          },
          "ended_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "end_reason": {
            "type": "string",
            "nullable": true,
            "enum": [
              "goal_reached",
              "deadline",
              "organizer",
              "admin",
              "account_deletion",
              "unknown",
              null
            ]
          },
          "accepting_donations": {
            "type": "boolean",
            "description": "An ended campaign takes donations until its organizer or staff stop them. False for a campaign of a suspended or deleted organization, and for one raising for a person who cannot receive a gift yet (no linked account or pending invitation, or a linked account that is inactive or being deleted), both of which the checkout refuses."
          },
          "donations_closed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "raised_cents": {
            "type": "integer"
          },
          "goal_cents": {
            "type": "integer"
          },
          "percent_funded": {
            "type": "integer",
            "description": "Whole percent, not capped at 100."
          },
          "goal_reached": {
            "type": "boolean"
          },
          "donor_count": {
            "type": "integer"
          },
          "days_left": {
            "type": "integer",
            "nullable": true
          },
          "donate_action": {
            "type": "string",
            "enum": [
              "donate",
              "find_similar",
              "paused",
              "none"
            ],
            "description": "`donate`: show Donate. `find_similar`: donations are stopped (or the organization was deleted). `paused`: a disabled Donate button, for a campaign paused for review, one of a suspended organization, or one waiting for its person beneficiary to be linked, invited or reactivated. `none`: not public yet, or deleted."
          },
          "outcome": {
            "type": "string",
            "nullable": true,
            "enum": [
              "ended_goal_reached",
              "ended_deadline",
              "ended_by_organizer",
              "ended_by_admin",
              "ended",
              "closed_by_organizer",
              "closed_by_admin",
              "closed",
              null
            ],
            "description": "Why an ended campaign stopped (#2090); null while it is live. When donations were stopped, who stopped them: `closed_by_organizer`, `closed_by_admin` (FundlyHub staff), or `closed` when not known. Otherwise how it ended: at its goal, at its deadline, by the organizer, by FundlyHub staff, or `ended` when not known. An account deletion reads as `ended` or `closed`."
          },
          "badge": {
            "type": "string",
            "nullable": true,
            "enum": [
              "fully_funded",
              "closed_by_organizer",
              "closed_by_admin",
              "closed",
              "ended_deadline",
              "ended_by_organizer",
              "ended_by_admin",
              "ended",
              "paused",
              "almost_there",
              "just_launched",
              null
            ],
            "description": "THE status label every client shows for the campaign (#2090), decided here so a card, a list and the campaign page never disagree. Precedence: `fully_funded` (raised at least the goal, ended or not); for an ended campaign, its `outcome` (`ended_goal_reached` below the goal after a refund reads `ended`); `paused` (under review, its organization is suspended, or its person beneficiary cannot receive a gift yet); for a live campaign, `almost_there` (80% of the goal) or `just_launched` (public for under 7 days); else null. Show \"Accepting gifts\" beside it when `is_ended` and `accepting_donations` are both true."
          },
          "paused_reason": {
            "type": "string",
            "nullable": true,
            "enum": [
              "review",
              "organization",
              "beneficiary",
              null
            ],
            "description": "Why `donate_action` is `paused` (#2177); null whenever it is not. `review`: FundlyHub staff paused the campaign for review. `organization`: its organization is suspended, or is a non-profit whose donations are paused. `beneficiary`: it raises for a person who cannot receive a gift yet; nobody is reviewing it, and donations open as soon as the organizer links or invites the person (or their linked account is active again). Clients show a note that matches the reason, and never tell a donor or the organizer that a `beneficiary` campaign is under review."
          }
        }
      },
      "Fundraiser": {
        "type": "object",
        "description": "A campaign, as the detail reads (`GET /fundraisers/{id}`, `/fundraisers/slug/{slug}`) return it. The listing (`GET /fundraisers`) returns a shorter `FundraiserCard` instead. Fields marked *slug read only* are absent from `GET /fundraisers/{id}`. The campaign's owner also receives the private fields they entered (such as `beneficiary_contact`) and their `trustStatus`; nobody else does.",
        "properties": {
          "media": {
            "type": "array",
            "nullable": true,
            "description": "Cover-first canonical gallery; null is legacy-only, empty must not fall back to legacy URLs.",
            "items": {
              "$ref": "#/components/schemas/CampaignGalleryMedia"
            }
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string",
            "example": "Help Support Local Food Bank"
          },
          "slug": {
            "type": "string",
            "example": "help-support-local-food-bank"
          },
          "summary": {
            "type": "string",
            "nullable": true,
            "description": "Short plain-text blurb for cards and listings."
          },
          "story_html": {
            "type": "string",
            "nullable": true,
            "description": "The campaign body, sanitised HTML."
          },
          "goal_amount_cents": {
            "type": "integer",
            "description": "Fundraising goal in CENTS. `5000000` is $50,000.00. This was published as `goal` in dollars before the API unified on a single money unit; a client that still reads `goal` will now read `undefined` rather than a figure a hundred times too small.",
            "example": 5000000
          },
          "total_raised_cents": {
            "type": "integer",
            "description": "Amount raised so far, in CENTS. `1250000` is $12,500.00. Published as `raised` in dollars before the cents cutover. *Slug read only.*",
            "example": 1250000
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "pending",
              "active",
              "paused",
              "ended",
              "rejected"
            ],
            "description": "`pending` is awaiting review, `ended` is closed (shown as \"Closed\" in the app), `rejected` is set only by FundlyHub review.",
            "example": "active"
          },
          "visibility": {
            "type": "string",
            "enum": [
              "public",
              "unlisted",
              "private"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "personal",
              "for_others",
              "charity"
            ]
          },
          "is_project": {
            "type": "boolean"
          },
          "category": {
            "type": "string",
            "nullable": true,
            "description": "The category's id (as a string) or slug."
          },
          "category_name": {
            "type": "string",
            "nullable": true,
            "description": "*Slug read only.*"
          },
          "tags": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            }
          },
          "cover_image": {
            "type": "string",
            "nullable": true
          },
          "cover_image_focal_x": {
            "type": "number",
            "nullable": true
          },
          "cover_image_focal_y": {
            "type": "number",
            "nullable": true
          },
          "images": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            }
          },
          "video_url": {
            "type": "string",
            "nullable": true
          },
          "location": {
            "type": "string",
            "nullable": true,
            "example": "Austin, TX"
          },
          "location_label": {
            "$ref": "#/components/schemas/LocationLabel"
          },
          "beneficiary_user_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Active FundlyHub account receiving personal gifts for type for_others. Mutually exclusive with an organization or invitation email. Never falls back to the organizer for a pending invitation."
          },
          "beneficiary_invite_email": {
            "type": "string",
            "format": "email",
            "maxLength": 254,
            "nullable": true,
            "description": "Invite a person by email with beneficiary_name and type for_others. Creation does not wait for acceptance. The organizer must have verified email. Held gifts belong to this pending identity; the recipient must sign in, verify the matching email and accept before normal Stripe payout onboarding. Returned only to the organizer on private campaign detail reads; never public."
          },
          "beneficiary_name": {
            "type": "string",
            "nullable": true
          },
          "beneficiary_contact": {
            "type": "string",
            "nullable": true,
            "description": "How to reach the beneficiary. Returned only to the campaign's owner; absent for every other caller."
          },
          "owner_user_id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "profiles": {
            "type": "object",
            "nullable": true,
            "description": "The owner. *Slug read only.*",
            "properties": {
              "name": {
                "type": "string"
              },
              "avatar": {
                "type": "string",
                "nullable": true
              },
              "email_verified": {
                "type": "boolean"
              },
              "profile_slug": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "donor_count": {
            "type": "integer",
            "description": "Unique donors. On the slug read this is the live count; on `GET /fundraisers/{id}` it is a stored counter."
          },
          "donation_count": {
            "type": "integer",
            "description": "*Slug read only.*"
          },
          "percentage_funded": {
            "type": "number",
            "description": "*Slug read only.*"
          },
          "shares_count": {
            "type": "integer",
            "description": "*Slug read only.*"
          },
          "source_language": {
            "type": "string",
            "description": "The language the campaign was written in (`en`, `ru`, `uk`, `es`)."
          },
          "end_date": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "approved_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "goal_reached_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "cover_tint": {
            "type": "string",
            "nullable": true,
            "pattern": "^#[0-9A-F]{6}$",
            "description": "The campaign page's background colour: a very light tint taken from the cover photo's most characteristic hue, as an upper-case `#RRGGBB` (a black-and-white cover gives `#F9F9FA`). Computed by FundlyHub shortly after the cover is set or changed, so it is `null` until then (and when there is no cover); fall back to your own plain background while it is `null`. Every value is light enough for dark text.",
            "example": "#F2FAFC"
          },
          "donations_last_24h": {
            "type": "integer",
            "minimum": 0,
            "description": "Completed donations made to this campaign in the last 24 hours. Pending, failed and refunded donations are not counted. Up to 30 seconds behind.",
            "example": 12
          },
          "success_story_slug": {
            "type": "string",
            "nullable": true,
            "description": "Detail reads only. The Fundly's success story page, `/success-stories/{success_story_slug}`, while the Fundly is a public success story (ended, raised more than $0, passes the safety gates, not hidden by staff); `null` otherwise. Read live on every request.",
            "example": "help-support-local-food-bank"
          },
          "city": {
            "$ref": "#/components/schemas/FundraiserCity"
          },
          "place_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "The Fundly's city (#2064), from the geocode of `location`. Cleared when `location` changes."
          },
          "viewer": {
            "$ref": "#/components/schemas/FundlyViewer"
          },
          "trustStatus": {
            "type": "object",
            "description": "Detail reads only, and only when the caller owns the campaign: the review verdict and what the owner should do about it.",
            "properties": {
              "aiDecision": {
                "type": "string"
              },
              "trustScore": {
                "type": "integer"
              },
              "payoutHold": {
                "type": "boolean"
              },
              "rejectionReasons": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "userMessages": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "FundraiserCard": {
        "type": "object",
        "description": "One item of the public listing (`GET /fundraisers`): the campaign's public fields, with the owner, the category name and the raised figures joined in. It carries no story body (`story_html`) and none of the owner-only fields; read `GET /fundraisers/slug/{slug}` for the whole campaign.",
        "properties": {
          "media": {
            "type": "array",
            "nullable": true,
            "description": "Cover-first canonical gallery; null is legacy-only, empty must not fall back to legacy URLs.",
            "items": {
              "$ref": "#/components/schemas/CampaignGalleryMedia"
            }
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string",
            "example": "Help Support Local Food Bank"
          },
          "slug": {
            "type": "string",
            "example": "help-support-local-food-bank"
          },
          "summary": {
            "type": "string",
            "nullable": true
          },
          "goal_amount_cents": {
            "type": "integer",
            "description": "Fundraising goal in CENTS.",
            "example": 5000000
          },
          "total_raised_cents": {
            "type": "integer",
            "description": "Amount raised so far, in CENTS.",
            "example": 1250000
          },
          "donor_count": {
            "type": "integer",
            "description": "Unique donors."
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "ended"
            ],
            "description": "The listing only ever contains published campaigns."
          },
          "visibility": {
            "type": "string",
            "enum": [
              "public"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "personal",
              "for_others",
              "charity"
            ]
          },
          "is_project": {
            "type": "boolean"
          },
          "category": {
            "type": "string",
            "nullable": true,
            "description": "The category's id (as a string) or slug."
          },
          "category_name": {
            "type": "string",
            "nullable": true
          },
          "tags": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            }
          },
          "cover_image": {
            "type": "string",
            "nullable": true
          },
          "cover_image_focal_x": {
            "type": "number",
            "nullable": true
          },
          "cover_image_focal_y": {
            "type": "number",
            "nullable": true
          },
          "images": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            }
          },
          "gallery": {
            "type": "array",
            "maxItems": 6,
            "description": "The campaign's photos for a listing tile, at most six: the cover first, then its other public images in gallery order, each URL once. Images only — no videos, no photos taken down, no uploads still processing. Empty when the campaign has no photo. Present on `GET /fundraisers` items, and on the campaign cards of `GET /users/{id}/campaigns`, `GET /users/{id}/donation-activity` and `GET /fundraisers/{id}/related`; treat a missing field as the cover alone.",
            "items": {
              "type": "string"
            },
            "example": [
              "https://cdn.fundlyhub.org/uploads/fundraisers/cover.jpg",
              "https://cdn.fundlyhub.org/uploads/fundraisers/second.jpg"
            ]
          },
          "video_url": {
            "type": "string",
            "nullable": true
          },
          "location": {
            "type": "string",
            "nullable": true,
            "description": "The location as the creator typed it (free text)."
          },
          "location_label": {
            "$ref": "#/components/schemas/LocationLabel"
          },
          "location_city": {
            "type": "string",
            "nullable": true,
            "description": "The city the campaign is in (its English name): the US city its `location` names, else the city a server-side geocode of the `location` finds. `null` until the location is geocoded, or when it is in no city (not a place, a whole state or country, or a rural point no city is named for).",
            "example": "Sacramento"
          },
          "location_region": {
            "type": "string",
            "nullable": true,
            "description": "The city's state or province: its ISO 3166-2 letter code where there is one (`CA`), otherwise its name.",
            "example": "CA"
          },
          "location_country": {
            "type": "string",
            "nullable": true,
            "description": "The city's ISO 3166-1 alpha-2 country code.",
            "example": "US"
          },
          "location_lat": {
            "type": "number",
            "format": "double",
            "nullable": true,
            "description": "Latitude of the CITY (its centroid), never of a street address, to at most 2 decimal places (about 1 km). `null` when the campaign is in no city.",
            "example": 38.58
          },
          "location_lng": {
            "type": "number",
            "format": "double",
            "nullable": true,
            "description": "Longitude of the city, as `location_lat`.",
            "example": -121.49
          },
          "distance_mi": {
            "type": "number",
            "format": "double",
            "description": "Miles from the `near` point to the campaign's city, 1 decimal. Present only on `GET /fundraisers?near=…` items.",
            "example": 3.2
          },
          "beneficiary_name": {
            "type": "string",
            "nullable": true
          },
          "owner_user_id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "profiles": {
            "type": "object",
            "nullable": true,
            "description": "The owner, as shown on a card.",
            "properties": {
              "name": {
                "type": "string"
              },
              "avatar": {
                "type": "string",
                "nullable": true
              },
              "email_verified": {
                "type": "boolean"
              },
              "profile_slug": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "source_language": {
            "type": "string",
            "description": "The language the campaign was written in (`en`, `ru`, `uk`, `es`)."
          },
          "translation_source": {
            "type": "string",
            "enum": [
              "source",
              "machine",
              "human"
            ],
            "description": "Present when the card was localised: whether `title` and `summary` are the original text, a machine translation or a human one."
          },
          "original_title": {
            "type": "string",
            "nullable": true,
            "description": "The untranslated title, when `title` is a translation."
          },
          "original_summary": {
            "type": "string",
            "nullable": true,
            "description": "The untranslated summary, when `summary` is a translation."
          },
          "end_date": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "approved_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "FundraiserCreate": {
        "description": "Body for `POST /fundraisers`.\n\nThree of the four fields this previously documented as REQUIRED —\n`description`, `goal`, `category_id` — are not fields the API has.\nA request built from the old shape failed validation outright.\nThe real required set is `title`, `slug` and `goal_amount_cents`.\n\n`owner_user_id` is set from the access token; it is stripped from the\nbody if sent, so a caller cannot create a campaign owned by someone\nelse.\n",
        "type": "object",
        "required": [
          "title",
          "slug",
          "goal_amount_cents"
        ],
        "properties": {
          "media": {
            "$ref": "#/components/schemas/CampaignEditorMedia"
          },
          "title": {
            "type": "string",
            "minLength": 3,
            "maxLength": 200,
            "example": "Help Support Local Food Bank"
          },
          "slug": {
            "type": "string",
            "minLength": 3,
            "maxLength": 100,
            "pattern": "^[a-z0-9-]+$",
            "description": "Lowercase letters, digits and hyphens. Check availability first with `GET /fundraisers/check-slug/{slug}`.",
            "example": "help-support-local-food-bank"
          },
          "goal_amount_cents": {
            "type": "integer",
            "minimum": 1,
            "maximum": 999999999999,
            "description": "Fundraising goal in CENTS. `5000000` is $50,000.00. Renamed from `goal_amount`, which was in dollars until the API unified on a single money unit — the rename is deliberate, so a client still sending `goal_amount` gets a validation error rather than a campaign with a goal a hundred times too small.",
            "example": 5000000
          },
          "summary": {
            "type": "string",
            "maxLength": 500,
            "description": "Short plain-text blurb for cards and listings."
          },
          "story_html": {
            "type": "string",
            "description": "The campaign body. Sanitised server-side."
          },
          "currency": {
            "type": "string",
            "default": "USD"
          },
          "category": {
            "type": "string",
            "description": "Category slug. Note this is a string, not the category's id."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cover_image": {
            "type": "string",
            "format": "uri"
          },
          "images": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "video_url": {
            "type": "string",
            "format": "uri"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "active",
              "pending",
              "paused",
              "ended"
            ],
            "default": "draft",
            "description": "`rejected` cannot be set here — a campaign cannot self-reject. A campaign may also be moved to `pending` by review regardless of what is requested. Only an explicit `draft` skips the publish gate, and only an explicit `draft` is accepted from a caller whose email is not verified."
          },
          "visibility": {
            "type": "string",
            "enum": [
              "public",
              "unlisted",
              "private"
            ],
            "default": "public"
          },
          "type": {
            "type": "string",
            "enum": [
              "personal",
              "for_others",
              "charity"
            ],
            "default": "personal"
          },
          "is_project": {
            "type": "boolean",
            "default": false
          },
          "beneficiary_user_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Active FundlyHub account receiving personal gifts for type for_others. Mutually exclusive with an organization or invitation email. Never falls back to the organizer for a pending invitation."
          },
          "beneficiary_invite_email": {
            "type": "string",
            "format": "email",
            "maxLength": 254,
            "nullable": true,
            "description": "Invite a person by email with beneficiary_name and type for_others. Creation does not wait for acceptance. The organizer must have verified email. Held gifts belong to this pending identity; the recipient must sign in, verify the matching email and accept before normal Stripe payout onboarding. Returned only to the organizer on private campaign detail reads; never public."
          },
          "beneficiary_name": {
            "type": "string"
          },
          "beneficiary_contact": {
            "type": "string"
          },
          "location": {
            "type": "string"
          },
          "end_date": {
            "type": "string",
            "format": "date",
            "description": "A real calendar date (`YYYY-MM-DD`). Empty string or null means no deadline; anything unparseable is a `400`."
          },
          "org_id": {
            "type": "string",
            "format": "uuid",
            "description": "Create on behalf of an organization the caller belongs to."
          },
          "cover_image_focal_x": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Manual focal-point override for the cover crop. Computed from the image when omitted."
          },
          "cover_image_focal_y": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "scrape_token": {
            "type": "string",
            "description": "The one-time token `POST /ai/scrape-campaign-url` issues with an imported campaign. Send it back unchanged when creating that campaign. Not stored."
          }
        }
      },
      "FundraiserUpdate": {
        "description": "Body for `PATCH /fundraisers/{id}`. Every field of `FundraiserCreate`\nexcept `owner_user_id` (stripped if sent), all optional. Only the\nfields sent are written.\n\nThe previously documented `description` field does not exist — the\ncampaign text is `summary` and `story_html` — and `completed` and\n`archived` were never statuses.\n",
        "type": "object",
        "properties": {
          "media": {
            "$ref": "#/components/schemas/CampaignEditorMedia"
          },
          "slug": {
            "type": "string",
            "description": "The page's link (#2488). A published campaign keeps its earlier links: `GET /fundraisers/slug/{slug}` answers an old one with the campaign under its current slug, and the /f and /p pages redirect to it. No other campaign can take an old link, though its own campaign may take it back. A link that is taken answers `409` with code `SLUG_TAKEN`. A draft that was never published keeps no old links."
          },
          "scrape_token": {
            "type": "string",
            "description": "The one-use token `POST /ai/scrape-campaign-url` returned, sent with the publish of a campaign imported from another site: a reasonability or AI reject then sends it to review (`pending`) instead of answering `403`, as on a first publish. Never stored."
          },
          "title": {
            "type": "string",
            "minLength": 3,
            "maxLength": 200
          },
          "summary": {
            "type": "string",
            "maxLength": 500
          },
          "story_html": {
            "type": "string"
          },
          "goal_amount_cents": {
            "type": "integer",
            "minimum": 1,
            "description": "Fundraising goal in CENTS — same unit and same name as `FundraiserCreate.goal_amount_cents`. `5000000` is $50,000.00. Documented as `goal` in dollars before the cents cutover; the update handler reads `goal_amount_cents` and ignores `goal`.",
            "example": 5000000
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "active",
              "pending",
              "paused",
              "ended"
            ],
            "description": "`active` publishes (running the publish gate), `draft` unpublishes and is refused with `400` once the campaign has collected money."
          },
          "visibility": {
            "type": "string",
            "enum": [
              "public",
              "unlisted",
              "private"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "personal",
              "for_others",
              "charity"
            ]
          },
          "is_project": {
            "type": "boolean"
          },
          "currency": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cover_image": {
            "type": "string"
          },
          "images": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "video_url": {
            "type": "string"
          },
          "beneficiary_user_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Active FundlyHub account receiving personal gifts for type for_others. Mutually exclusive with an organization or invitation email. Never falls back to the organizer for a pending invitation."
          },
          "beneficiary_invite_email": {
            "type": "string",
            "format": "email",
            "maxLength": 254,
            "nullable": true,
            "description": "Invite a person by email with beneficiary_name and type for_others. Creation does not wait for acceptance. The organizer must have verified email. Held gifts belong to this pending identity; the recipient must sign in, verify the matching email and accept before normal Stripe payout onboarding. Returned only to the organizer on private campaign detail reads; never public."
          },
          "beneficiary_name": {
            "type": "string"
          },
          "beneficiary_contact": {
            "type": "string"
          },
          "location": {
            "type": "string"
          },
          "end_date": {
            "type": "string",
            "format": "date"
          },
          "org_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Canonical nonprofit FK with type charity. Null clears nonprofit attribution when switching to personal or for_others. Live team authority is required for a new nonprofit; any payment activity locks recipient changes."
          },
          "cover_image_focal_x": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "cover_image_focal_y": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        }
      },
      "DonationReceiptContext": {
        "type": "object",
        "nullable": true,
        "description": "Server-derived destination. Campaign/project takes precedence when fundraiser_id is present. A nonprofit general-fund context does not itself establish payment completion or tax deductibility. Null means the target cannot be established; never infer a campaign from its absence.",
        "required": [
          "kind",
          "id",
          "name",
          "slug"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "campaign",
              "nonprofit_general_fund"
            ]
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string",
            "description": "Current canonical target slug when available."
          },
          "is_project": {
            "type": "boolean",
            "description": "Campaign/project routing; applies to campaign contexts."
          },
          "is_church": {
            "type": "boolean",
            "description": "Server-derived church classification; applies to nonprofit general-fund contexts."
          },
          "frequency": {
            "type": "string",
            "enum": [
              "once",
              "monthly"
            ],
            "description": "Applies to nonprofit general-fund contexts",
            "including monthly renewal receipts.": null
          }
        }
      },
      "Donation": {
        "type": "object",
        "description": "A donation record.\n**Every money field is an integer number of CENTS** — the same unit Stripe uses, and the unit the whole API now speaks. `5000` is $50.00.\nEndpoints return different projections: the public donor wall (`GET /fundraisers/{fundraiserId}/donations`) omits every donor identifier except the display name and avatar, returns **net** amounts (gross minus the Stripe fee) in `amount_cents`, and strips the name and avatar entirely from anonymous gifts.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "fundraiser_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "donor_user_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Derived from the session; never accepted from the client."
          },
          "donor_name": {
            "type": "string",
            "nullable": true
          },
          "donor_avatar": {
            "type": "string",
            "nullable": true,
            "description": "Donor-wall projection only, resolved from the donor's profile."
          },
          "amount_cents": {
            "type": "integer",
            "example": 5000,
            "description": "Gross donation amount in cents ($50.00 here); net of the Stripe fee on the donor-wall projection. Renamed from `amount`, which was in dollars until the API moved to a single money unit."
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "tip_amount_cents": {
            "type": "integer",
            "example": 500,
            "description": "Optional tip to FundlyHub, in cents. Renamed from `tip_amount` (dollars)."
          },
          "fee_amount_cents": {
            "type": "integer",
            "example": 175,
            "description": "Stripe processing fee in cents. Renamed from `fee_amount` (dollars)."
          },
          "net_amount_cents": {
            "type": "integer",
            "example": 4825,
            "description": "`amount_cents - fee_amount_cents`, in cents. Computed by the database, never accepted from a client."
          },
          "payment_status": {
            "type": "string",
            "enum": [
              "paid",
              "refunded",
              "failed",
              "pending"
            ],
            "description": "The gift's state. Written by the Stripe-verified webhook and `POST /payments/confirm` only — clients cannot set it."
          },
          "payment_provider": {
            "type": "string",
            "nullable": true
          },
          "payment_intent_id": {
            "type": "string",
            "nullable": true
          },
          "receipt_id": {
            "type": "string",
            "nullable": true
          },
          "comment": {
            "type": "string",
            "nullable": true,
            "description": "The donor's public message."
          },
          "is_anonymous": {
            "type": "boolean"
          },
          "anonymous_key": {
            "type": "string",
            "nullable": true,
            "description": "Opaque key for the anonymous identity behind this gift — the same value on every gift the same anonymous donor made, so a client can show them as one person (one generated name, one avatar colour) without learning who they are. It is a keyed hash, not an id, and cannot be turned back into a person. Null on a gift that shows a name."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "DonationCreate": {
        "description": "Body for `POST /donations`.\n\n**Amounts are integer CENTS.** They were dollars on this endpoint until\nthe API unified on one money unit; the fields were renamed\n`amount` → `amount_cents` and `tip_amount` → `tip_amount_cents` so that\nan un-updated client fails loudly on the missing required field rather\nthan recording a donation a hundred times too small.\n\nBoth fields must be whole numbers. `50.00` is rejected: under the old\ncontract it meant fifty dollars, and there is no reading of it that is\na valid number of cents.\n\nThe donor is taken from the access token, not the body —\n`donor_user_id` is ignored if sent.\n",
        "type": "object",
        "required": [
          "fundraiser_id",
          "amount_cents"
        ],
        "properties": {
          "fundraiser_id": {
            "type": "string",
            "format": "uuid"
          },
          "amount_cents": {
            "type": "integer",
            "minimum": 1,
            "description": "Donation amount in cents. `5000` is $50.00.",
            "example": 5000
          },
          "currency": {
            "type": "string",
            "default": "USD"
          },
          "tip_amount_cents": {
            "type": "integer",
            "minimum": 0,
            "default": 0,
            "description": "Optional tip to FundlyHub, in cents.",
            "example": 500
          },
          "comment": {
            "type": "string",
            "maxLength": 1000,
            "description": "The donor's public message. Documented as `message` until this was corrected — the handler only ever read `comment`, so anything sent as `message` was silently dropped and the donation was recorded without it."
          },
          "donor_name": {
            "type": "string"
          },
          "donor_email": {
            "type": "string",
            "format": "email"
          },
          "is_anonymous": {
            "type": "boolean",
            "default": false
          },
          "payment_provider": {
            "type": "string"
          },
          "payment_intent_id": {
            "type": "string"
          }
        }
      },
      "Category": {
        "type": "object",
        "description": "A fundraiser category. Counts and totals are not part of this object — they come from `/categories/stats` and `/categories/{id}/stats`.",
        "properties": {
          "id": {
            "type": "integer",
            "example": 3
          },
          "name": {
            "type": "string",
            "example": "Medical"
          },
          "slug": {
            "type": "string",
            "example": "medical"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "icon": {
            "type": "string",
            "nullable": true
          },
          "color": {
            "type": "string",
            "nullable": true
          },
          "display_order": {
            "type": "integer"
          }
        }
      },
      "Organization": {
        "type": "object",
        "description": "An organization's public fields, as `GET /organizations` and `GET /organizations/{id}` return them. There is no `name`, `verified` or `owner_id`: the name is `legal_name` (with an optional `dba_name`), verification is `verification_status`, and ownership is an `org_owner` role assignment rather than a field.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "legal_name": {
            "type": "string",
            "example": "Local Food Bank Foundation"
          },
          "dba_name": {
            "type": "string",
            "nullable": true
          },
          "slug": {
            "type": "string",
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "mission": {
            "type": "string",
            "nullable": true
          },
          "website": {
            "type": "string",
            "nullable": true
          },
          "logo": {
            "type": "string",
            "nullable": true
          },
          "banner_image": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "categories": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            }
          },
          "verification_status": {
            "type": "string",
            "description": "`pending`, `approved`, `verified`, `rejected` or `suspended`; public reads only ever see `approved` and `verified`."
          },
          "kind": {
            "type": "string",
            "enum": [
              "company",
              "conglomerate"
            ]
          },
          "parent_organization_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "OrganizationCreate": {
        "type": "object",
        "description": "Body for `POST /organizations`.",
        "required": [
          "legal_name"
        ],
        "properties": {
          "legal_name": {
            "type": "string"
          },
          "ein": {
            "type": "string",
            "example": "12-3456789"
          },
          "country": {
            "type": "string"
          },
          "website": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "kind": {
            "type": "string",
            "enum": [
              "company",
              "conglomerate"
            ]
          },
          "parent_organization_id": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "UserProfile": {
        "type": "object",
        "description": "A public profile, as `GET /users/{id}` returns it. The picture is `avatar` (not `avatar_url`), and `email` is present only on the caller's own profile.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "The name the person gave, or `null` when they have not set one. Never derived from their email address."
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "avatar": {
            "type": "string",
            "nullable": true
          },
          "bio": {
            "type": "string",
            "nullable": true
          },
          "location": {
            "type": "string",
            "nullable": true
          },
          "website": {
            "type": "string",
            "nullable": true
          },
          "profile_slug": {
            "type": "string"
          },
          "profile_visibility": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "description": "One row of a search response.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Entity id; `guest:<key>` or `anon:<key>` for a donor row."
          },
          "type": {
            "type": "string",
            "enum": [
              "campaign",
              "user",
              "organization",
              "donor",
              "city",
              "community",
              "event"
            ]
          },
          "title": {
            "type": "string",
            "nullable": true,
            "description": "Null only on an anonymous donor row: that donor's display name is a localized alias the client derives from `anonymousKey`, so the row and the donor page never disagree about what to call somebody."
          },
          "subtitle": {
            "type": "string",
            "nullable": true
          },
          "link": {
            "type": "string",
            "description": "Relative path to the matched entity."
          },
          "image": {
            "type": "string",
            "nullable": true
          },
          "anonymousKey": {
            "type": "string",
            "nullable": true,
            "description": "Opaque anonymous identity key. Anonymous donor rows only."
          },
          "donorKind": {
            "type": "string",
            "nullable": true,
            "enum": [
              "guest",
              "anon"
            ],
            "description": "Which donor scope the row came from. Donor rows only."
          },
          "given": {
            "type": "integer",
            "description": "Donor rows only. Minor units this identity gave — what its gifts raised, net of fees, tips excluded (each gift's ledger credit less its Stripe fee), over its paid and refunded gifts to public campaigns — the same figure the leaderboard row and `/donors/{kind}/{key}` report. Sent as a number rather than as a rendered string so the client formats it in the reader's own language and in the currency below."
          },
          "gifts": {
            "type": "integer",
            "description": "Donor rows only. The gifts behind `given` (paid or refunded, to public campaigns)."
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "description": "ISO 4217 for `given`, from the identity's most recent gift. Donor rows only; null when the rows carried none. Minor units are the currency's own, so JPY 5000 is ¥5,000 and not ¥50.00."
          },
          "handle": {
            "type": "string",
            "description": "User rows only. The profile's handle (`profile_slug`), so the row can show what an `@handle` query matched."
          },
          "isPrivate": {
            "type": "boolean",
            "description": "User rows only. A private profile is findable by name, but its row carries no bio and was not matched on one."
          },
          "highlights": {
            "type": "object",
            "additionalProperties": true,
            "description": "Extra display fields — e.g. an organization row's `website`; a campaign row's `category` and `location` (its `location_label`)."
          },
          "location_label": {
            "$ref": "#/components/schemas/LocationLabel"
          },
          "fundraising": {
            "allOf": [
              {
                "$ref": "#/components/schemas/FundraisingState"
              }
            ],
            "description": "Campaign rows (#2090). The campaign card's state; show `badge` as its status."
          },
          "slug": {
            "type": "string",
            "description": "City and community rows. The city's slug (the anchor's on a metro row), or the community's."
          },
          "scope_href": {
            "type": "string",
            "description": "City and community rows. The /leaderboard scope, e.g. `/leaderboard?city=sacramento-ca&area=1`."
          },
          "impact_cents": {
            "type": "integer",
            "description": "City and community rows. City or Community impact, all time, each settled gift once."
          },
          "area": {
            "type": "boolean",
            "description": "City rows. True on a metro row (the anchor and its member cities)."
          },
          "label": {
            "type": "string",
            "description": "City rows. `Sacramento, CA` in the US, `Kyiv, Ukraine` elsewhere."
          },
          "region_name": {
            "type": "string",
            "nullable": true,
            "description": "City rows. The state spelled out in the US, else the region as stored."
          },
          "country": {
            "type": "string",
            "description": "City rows. ISO 3166-1 alpha-2."
          },
          "place_count": {
            "type": "integer",
            "nullable": true,
            "description": "City rows. Cities in the metro (anchor included) on a metro row, else null."
          },
          "donors": {
            "type": "integer",
            "nullable": true,
            "description": "City rows. Distinct donors who live there (signed in, guest or anonymous); null when none."
          },
          "fundlies": {
            "type": "integer",
            "description": "City rows. Verified Fundlies started there."
          },
          "member_count": {
            "type": "integer",
            "description": "Community rows. Active members."
          },
          "city_text": {
            "type": "string",
            "nullable": true,
            "description": "Community rows. The community's own city text."
          },
          "visibility": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ],
            "description": "Community rows."
          }
        }
      },
      "LeaderboardPartGifts": {
        "type": "object",
        "description": "Settled gifts in each part (the bar's tooltip). The fund counts its dues and gift entries.",
        "properties": {
          "fund": {
            "type": "integer"
          },
          "raised": {
            "type": "integer"
          },
          "given": {
            "type": "integer"
          },
          "driven": {
            "type": "integer"
          }
        }
      },
      "LeaderboardCommunityRow": {
        "type": "object",
        "description": "One community on the communities view, ranked on Community impact (each settled gift once, amount_cents).",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "community"
            ]
          },
          "rank": {
            "type": "integer"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "href": {
            "type": "string",
            "description": "`/communities/<slug>`, the row's link"
          },
          "scope_href": {
            "type": "string",
            "description": "`/leaderboard?community=<slug>`"
          },
          "photo_url": {
            "type": "string",
            "nullable": true
          },
          "kind": {
            "type": "string",
            "enum": [
              "city",
              "church",
              "diaspora",
              "families",
              "school",
              "workplace",
              "other"
            ]
          },
          "visibility": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ]
          },
          "membership": {
            "type": "string",
            "enum": [
              "free",
              "paid"
            ]
          },
          "price_cents": {
            "type": "integer",
            "nullable": true,
            "description": "Monthly dues when paid"
          },
          "currency": {
            "type": "string"
          },
          "city": {
            "type": "object",
            "nullable": true,
            "properties": {
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "city_text": {
            "type": "string",
            "nullable": true
          },
          "member_count": {
            "type": "integer"
          },
          "fundlies": {
            "type": "integer",
            "description": "Fundlies posted here with a counted gift in the period"
          },
          "fund_cents": {
            "type": "integer",
            "description": "Into the community fund (dues and gifts",
            "net": null,
            "minus their refunds)": null
          },
          "raised_cents": {
            "type": "integer",
            "description": "For Fundlies posted here, minus this fund's own gifts (a community counting its members' whole history also adds the Fundlies they organize)"
          },
          "given_cents": {
            "type": "integer",
            "description": "By members since they joined, to other Fundlies (all time in a community counting its members' whole history)"
          },
          "driven_cents": {
            "type": "integer",
            "description": "Through members' links since they joined, to other Fundlies (all time in a community counting its members' whole history)"
          },
          "impact_cents": {
            "type": "integer",
            "description": "The four parts added"
          },
          "score": {
            "type": "integer"
          },
          "gifts": {
            "$ref": "#/components/schemas/LeaderboardPartGifts"
          },
          "fund_to_shared_cents": {
            "type": "integer",
            "description": "What this fund gave to Fundlies shared here",
            "counted once in the fund line": null
          },
          "has_fund": {
            "type": "boolean"
          }
        }
      },
      "LeaderboardCityRow": {
        "type": "object",
        "description": "One city on the cities view, ranked on City impact (each settled gift once, amount_cents).",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "city"
            ]
          },
          "rank": {
            "type": "integer"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "region": {
            "type": "string",
            "nullable": true
          },
          "region_name": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string"
          },
          "href": {
            "type": "string",
            "nullable": true,
            "description": "`/cities/<slug>` when the city has a page"
          },
          "scope_href": {
            "type": "string"
          },
          "photo_url": {
            "type": "string",
            "nullable": true
          },
          "metro": {
            "type": "object",
            "nullable": true,
            "properties": {
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "fundlies": {
            "type": "integer",
            "description": "Verified Fundlies started here"
          },
          "donors": {
            "type": "integer",
            "nullable": true,
            "description": "Donors who live here",
            "in the period; null when none": null
          },
          "people": {
            "type": "integer",
            "description": "Rows on the board whose home city is here (registered people, guests and anonymous aliases): the same count as this city's `people_count`"
          },
          "fund_cents": {
            "type": "integer",
            "description": "Into funds of communities here"
          },
          "raised_cents": {
            "type": "integer",
            "description": "For verified Fundlies started here, or benefiting a nonprofit whose home city is here (wherever its Fundly is), minus those funds' gifts"
          },
          "given_cents": {
            "type": "integer",
            "description": "By donors who live here",
            "to Fundlies elsewhere": null
          },
          "driven_cents": {
            "type": "integer",
            "description": "Through links of people here",
            "not already counted": null
          },
          "impact_cents": {
            "type": "integer"
          },
          "score": {
            "type": "integer"
          },
          "gifts": {
            "$ref": "#/components/schemas/LeaderboardPartGifts"
          },
          "fund_to_local_cents": {
            "type": "integer",
            "description": "What funds here gave to Fundlies started here, or benefiting a nonprofit whose home city is here (wherever its Fundly is), counted once in the fund line"
          }
        }
      },
      "LeaderboardCityScope": {
        "type": "object",
        "description": "The city scope card.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "city"
            ]
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string",
            "description": "Canonical slug"
          },
          "name": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "region": {
            "type": "string",
            "nullable": true
          },
          "region_name": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string"
          },
          "photo_url": {
            "type": "string",
            "nullable": true
          },
          "href": {
            "type": "string",
            "nullable": true
          },
          "area": {
            "type": "boolean",
            "description": "The metro is included"
          },
          "metro": {
            "type": "object",
            "nullable": true,
            "description": "The metro this city anchors or belongs to; null hides the switch",
            "properties": {
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "place_count": {
                "type": "integer"
              }
            }
          },
          "name_in_scope": {
            "type": "string",
            "description": "'Sacramento' or 'Sacramento area'"
          },
          "people_count": {
            "type": "integer",
            "description": "Rows ranked in the scope, every role: each registered person, guest and anonymous alias whose home city is in it"
          },
          "fund_cents": {
            "type": "integer"
          },
          "raised_cents": {
            "type": "integer",
            "description": "For verified Fundlies started here, or benefiting a nonprofit whose home city is here (wherever its Fundly is), minus those funds' gifts"
          },
          "given_cents": {
            "type": "integer"
          },
          "driven_cents": {
            "type": "integer"
          },
          "impact_cents": {
            "type": "integer",
            "description": "City impact",
            "each settled gift once": null
          },
          "gifts": {
            "$ref": "#/components/schemas/LeaderboardPartGifts"
          },
          "fund_to_local_cents": {
            "type": "integer",
            "description": "What funds here gave to Fundlies started here, or benefiting a nonprofit whose home city is here (wherever its Fundly is), counted once in the fund line"
          },
          "fundlies": {
            "type": "integer"
          },
          "donors": {
            "type": "integer",
            "nullable": true
          },
          "dedupe_note": {
            "type": "boolean"
          }
        }
      },
      "LeaderboardCommunityScope": {
        "type": "object",
        "description": "The community scope card.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "community"
            ]
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "href": {
            "type": "string"
          },
          "photo_url": {
            "type": "string",
            "nullable": true
          },
          "kind": {
            "type": "string"
          },
          "visibility": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ]
          },
          "membership": {
            "type": "string",
            "enum": [
              "free",
              "paid"
            ]
          },
          "price_cents": {
            "type": "integer",
            "nullable": true
          },
          "currency": {
            "type": "string"
          },
          "city": {
            "type": "object",
            "nullable": true,
            "properties": {
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "city_text": {
            "type": "string",
            "nullable": true
          },
          "member_count": {
            "type": "integer"
          },
          "fund_cents": {
            "type": "integer"
          },
          "raised_cents": {
            "type": "integer"
          },
          "given_cents": {
            "type": "integer"
          },
          "driven_cents": {
            "type": "integer"
          },
          "impact_cents": {
            "type": "integer",
            "description": "Community impact",
            "each settled gift once": null
          },
          "gifts": {
            "$ref": "#/components/schemas/LeaderboardPartGifts"
          },
          "fund_to_shared_cents": {
            "type": "integer"
          },
          "fundlies": {
            "type": "integer"
          },
          "has_fund": {
            "type": "boolean"
          },
          "fund_href": {
            "type": "string",
            "nullable": true,
            "description": "The fund tab",
            "when the caller may open it": null
          },
          "show_leaders": {
            "type": "boolean"
          },
          "members_visible": {
            "type": "boolean",
            "description": "False for a private community and a caller who is not a member; entries are then empty"
          },
          "viewer_role": {
            "type": "string",
            "nullable": true,
            "enum": [
              "owner",
              "leader",
              "volunteer",
              "member"
            ]
          },
          "dedupe_note": {
            "type": "boolean"
          }
        }
      },
      "LeaderboardViewerStanding": {
        "type": "object",
        "description": "`ranked`: the caller's row in this scope. `unranked`: in scope, nothing settled yet. `outside_scope`: the caller's home city (their profile city; without one, the city most of their named gifts come from) is not in the city scope (`suggestion` offers the metro when they live in it), or they are not a member of the community.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ranked",
              "unranked",
              "outside_scope"
            ]
          },
          "rank": {
            "type": "integer"
          },
          "score": {
            "type": "integer"
          },
          "impact": {
            "type": "integer"
          },
          "raised": {
            "type": "integer"
          },
          "given": {
            "type": "integer"
          },
          "driven": {
            "type": "integer"
          },
          "gap": {
            "type": "integer"
          },
          "above": {
            "type": "string",
            "nullable": true
          },
          "above_hidden": {
            "type": "boolean"
          },
          "scope_name": {
            "type": "string",
            "nullable": true
          },
          "reason": {
            "type": "string",
            "enum": [
              "other_city",
              "no_city",
              "not_member"
            ]
          },
          "viewer_city": {
            "type": "object",
            "nullable": true,
            "properties": {
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "suggestion": {
            "type": "object",
            "nullable": true,
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "metro"
                ]
              },
              "city": {
                "type": "string"
              },
              "area": {
                "type": "boolean"
              },
              "name": {
                "type": "string"
              },
              "href": {
                "type": "string"
              }
            }
          }
        }
      },
      "LeaderboardJumpTo": {
        "type": "object",
        "properties": {
          "city": {
            "type": "object",
            "nullable": true,
            "description": "The caller's home city (their profile city; without one, the city most of their named gifts come from) when it has a page, else its metro (with `area`)",
            "properties": {
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "photo_url": {
                "type": "string",
                "nullable": true
              },
              "relation": {
                "type": "string",
                "enum": [
                  "home",
                  "metro"
                ]
              },
              "area": {
                "type": "boolean"
              },
              "impact_cents": {
                "type": "integer"
              },
              "href": {
                "type": "string"
              }
            }
          },
          "communities": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "photo_url": {
                  "type": "string",
                  "nullable": true
                },
                "member_count": {
                  "type": "integer"
                },
                "impact_cents": {
                  "type": "integer"
                },
                "role": {
                  "type": "string",
                  "enum": [
                    "owner",
                    "leader",
                    "volunteer",
                    "member"
                  ]
                },
                "href": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchResult"
            }
          },
          "total": {
            "type": "integer",
            "description": "Total matching campaigns. Users and organizations are capped at `limit` and not counted here."
          },
          "executionTimeMs": {
            "type": "integer"
          },
          "cached": {
            "type": "boolean"
          }
        }
      },
      "Milestone": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "fundraiser_id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "target_amount_cents": {
            "type": "integer",
            "nullable": true,
            "description": "Milestone target in cents. Renamed from `target_amount` (dollars)."
          },
          "due_date": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "completed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Set when the milestone is marked complete; null while outstanding."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PayoutSchedule": {
        "type": "object",
        "properties": {
          "interval": {
            "type": "string",
            "enum": [
              "manual",
              "daily",
              "weekly",
              "monthly"
            ]
          },
          "weeklyPayoutDays": {
            "type": "array",
            "nullable": true,
            "description": "Single-element list holding Stripe's weekly anchor, or null.",
            "items": {
              "type": "string"
            }
          },
          "monthlyPayoutDays": {
            "type": "array",
            "nullable": true,
            "description": "Single-element list holding Stripe's monthly anchor (1-31), or null.",
            "items": {
              "type": "integer"
            }
          },
          "delayDays": {
            "type": "integer",
            "description": "Stripe's payout delay in days. Defaults to 2 when the account does not report one."
          }
        }
      },
      "Notification": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "user_id": {
            "type": "string",
            "format": "uuid"
          },
          "type": {
            "type": "string",
            "description": "Event key, e.g. `donation_received`."
          },
          "category": {
            "type": "string",
            "enum": [
              "campaign",
              "donation",
              "social",
              "security",
              "payouts"
            ]
          },
          "priority": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high",
              "urgent"
            ]
          },
          "title": {
            "type": "string"
          },
          "message": {
            "type": "string",
            "description": "May contain inline HTML links (donor names, campaign links)."
          },
          "icon": {
            "type": "string"
          },
          "action_url": {
            "type": "string",
            "nullable": true
          },
          "action_label": {
            "type": "string",
            "nullable": true
          },
          "is_read": {
            "type": "boolean"
          },
          "is_archived": {
            "type": "boolean"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CampaignUpdateFeedItem": {
        "type": "object",
        "description": "A campaign update in the signed-in person's feed. The same shape as an item of `GET /projects/{fundraiserId}/updates` (the `project_updates` row with `type: update` and `author`), plus `fundraiser`, `is_read` and `read_at`. With `lang`, the translation fields that endpoint adds (`translation_source`, `original_title`, `original_body`) appear too.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "type": {
            "type": "string",
            "enum": [
              "update"
            ]
          },
          "fundraiser_id": {
            "type": "string",
            "format": "uuid"
          },
          "author_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "body": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "active"
            ]
          },
          "source_language": {
            "type": "string",
            "nullable": true,
            "enum": [
              "en",
              "ru",
              "uk",
              "es"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "text_edited_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "author": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string",
                "nullable": true
              },
              "avatar": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "fundraiser": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "title": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "cover_image": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "is_read": {
            "type": "boolean",
            "description": "True when the person marked it read, or when it was posted before they followed the campaign's creator or organization or first gave to it — older updates are history and never count as unread."
          },
          "read_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When it was first marked read; null when unread or read only by the starting-point rule."
          }
        }
      },
      "LikeState": {
        "type": "object",
        "description": "The caller's like on one comment or update, and that target's count, after the write (#1833).",
        "required": [
          "liked",
          "like_count"
        ],
        "properties": {
          "liked": {
            "type": "boolean",
            "description": "Whether the caller now likes the target."
          },
          "like_count": {
            "type": "integer",
            "minimum": 0,
            "description": "How many accounts like the target, this caller included."
          }
        }
      },
      "Gif": {
        "type": "object",
        "description": "A GIPHY GIF on a comment (#1963). Built by the server from GIPHY's own response; a client never supplies a URL. Every URL is `https://` on a `giphy.com` subdomain with no query string. Full size is GIPHY's `images.original`, the still is `images.original_still`, and the preview is `images.fixed_width` (200 px wide). Render `title` as text.",
        "required": [
          "id",
          "title",
          "width",
          "height",
          "mp4_url",
          "webp_url",
          "gif_url",
          "still_url",
          "preview_mp4_url",
          "preview_webp_url",
          "preview_width",
          "preview_height"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9]{6,40}$",
            "example": "xT4uQulxzV39haRFjG"
          },
          "title": {
            "type": "string",
            "description": "Plain text, possibly empty. Use as alt text."
          },
          "width": {
            "type": "integer",
            "minimum": 1,
            "example": 480
          },
          "height": {
            "type": "integer",
            "minimum": 1,
            "example": 270
          },
          "mp4_url": {
            "type": "string",
            "format": "uri",
            "example": "https://media2.giphy.com/media/xT4uQulxzV39haRFjG/giphy.mp4"
          },
          "webp_url": {
            "type": "string",
            "format": "uri",
            "example": "https://media2.giphy.com/media/xT4uQulxzV39haRFjG/giphy.webp"
          },
          "gif_url": {
            "type": "string",
            "format": "uri",
            "example": "https://media2.giphy.com/media/xT4uQulxzV39haRFjG/giphy.gif"
          },
          "still_url": {
            "type": "string",
            "format": "uri",
            "example": "https://media2.giphy.com/media/xT4uQulxzV39haRFjG/giphy_s.gif"
          },
          "preview_mp4_url": {
            "type": "string",
            "format": "uri",
            "example": "https://media2.giphy.com/media/xT4uQulxzV39haRFjG/200w.mp4"
          },
          "preview_webp_url": {
            "type": "string",
            "format": "uri",
            "example": "https://media2.giphy.com/media/xT4uQulxzV39haRFjG/200w.webp"
          },
          "preview_width": {
            "type": "integer",
            "minimum": 1,
            "example": 200
          },
          "preview_height": {
            "type": "integer",
            "minimum": 1,
            "example": 113
          }
        }
      },
      "GifPage": {
        "type": "object",
        "required": [
          "data",
          "next_offset"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Gif"
            }
          },
          "next_offset": {
            "type": "integer",
            "nullable": true,
            "description": "The `offset` for the next page, or null when there is none."
          }
        }
      },
      "AccountDeletionSchedule": {
        "type": "object",
        "required": [
          "scheduled_for",
          "requested_at"
        ],
        "properties": {
          "scheduled_for": {
            "type": "string",
            "format": "date-time",
            "description": "When the account will be deleted (30 days after the request), if nothing is owed to the person by then; otherwise once it has been paid out."
          },
          "requested_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "statusCode": {
            "type": "integer"
          }
        }
      },
      "OrgRoleTitle": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "executive_director"
          },
          "label": {
            "type": "string",
            "example": "Executive Director"
          },
          "category": {
            "type": "string",
            "enum": [
              "governance",
              "executive",
              "programs",
              "fundraising",
              "operations",
              "community"
            ]
          },
          "sort_order": {
            "type": "integer"
          }
        }
      },
      "OrgAdminPagination": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "OrgAdminFundraiser": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "owner_user_id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string"
          },
          "slug": {
            "type": "string",
            "nullable": true
          },
          "summary": {
            "type": "string",
            "nullable": true
          },
          "is_project": {
            "type": "boolean"
          },
          "location_label": {
            "type": "string",
            "nullable": true,
            "description": "Canonical city and state label shared with campaign cards."
          },
          "donor_count": {
            "type": "integer"
          },
          "total_raised_cents": {
            "type": "string",
            "description": "Ledger-backed campaign stats in integer cents, after Stripe fees."
          },
          "owner_profile": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "nullable": true
              },
              "avatar": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "fundraising": {
            "$ref": "#/components/schemas/FundraisingState"
          },
          "goal_amount_cents": {
            "type": "string",
            "description": "Goal in integer CENTS, serialized as a JSON string (a 64-bit integer).",
            "example": "500000"
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "pending",
              "rejected",
              "active",
              "paused",
              "ended"
            ]
          },
          "visibility": {
            "type": "string",
            "enum": [
              "public",
              "unlisted",
              "private"
            ]
          },
          "cover_image": {
            "type": "string",
            "nullable": true
          },
          "end_date": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "A calendar date, serialized as midnight server time."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "OrgAdminDonation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "fundraiser_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Null for a gift made directly to the non-profit (general fund, monthly)."
          },
          "fundraiser_title": {
            "type": "string",
            "nullable": true
          },
          "fundraiser_slug": {
            "type": "string",
            "nullable": true
          },
          "amount_cents": {
            "type": "integer",
            "description": "Gift amount in integer CENTS."
          },
          "currency": {
            "type": "string"
          },
          "tip_amount_cents": {
            "type": "integer",
            "nullable": true
          },
          "fee_amount_cents": {
            "type": "integer",
            "nullable": true
          },
          "payment_status": {
            "type": "string",
            "enum": [
              "paid",
              "pending",
              "failed",
              "refunded"
            ]
          },
          "is_anonymous": {
            "type": "boolean"
          },
          "comment": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "donor_display_name": {
            "type": "string",
            "description": "`Anonymous donor` for anonymous gifts or when no name is known."
          }
        }
      },
      "OrgAdminDonor": {
        "type": "object",
        "properties": {
          "donor_key": {
            "type": "string",
            "description": "Opaque, stable key for the donor: `anonymous`, `user:<profile id>` or `guest:<24 hex characters>`. Use it to tell rows apart, not to identify or contact a donor.",
            "example": "user:3f1c2a9e-5b7d-4e1a-9c2b-8d6f0a1b2c3d"
          },
          "donor_display_name": {
            "type": "string"
          },
          "donor_avatar": {
            "type": "string",
            "nullable": true,
            "description": "Saved profile avatar for an identified registered donor; always null for anonymous and guest buckets."
          },
          "donation_count": {
            "type": "integer"
          },
          "total_amount_cents": {
            "type": "string",
            "description": "Raised after card fees: what this donor's counted gifts (paid or refunded) to this organization raised, in integer CENTS, serialized as a JSON string (a bigint sum). Each gift counts at its ledger donation credit less its Stripe fee, never the tip, and a refunded gift counts at that amount too (a refund does not un-give a gift): the per-gift amount the Overview's Raised sums. It is not the gross a donor was charged, which the gift's receipt, its donation detail and the Donations list show.",
            "example": "125000"
          },
          "currency": {
            "type": "string"
          },
          "last_donated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "OrgAdminUserSearchResult": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "type": {
            "type": "string",
            "enum": [
              "user"
            ]
          },
          "name": {
            "type": "string",
            "description": "The user's display name, or `FundlyHub user` when none is set."
          },
          "avatar": {
            "type": "string",
            "nullable": true,
            "description": "Avatar URL, or `null`."
          },
          "masked_email": {
            "type": "string",
            "description": "The account's email with the local part masked to its first character, e.g. `j***@example.org`, so the caller can confirm the match without the address being echoed back.",
            "example": "j***@example.org"
          }
        }
      },
      "OrgAdminMember": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": "string",
            "format": "uuid"
          },
          "user_name": {
            "type": "string",
            "nullable": true
          },
          "user_email": {
            "type": "string",
            "nullable": true
          },
          "user_avatar": {
            "type": "string",
            "nullable": true
          },
          "role_name": {
            "type": "string",
            "enum": [
              "org_owner",
              "org_admin",
              "org_viewer"
            ]
          },
          "role_display_name": {
            "type": "string",
            "nullable": true
          },
          "hierarchy_level": {
            "type": "integer",
            "description": "45 owner, 35 admin, 25 viewer."
          },
          "assigned_at": {
            "type": "string",
            "format": "date-time"
          },
          "org_role_title_id": {
            "type": "string",
            "nullable": true,
            "description": "An `id` from `GET /org-role-titles`, when the title comes from the taxonomy."
          },
          "custom_role_title": {
            "type": "string",
            "nullable": true,
            "description": "The free-form title, when nothing in the taxonomy was picked."
          },
          "role_title_label": {
            "type": "string",
            "nullable": true,
            "description": "The title as shown: the taxonomy label when `org_role_title_id` is set, otherwise `custom_role_title`."
          }
        }
      },
      "OrgAdminSettings": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "legal_name": {
            "type": "string"
          },
          "website": {
            "type": "string",
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "logo": {
            "type": "string",
            "nullable": true
          },
          "banner_image": {
            "type": "string",
            "nullable": true
          },
          "mission": {
            "type": "string",
            "nullable": true
          },
          "social_links": {
            "type": "object",
            "description": "Platform → URL; keys are among twitter, linkedin, facebook, instagram, youtube, tiktok.",
            "additionalProperties": {
              "type": "string"
            }
          },
          "founded_year": {
            "type": "integer",
            "nullable": true
          },
          "verification_completed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "categories": {
            "type": "array",
            "nullable": true,
            "description": "Category names, as `GET /categories` spells them.",
            "items": {
              "type": "string"
            }
          },
          "contact_email": {
            "type": "string",
            "nullable": true
          },
          "contact_email_public": {
            "type": "boolean"
          },
          "slug": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "company",
              "conglomerate"
            ]
          },
          "verification_status": {
            "type": "string"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "OrgAdminImageUpload": {
        "type": "object",
        "required": [
          "fileBase64",
          "contentType"
        ],
        "properties": {
          "fileBase64": {
            "type": "string",
            "format": "byte",
            "description": "The image, base64-encoded (no `data:` prefix)."
          },
          "contentType": {
            "type": "string",
            "enum": [
              "image/jpeg",
              "image/png",
              "image/webp"
            ]
          }
        }
      },
      "OrgAdminUpdate": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "author_user_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "title": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "cover_image": {
            "type": "string",
            "nullable": true
          },
          "published_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "OrgAdminDba": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "dba_name": {
            "type": "string"
          },
          "is_default": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "OrgAdminAddress": {
        "type": "object",
        "description": "An address object of up to 16 string fields, each at most 512 characters; null and blank values are dropped. The fields read are `line1`, `line2` (suite or unit), `city`, `region` (a US state), `postal_code` (or `postal`) and `country` (a code or a name; the organization's own when absent). An address that resolves (a US one needs its street, city, state and ZIP) is stored once, in standard form (\"123 Main Street\" as \"123 Main St\", \"Suite 100\" as \"Ste 100\"), and is read back with exactly those six fields. One that does not resolve yet, such as an unknown ZIP or city, is kept as typed and resolved in the background.",
        "maxProperties": 16,
        "additionalProperties": {
          "type": "string",
          "maxLength": 512
        },
        "example": {
          "line1": "100 Main St",
          "city": "Sacramento",
          "region": "CA",
          "postal_code": "95814",
          "country": "US"
        }
      },
      "OrgAdminLocation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "address": {
            "$ref": "#/components/schemas/OrgAdminAddress"
          },
          "is_primary": {
            "type": "boolean"
          },
          "is_publicly_visible": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "OrgAdminPayoutsStatus": {
        "type": "object",
        "properties": {
          "connected": {
            "type": "boolean"
          },
          "accountId": {
            "type": "string"
          },
          "chargesEnabled": {
            "type": "boolean"
          },
          "payoutsEnabled": {
            "type": "boolean"
          },
          "detailsSubmitted": {
            "type": "boolean"
          },
          "defaultCurrency": {
            "type": "string",
            "example": "usd"
          },
          "country": {
            "type": "string",
            "example": "US"
          },
          "businessType": {
            "type": "string",
            "example": "company"
          },
          "requirementsCurrentlyDue": {
            "type": "array",
            "description": "Stripe requirement keys still outstanding.",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "OrgAdminChildOrganization": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "legal_name": {
            "type": "string"
          },
          "dba_name": {
            "type": "string",
            "nullable": true
          },
          "slug": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "example": "company"
          },
          "verification_status": {
            "type": "string"
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "website": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "OrgAdminCreatedChild": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "legal_name": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "company"
            ]
          },
          "parent_organization_id": {
            "type": "string",
            "format": "uuid"
          },
          "verification_status": {
            "type": "string",
            "example": "pending"
          },
          "dbas": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "dba_name": {
                  "type": "string"
                },
                "is_default": {
                  "type": "boolean"
                }
              }
            }
          },
          "locations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "label": {
                  "type": "string",
                  "nullable": true
                },
                "address": {
                  "$ref": "#/components/schemas/OrgAdminAddress"
                },
                "is_primary": {
                  "type": "boolean"
                }
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "OrgAdminDocument": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "doc_type": {
            "type": "string",
            "enum": [
              "ein_letter",
              "501c3_determination",
              "w9",
              "voided_check",
              "other"
            ]
          },
          "original_filename": {
            "type": "string",
            "nullable": true
          },
          "content_type": {
            "type": "string"
          },
          "size_bytes": {
            "type": "integer"
          },
          "verification_status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected"
            ]
          },
          "rejection_reason": {
            "type": "string",
            "nullable": true
          },
          "reviewed_by_user_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "reviewed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "uploaded_by_user_id": {
            "type": "string",
            "format": "uuid"
          },
          "is_publicly_visible": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TranslationFundraiserRow": {
        "type": "object",
        "description": "A campaign's row in one locale. All fields null and `source` null when not translated yet.",
        "properties": {
          "language": {
            "type": "string",
            "enum": [
              "en",
              "ru",
              "uk",
              "es"
            ]
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "summary": {
            "type": "string",
            "nullable": true
          },
          "story_html": {
            "type": "string",
            "nullable": true
          },
          "source": {
            "type": "string",
            "enum": [
              "human",
              "machine"
            ],
            "nullable": true
          },
          "translated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "TranslationFundraiserSavedRow": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "fundraiser_id": {
                "type": "string",
                "format": "uuid"
              }
            }
          },
          {
            "$ref": "#/components/schemas/TranslationFundraiserRow"
          }
        ]
      },
      "TranslationMilestoneRow": {
        "type": "object",
        "properties": {
          "language": {
            "type": "string",
            "enum": [
              "en",
              "ru",
              "uk",
              "es"
            ]
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "source": {
            "type": "string",
            "enum": [
              "human",
              "machine"
            ],
            "nullable": true
          },
          "translated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "TranslationMilestoneEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "translations": {
            "type": "array",
            "description": "One entry per locale other than the campaign's source language.",
            "items": {
              "$ref": "#/components/schemas/TranslationMilestoneRow"
            }
          },
          "original_row": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TranslationMilestoneRow"
              }
            ],
            "nullable": true,
            "description": "The milestone's row in the campaign's own language, if any."
          }
        }
      },
      "TranslationProjectUpdateRow": {
        "type": "object",
        "properties": {
          "language": {
            "type": "string",
            "enum": [
              "en",
              "ru",
              "uk",
              "es"
            ]
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "content": {
            "type": "string",
            "nullable": true
          },
          "source": {
            "type": "string",
            "enum": [
              "human",
              "machine"
            ],
            "nullable": true
          },
          "translated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "outdated": {
            "type": "boolean",
            "description": "A hand translation saved before the update's text was last edited."
          }
        }
      },
      "TranslationProjectUpdateEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "source": {
            "type": "object",
            "properties": {
              "language": {
                "type": "string",
                "enum": [
                  "en",
                  "ru",
                  "uk",
                  "es"
                ]
              },
              "title": {
                "type": "string",
                "nullable": true
              },
              "content": {
                "type": "string"
              },
              "edited_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "When an edit last changed the text; null if never."
              }
            }
          },
          "translations": {
            "type": "array",
            "description": "One entry per locale other than the update's own.",
            "items": {
              "$ref": "#/components/schemas/TranslationProjectUpdateRow"
            }
          }
        }
      },
      "TranslationUpdateSavedRow": {
        "type": "object",
        "properties": {
          "update_id": {
            "type": "string",
            "format": "uuid"
          },
          "language": {
            "type": "string",
            "enum": [
              "en",
              "ru",
              "uk",
              "es"
            ]
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "content": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "human",
              "machine"
            ]
          },
          "translated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TranslationLegacyUpdateRow": {
        "type": "object",
        "properties": {
          "language": {
            "type": "string",
            "enum": [
              "en",
              "ru",
              "uk",
              "es"
            ]
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "content": {
            "type": "string",
            "nullable": true
          },
          "source": {
            "type": "string",
            "enum": [
              "human",
              "machine"
            ],
            "nullable": true
          },
          "translated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "TranslationMtError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "Why translation is unavailable."
          }
        }
      },
      "ShareChannelStat": {
        "type": "object",
        "properties": {
          "clicks": {
            "type": "integer",
            "description": "Human visits through a shared link."
          },
          "gifts": {
            "type": "integer",
            "description": "Paid, non-self-referred gifts those visits led to."
          }
        }
      },
      "FundraiserTrustAssessment": {
        "type": "object",
        "properties": {
          "publishable": {
            "type": "boolean"
          },
          "profileBlockers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "campaignBlockers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "suggestions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string"
                },
                "severity": {
                  "type": "string",
                  "enum": [
                    "warning",
                    "tip"
                  ]
                },
                "message": {
                  "type": "string"
                },
                "actionUrl": {
                  "type": "string"
                }
              }
            }
          },
          "trustScore": {
            "type": "number"
          },
          "aiAnalysis": {
            "type": "object",
            "nullable": true,
            "properties": {
              "storyScore": {
                "type": "number"
              },
              "titleSuggestion": {
                "type": "string"
              },
              "storySuggestions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "redFlags": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "overallVerdict": {
                "type": "string",
                "enum": [
                  "approve",
                  "needs_work",
                  "reject"
                ]
              },
              "categorySpecificIssues": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "verifiableDetails": {
                "type": "boolean"
              },
              "contradictions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "aiDecision": {
            "type": "string",
            "enum": [
              "auto_approve",
              "pending_review",
              "reject"
            ]
          },
          "rejectionReasons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "aiAnalysisError": {
            "type": "string",
            "nullable": true,
            "enum": [
              "api_key_missing",
              "timeout",
              "rate_limited",
              "parse_error",
              "unknown"
            ]
          },
          "payoutHold": {
            "type": "boolean",
            "description": "Whether payouts would be held pending Stripe verification."
          },
          "userMessages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "FundraiserActivityEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "action": {
            "type": "string",
            "enum": [
              "created",
              "submitted_for_review",
              "approved",
              "rejected",
              "updated",
              "update_posted",
              "goal_reached",
              "deleted"
            ]
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "actor": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "nullable": true
              },
              "name": {
                "type": "string",
                "nullable": true
              },
              "email": {
                "type": "string",
                "nullable": true
              },
              "role": {
                "type": "string",
                "enum": [
                  "owner",
                  "admin",
                  "system"
                ],
                "nullable": true
              }
            }
          },
          "details": {
            "type": "object",
            "description": "Present on some actions: `title` and `goalAmount` (created), `goalAmountCents` and `totalRaisedCents` (goal_reached), `reasons` (rejected).",
            "additionalProperties": true
          }
        }
      },
      "DonorFace": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "avatar": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "RelatedCampaign": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string",
            "nullable": true
          },
          "goal_amount_cents": {
            "type": "number"
          },
          "raised_amount_cents": {
            "type": "number"
          },
          "currency": {
            "type": "string"
          },
          "cover_image": {
            "type": "string",
            "nullable": true
          },
          "cover_image_focal_x": {
            "type": "number",
            "nullable": true
          },
          "cover_image_focal_y": {
            "type": "number",
            "nullable": true
          },
          "category": {
            "type": "string",
            "nullable": true
          },
          "category_name": {
            "type": "string",
            "nullable": true
          },
          "location": {
            "type": "string",
            "nullable": true
          },
          "location_label": {
            "$ref": "#/components/schemas/LocationLabel"
          },
          "fundraising": {
            "$ref": "#/components/schemas/FundraisingState"
          },
          "donor_count": {
            "type": "integer"
          },
          "days_left": {
            "type": "integer",
            "nullable": true
          },
          "is_project": {
            "type": "boolean"
          },
          "trust_score": {
            "type": "number",
            "nullable": true
          },
          "approved_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "organizer_name": {
            "type": "string",
            "nullable": true
          },
          "organizer_avatar": {
            "type": "string",
            "nullable": true
          },
          "gallery": {
            "type": "array",
            "maxItems": 6,
            "description": "The campaign card's photos, at most six: the cover first, then its other public images in gallery order, each URL once. Images only — no videos, no photos taken down, no uploads still processing. Empty when the campaign has no photo. The same list and rule as `gallery` on `GET /fundraisers` items.",
            "items": {
              "type": "string"
            }
          },
          "translation_source": {
            "type": "string",
            "enum": [
              "source",
              "machine",
              "human"
            ],
            "description": "Present when a reader language was resolved."
          },
          "original_title": {
            "type": "string",
            "nullable": true
          },
          "original_summary": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "OutcomeReportAttachment": {
        "type": "object",
        "required": [
          "kind",
          "url"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "image"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "SuccessStoryKind": {
        "type": "string",
        "enum": [
          "fully_funded",
          "ended",
          "closed"
        ],
        "description": "Computed, never stored. `fully_funded`: raised reached the goal. `closed`: donations were stopped short of the goal. `ended`: everything else, including an ended Fundly still taking gifts."
      },
      "CityCard": {
        "type": "object",
        "description": "One city. `donors` counts every donor who lives here, from the first; null when none. Money is what reached the creators, in cents: each counted gift (paid or refunded) to a verified Fundly at its donation less the Stripe fee, never the tip, so a city's figures are sums of campaign cards. `donors` counts the people behind the same gifts.",
        "properties": {
          "slug": {
            "type": "string",
            "example": "sacramento-ca"
          },
          "name": {
            "type": "string",
            "example": "Sacramento"
          },
          "region": {
            "type": "string",
            "nullable": true,
            "description": "The US state code, or the region the geocoder gave elsewhere.",
            "example": "CA"
          },
          "country": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2.",
            "example": "US"
          },
          "label": {
            "type": "string",
            "example": "Sacramento, CA"
          },
          "photo_url": {
            "type": "string",
            "nullable": true,
            "description": "The 1:1 city photo."
          },
          "lat": {
            "type": "number",
            "description": "City centroid, 2 decimals."
          },
          "lng": {
            "type": "number"
          },
          "fundlies_active": {
            "type": "integer",
            "description": "Verified Fundlies started here that are live now."
          },
          "fundlies_funded": {
            "type": "integer",
            "description": "Verified Fundlies started here that reached their goal."
          },
          "donors": {
            "type": "integer",
            "nullable": true,
            "description": "Distinct donors who live here (signed in, guest or anonymous); null when none."
          },
          "raised_cents": {
            "type": "integer",
            "description": "What the verified Fundlies started here raised: the sum of their campaign cards (net of the Stripe fee, tips excluded)."
          },
          "has_page": {
            "type": "boolean",
            "description": "Whether `/cities/{slug}` exists (the page threshold, staff override, never hidden)."
          },
          "metro": {
            "type": "object",
            "nullable": true,
            "description": "The metro this city belongs to (its anchor city); null for an anchor or a city with none.",
            "properties": {
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          }
        }
      },
      "CityMapPoint": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "lat": {
            "type": "number"
          },
          "lng": {
            "type": "number"
          },
          "fundlies": {
            "type": "integer",
            "description": "Verified Fundlies started here."
          },
          "donors": {
            "type": "integer",
            "nullable": true,
            "description": "Null when none."
          },
          "kind": {
            "type": "string",
            "enum": [
              "fundlies",
              "donors_only"
            ],
            "description": "`fundlies` draws a purple dot, `donors_only` a lavender one."
          },
          "has_page": {
            "type": "boolean"
          }
        }
      },
      "CityFollowBlock": {
        "type": "object",
        "description": "The viewer's follow state for one city. Anonymous: `following` false, no friends. `friends` are at most 3 mutual follows who follow the city and did not turn off \"Show the cities I follow to friends\", closest first (gave to the same Fundlies, then the newest mutual follow); `friend_count` counts every friend who follows, opted out or not.",
        "properties": {
          "following": {
            "type": "boolean"
          },
          "digest": {
            "type": "boolean",
            "description": "The Monday digest (default on)."
          },
          "instant": {
            "type": "boolean",
            "description": "An email per new verified Fundly (default off)."
          },
          "follower_count": {
            "type": "integer",
            "nullable": true,
            "description": "Everyone following; null below 5."
          },
          "friends": {
            "type": "array",
            "maxItems": 3,
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "avatar_url": {
                  "type": "string",
                  "nullable": true
                },
                "handle": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "friend_count": {
            "type": "integer"
          }
        }
      },
      "CityPage": {
        "type": "object",
        "properties": {
          "map_version": {
            "type": "string",
            "example": "1792000000-412",
            "description": "Changes whenever any city changes (a new city, a moved point, a new photo). Add it as `v` to the map snapshot URLs so a cached image is never older than the cities it shows."
          },
          "city": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CityCard"
              },
              {
                "type": "object",
                "properties": {
                  "timezone": {
                    "type": "string",
                    "example": "America/Los_Angeles"
                  },
                  "metro": {
                    "type": "object",
                    "nullable": true,
                    "description": "The metro (for its anchor, the city itself) with how many cities it holds.",
                    "properties": {
                      "slug": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      },
                      "place_count": {
                        "type": "integer"
                      }
                    }
                  },
                  "region_name": {
                    "type": "string",
                    "nullable": true,
                    "example": "California"
                  },
                  "country_name": {
                    "type": "string",
                    "example": "United States"
                  },
                  "photo_crop": {
                    "type": "object",
                    "nullable": true,
                    "additionalProperties": true
                  },
                  "photo_credit": {
                    "type": "object",
                    "nullable": true,
                    "description": "Who took the photo, when it came from Unsplash (#2085); null for any other photo. Shown as 'Photo by <photographer_name> on Unsplash', each link carrying utm_source and utm_medium=referral.",
                    "required": [
                      "source",
                      "photo_id",
                      "photographer_name",
                      "photographer_username",
                      "photographer_url",
                      "photo_page_url"
                    ],
                    "properties": {
                      "source": {
                        "type": "string",
                        "enum": [
                          "unsplash"
                        ]
                      },
                      "photo_id": {
                        "type": "string",
                        "description": "The Unsplash photo id."
                      },
                      "photographer_name": {
                        "type": "string"
                      },
                      "photographer_username": {
                        "type": "string"
                      },
                      "photographer_url": {
                        "type": "string",
                        "format": "uri",
                        "description": "The photographer's Unsplash profile, without referral params."
                      },
                      "photo_page_url": {
                        "type": "string",
                        "format": "uri",
                        "description": "The photo's page on Unsplash."
                      }
                    }
                  },
                  "photo_original_url": {
                    "type": "string",
                    "nullable": true,
                    "description": "The original photo the hero shows (the card keeps the square crop in `photo_url`): an https URL or an `/uploads/` path on this site. Null when the city has no photo or the stored URL is neither.",
                    "example": "https://fundlyhub.org/uploads/image-originals/sacramento.jpg"
                  },
                  "photo_page_focus": {
                    "type": "object",
                    "nullable": true,
                    "description": "Where the hero centres `photo_original_url`, as CSS `object-position` percentages with one decimal, set by staff. Null is the default framing (the centre), and always null when `photo_original_url` is.",
                    "required": [
                      "x",
                      "y"
                    ],
                    "properties": {
                      "x": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 100,
                        "description": "Percent from the left.",
                        "example": 30
                      },
                      "y": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 100,
                        "description": "Percent from the top.",
                        "example": 62.5
                      }
                    }
                  }
                }
              }
            ]
          },
          "stats": {
            "type": "object",
            "properties": {
              "fundlies_active": {
                "type": "integer"
              },
              "fundlies_funded": {
                "type": "integer"
              },
              "fundlies_here": {
                "type": "integer",
                "description": "Every verified Fundly started here."
              },
              "city_impact_cents": {
                "type": "integer",
                "description": "City impact, the figure `/leaderboard?city={slug}` ranks on: money landing in the community funds of communities here, plus raised for Fundlies started here or benefiting a nonprofit whose home city is here (wherever its Fundly is), given from here and driven from here (referral attribution), each counted gift once, in the first part that claims it, at what reached its creator (net of the Stripe fee, tips excluded). A gift a local community fund made counts only in the fund line."
              },
              "raised_here_cents": {
                "type": "integer"
              },
              "donors": {
                "type": "integer",
                "nullable": true,
                "description": "Null when none."
              },
              "given_from_here_cents": {
                "type": "integer"
              },
              "communities": {
                "type": "integer",
                "description": "Listed communities placed here (active, listed, not deleted), the set `communities` lists."
              },
              "nonprofits": {
                "type": "integer",
                "description": "The non-profit cards in `nonprofits` that are not churches (the verified non-profits placed here, not deleted)."
              },
              "churches": {
                "type": "integer",
                "description": "The non-profit cards in `nonprofits` that are churches."
              },
              "ambassadors": {
                "type": "integer"
              },
              "sponsors": {
                "type": "integer",
                "nullable": true,
                "description": "Listed sponsors with an open location here (#2468): every one, the set `GET /sponsors?city={slug}` lists, past the cap on `sponsors` too. Null while sponsors are switched off for everyone."
              }
            }
          },
          "needs_help": {
            "type": "array",
            "description": "Live verified Fundlies started here, newest first, at most 12. When none is live, the city's verified Fundlies that have ended without being fully funded instead (an ended Fundly still takes gifts). Items are campaign cards, as `GET /fundraisers` returns them.",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "fully_funded": {
            "type": "array",
            "description": "Verified Fundlies here that reached their goal, at most 12.",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "communities": {
            "type": "array",
            "description": "Every listed community placed here, as the directory's cards, featured first, then the most members.",
            "items": {
              "$ref": "#/components/schemas/CommunityCard"
            }
          },
          "nonprofits": {
            "type": "array",
            "description": "\"Non-profits in <city>\" (#2098): every verified non-profit placed here, not deleted, as the directory's cards in its default order (impact; a paused one last), each built for the caller (`viewer`: their role and Follow state). The same set `stats.nonprofits` counts.",
            "items": {
              "$ref": "#/components/schemas/NonprofitCard"
            }
          },
          "sponsors": {
            "type": "array",
            "description": "\"Sponsors in <city>\" (#2468): the city's businesses as the directory's cards (`GET /sponsors?city={slug}`), at most 24, nearest first from the caller's place, else by name, each built for the caller (a guest's when signed out). Each links its public page, `/sponsors/{slug}`. Empty while sponsors are switched off for everyone; `stats.sponsors` counts them all.",
            "items": {
              "$ref": "#/components/schemas/PublicSponsorCard"
            }
          },
          "sponsor_achievements": {
            "$ref": "#/components/schemas/PerkAchievementMap"
          },
          "ambassadors": {
            "type": "array",
            "description": "Public profiles in this city holding the ambassador role, at most 12.",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "avatar_url": {
                  "type": "string",
                  "nullable": true
                },
                "handle": {
                  "type": "string",
                  "nullable": true
                },
                "driven_cents": {
                  "type": "integer",
                  "description": "What reached the creators of verified Fundlies through their shares (net of the Stripe fee, tips excluded, not self-referred)."
                },
                "fundlies_organized": {
                  "type": "integer"
                }
              }
            }
          },
          "nearby": {
            "type": "array",
            "description": "Other cities with a page, the same metro first, then nearest (within 150 miles), at most 8.",
            "items": {
              "$ref": "#/components/schemas/CityCard"
            }
          },
          "gift_destinations": {
            "type": "array",
            "nullable": true,
            "description": "The top 5 cities by share of the money donors here gave; null below 5 donors.",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "has_page": {
                  "type": "boolean"
                },
                "share": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                }
              }
            }
          },
          "backed": {
            "type": "object",
            "nullable": true,
            "description": "What donors here backed; null below 5 donors.",
            "properties": {
              "fundlies": {
                "type": "integer"
              },
              "cities": {
                "type": "integer"
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "follow": {
            "$ref": "#/components/schemas/CityFollowBlock"
          }
        }
      },
      "FundraiserCity": {
        "type": "object",
        "nullable": true,
        "description": "Detail reads only. The Fundly's city while the Fundly is verified (approved, public, not deleted) and the city is not hidden; `null` otherwise. Link the location to `/cities/{slug}` only when `has_page`.",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "region": {
            "type": "string",
            "nullable": true
          },
          "label": {
            "type": "string"
          },
          "photo_url": {
            "type": "string",
            "nullable": true
          },
          "fundlies": {
            "type": "integer"
          },
          "donors": {
            "type": "integer",
            "nullable": true,
            "description": "Null when none."
          },
          "has_page": {
            "type": "boolean"
          }
        }
      },
      "CityUnsubscribeState": {
        "type": "object",
        "properties": {
          "city": {
            "type": "object",
            "properties": {
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "label": {
                "type": "string"
              }
            }
          },
          "kind": {
            "type": "string",
            "enum": [
              "digest",
              "instant"
            ]
          },
          "digest": {
            "type": "boolean"
          },
          "instant": {
            "type": "boolean"
          }
        }
      },
      "StoryCard": {
        "type": "object",
        "description": "One Fundly on the success stories pages (#2061). Every Fundly that has ended, raised more than $0 and passes the safety gates appears; there is no opt-in. The text fields are present only once the organizer-approved story is published.",
        "properties": {
          "fundraiser_id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string",
            "description": "The story's URL key (`/success-stories/{slug}`), stable even if the Fundly's slug changes."
          },
          "title": {
            "type": "string",
            "description": "The Fundly's title, in the reader's language when a translation exists."
          },
          "organizer": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "nullable": true
              },
              "avatar_url": {
                "type": "string",
                "nullable": true
              },
              "city": {
                "type": "string",
                "nullable": true,
                "description": "The Fundly's `location_label` (\"City, ST\","
              }
            }
          },
          "cover_image": {
            "type": "string",
            "nullable": true,
            "description": "The story's cover override, else the Fundly's cover."
          },
          "images": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Cover first, then the Fundly's public photos, at most 6."
          },
          "kind": {
            "$ref": "#/components/schemas/SuccessStoryKind"
          },
          "outcome": {
            "type": "string",
            "enum": [
              "ended_goal_reached",
              "ended_deadline",
              "ended_by_organizer",
              "ended_by_admin",
              "ended",
              "closed_by_organizer",
              "closed_by_admin",
              "closed"
            ],
            "description": "Why the Fundly stopped: `fundraising.outcome` (#2090), the same answer every campaign card carries. When donations were stopped, who stopped them: `closed_by_organizer`, `closed_by_admin` (FundlyHub staff), or `closed` when not known. Otherwise how it ended: at its goal, at its deadline, by the organizer, by FundlyHub staff, or `ended` when not known. An account deletion reads as `ended` or `closed`. The status to show is `fundraising.badge`."
          },
          "raised_cents": {
            "type": "integer",
            "description": "Settled and net of refunds, the same figure as the campaign page. Always a number."
          },
          "finished_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When it finished: the goal date for a fully funded Fundly, else when it ended, else when donations stopped, else the day after its end date. The `recent` sort orders by it."
          },
          "accepting_gifts": {
            "type": "boolean",
            "description": "`fundraising.accepting_donations`: the Fundly still takes gifts."
          },
          "has_story": {
            "type": "boolean",
            "description": "The organizer-approved story is published (show the \"Story\" pill)."
          },
          "headline": {
            "type": "string",
            "nullable": true,
            "description": "Published stories only."
          },
          "dek": {
            "type": "string",
            "nullable": true,
            "description": "Published stories only."
          },
          "is_project": {
            "type": "boolean"
          },
          "fundraising": {
            "$ref": "#/components/schemas/FundraisingState"
          }
        }
      },
      "SuccessStoryBreakdownRow": {
        "type": "object",
        "required": [
          "label",
          "amount_cents"
        ],
        "properties": {
          "label": {
            "type": "string",
            "maxLength": 120
          },
          "amount_cents": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "SuccessStoryRecord": {
        "type": "object",
        "description": "The Fundly's record, every field computed live from donations, referral attributions, payouts and the Fundly's own dates. A field nobody can compute is `null`, never a guess.",
        "properties": {
          "launched_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the organizer started the Fundly."
          },
          "verified_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When FundlyHub approved it, before its first gift."
          },
          "first_gift": {
            "type": "object",
            "nullable": true,
            "description": "The first gift, its donor sent as the campaign's donor wall sends one, so a client names it with the same pseudonym the wall shows: a null `donor_name` is aliased from `anonymous_key`, else from the gift `id`.",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "The gift, as the donor wall's row id."
              },
              "donor_href": {
                "type": "string",
                "nullable": true,
                "description": "Canonical donor wall profile route; anonymous and guest routes use opaque keys."
              },
              "donor_name": {
                "type": "string",
                "nullable": true,
                "description": "The donor's public name; null for an anonymous gift or a donor with no public name."
              },
              "is_anonymous": {
                "type": "boolean"
              },
              "anonymous_key": {
                "type": "string",
                "nullable": true,
                "description": "The anonymous identity's public key, the one the donor wall sends."
              },
              "amount_cents": {
                "type": "integer",
                "description": "What the gift raised, net of fees, tips excluded."
              },
              "at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "ambassadors": {
            "type": "object",
            "nullable": true,
            "description": "Ambassadors whose links brought settled gifts; null when none did.",
            "properties": {
              "count": {
                "type": "integer"
              },
              "names": {
                "type": "array",
                "maxItems": 3,
                "items": {
                  "type": "string"
                }
              },
              "gifts": {
                "type": "integer",
                "description": "Settled gifts that came through their links."
              }
            }
          },
          "halfway_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "The settled gift that took the running total to half the goal."
          },
          "goal_reached_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Fully funded Fundlies only."
          },
          "ended_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "end_reason": {
            "type": "string",
            "nullable": true,
            "enum": [
              "goal_reached",
              "deadline",
              "organizer",
              "admin",
              "account_deletion",
              "unknown"
            ]
          },
          "payout_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "The latest payout of the Fundly's settled gifts."
          },
          "donor_count": {
            "type": "integer"
          },
          "days_to_goal": {
            "type": "integer",
            "nullable": true,
            "description": "Whole days from launch (approval) to the goal, at least 1."
          },
          "days_live": {
            "type": "integer",
            "description": "Whole days from launch (approval) to the ending, at least 1."
          }
        }
      },
      "SuccessStoryText": {
        "type": "object",
        "description": "The organizer-approved words. Published stories only.",
        "properties": {
          "headline": {
            "type": "string",
            "nullable": true
          },
          "dek": {
            "type": "string",
            "nullable": true
          },
          "ask_excerpt": {
            "type": "string",
            "nullable": true,
            "description": "2-3 sentences quoted verbatim from the Fundly's own story."
          },
          "money_text": {
            "type": "string",
            "nullable": true,
            "description": "\"Where the money went\", in the organizer's words."
          },
          "breakdown": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SuccessStoryBreakdownRow"
            },
            "description": "The organizer's own report. FundlyHub verifies the Fundly and the payout, not each receipt."
          },
          "photo_url": {
            "type": "string",
            "nullable": true
          },
          "photo_caption": {
            "type": "string",
            "nullable": true
          },
          "now_text": {
            "type": "string",
            "nullable": true,
            "description": "\"Where things stand now\"."
          },
          "gifts_purpose": {
            "type": "string",
            "nullable": true,
            "description": "\"Anything given now goes to ___\". Null while the Fundly does not take gifts."
          },
          "written_with": {
            "type": "object",
            "nullable": true,
            "properties": {
              "name": {
                "type": "string"
              },
              "avatar_url": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "published_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SuccessStoryPage": {
        "type": "object",
        "properties": {
          "card": {
            "$ref": "#/components/schemas/StoryCard"
          },
          "story": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SuccessStoryText"
              }
            ],
            "nullable": true,
            "description": "Null until the story is published; the page then renders from the record."
          },
          "fundly": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string"
              },
              "story_excerpt": {
                "type": "string",
                "description": "The first 400 characters of the Fundly's own story, as plain text."
              },
              "url": {
                "type": "string",
                "description": "The Fundly's page path, `/f/{slug}` or `/p/{slug}`."
              }
            }
          },
          "photos": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The cover first, then every public photo of the Fundly."
          },
          "record": {
            "$ref": "#/components/schemas/SuccessStoryRecord"
          },
          "thanks": {
            "type": "object",
            "properties": {
              "donor_count": {
                "type": "integer"
              },
              "donors": {
                "type": "array",
                "maxItems": 6,
                "description": "Newest first, one per person, as the donor wall sends them: an anonymous or nameless donor has a null `donor_name` and no avatar, and the client names it with the wall's pseudonym from `anonymous_key`, else from the gift `id`.",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "The donor's latest gift, as the donor wall's row id."
                    },
                    "donor_href": {
                      "type": "string",
                      "nullable": true,
                      "description": "Canonical donor wall profile route; no private identity is disclosed."
                    },
                    "donor_name": {
                      "type": "string",
                      "nullable": true
                    },
                    "is_anonymous": {
                      "type": "boolean"
                    },
                    "anonymous_key": {
                      "type": "string",
                      "nullable": true
                    },
                    "avatar_url": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "more": {
            "type": "array",
            "maxItems": 3,
            "items": {
              "$ref": "#/components/schemas/StoryCard"
            }
          },
          "updates": {
            "type": "array",
            "maxItems": 20,
            "description": "The Fundly's own public updates (the campaign updates the organizer posts with `POST /projects/{fundraiserId}/updates`) posted on or after it finished (the goal date for a fully funded Fundly, else its ending), newest first.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "title": {
                  "type": "string",
                  "nullable": true
                },
                "body": {
                  "type": "string"
                },
                "created_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "images": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "SuccessStoryStatus": {
        "type": "string",
        "enum": [
          "draft",
          "organizer_review",
          "approved",
          "published",
          "hidden"
        ]
      },
      "SuccessStoryRow": {
        "type": "object",
        "description": "The whole success story record, as its owner and staff see it.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "fundraiser_id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/SuccessStoryStatus"
          },
          "headline": {
            "type": "string",
            "nullable": true
          },
          "dek": {
            "type": "string",
            "nullable": true
          },
          "ask_excerpt": {
            "type": "string",
            "nullable": true
          },
          "money_text": {
            "type": "string",
            "nullable": true
          },
          "breakdown": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SuccessStoryBreakdownRow"
            }
          },
          "photo_url": {
            "type": "string",
            "nullable": true
          },
          "photo_caption": {
            "type": "string",
            "nullable": true
          },
          "now_text": {
            "type": "string",
            "nullable": true
          },
          "gifts_purpose": {
            "type": "string",
            "nullable": true
          },
          "cover_url": {
            "type": "string",
            "nullable": true
          },
          "drafted_by": {
            "type": "string",
            "nullable": true,
            "enum": [
              "ai",
              "admin"
            ]
          },
          "ai_drafted_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "written_with_user_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "sent_to_organizer_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "organizer_approved_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "published_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "published_by": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "hidden_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "hidden_reason": {
            "type": "string",
            "nullable": true
          },
          "organizer_edited_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "The owner's last edit after publish; null when never."
          },
          "featured": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "fundraiser_title": {
            "type": "string"
          },
          "fundraiser_slug": {
            "type": "string"
          },
          "organizer_name": {
            "type": "string",
            "nullable": true
          },
          "organizer_avatar": {
            "type": "string",
            "nullable": true
          },
          "currency": {
            "type": "string"
          },
          "written_with": {
            "type": "object",
            "nullable": true,
            "description": "The organizer who approved the words.",
            "properties": {
              "name": {
                "type": "string"
              },
              "avatar_url": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "updates": {
            "type": "array",
            "maxItems": 20,
            "description": "The Fundly's own updates posted once it finished, newest first (as on the story page).",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "title": {
                  "type": "string",
                  "nullable": true
                },
                "body": {
                  "type": "string"
                },
                "created_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "images": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "fundraiser": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "title": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "is_project": {
                "type": "boolean"
              },
              "cover_image": {
                "type": "string",
                "nullable": true
              },
              "images": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "organizer": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string",
                "nullable": true
              },
              "avatar_url": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "kind": {
            "$ref": "#/components/schemas/SuccessStoryKind"
          },
          "raised_cents": {
            "type": "integer"
          },
          "accepting_gifts": {
            "type": "boolean"
          },
          "eligible": {
            "type": "boolean",
            "description": "Whether the Fundly passes the success story gates right now."
          }
        }
      },
      "SuccessStoryOwnerView": {
        "type": "object",
        "properties": {
          "story": {
            "$ref": "#/components/schemas/SuccessStoryRow"
          },
          "can_edit": {
            "type": "boolean",
            "description": "True in every status but `hidden`."
          },
          "can_approve": {
            "type": "boolean",
            "description": "True while the story is `draft` or `organizer_review`."
          }
        }
      },
      "OutcomeReport": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "fundraiserId": {
            "type": "string",
            "format": "uuid"
          },
          "authorId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "body": {
            "type": "string",
            "description": "Sanitised rich text (HTML)."
          },
          "attachments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OutcomeReportAttachment"
            }
          },
          "invoiceCount": {
            "type": "integer"
          },
          "publishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "hiddenAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CampaignEndorser": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "avatar": {
            "type": "string",
            "nullable": true
          },
          "slug": {
            "type": "string",
            "nullable": true,
            "description": "Profile slug."
          },
          "impressions": {
            "type": "integer",
            "description": "Human visits through this person's link."
          }
        }
      },
      "EndorsementResult": {
        "type": "object",
        "properties": {
          "endorsement": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "fundraiserId": {
                "type": "string",
                "format": "uuid"
              },
              "note": {
                "type": "string",
                "nullable": true
              },
              "createdAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "created": {
            "type": "boolean"
          }
        }
      },
      "EndorsementError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "not_found",
              "not_endorsable",
              "self_endorsement"
            ]
          }
        }
      },
      "EndorsementRequest": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "fundraiserId": {
            "type": "string",
            "format": "uuid"
          },
          "ambassadorUserId": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "sent",
              "failed"
            ]
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time"
          },
          "notifiedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "StockPhoto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "urls": {
            "type": "object",
            "properties": {
              "thumb": {
                "type": "string"
              },
              "small": {
                "type": "string"
              },
              "regular": {
                "type": "string"
              },
              "full": {
                "type": "string"
              }
            }
          },
          "alt": {
            "type": "string"
          },
          "photographer": {
            "type": "string"
          },
          "photographerUrl": {
            "type": "string"
          },
          "downloadLocation": {
            "type": "string",
            "description": "Pass to `POST /images/track-download` when the photo is chosen."
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          }
        }
      },
      "StorageBucket": {
        "type": "string",
        "description": "The folder an upload goes into. `community-photos` and `city-photos` hold community and city photos; `image-originals` holds the untouched original of a cropped image whose output is written by its own endpoint (an avatar, an organization logo or banner, badge art), so an edit can reopen on it.",
        "enum": [
          "fundraiser-images",
          "fundraiser-gallery",
          "fundraiser-drafts",
          "creator-tiers",
          "community-photos",
          "city-photos",
          "image-originals"
        ]
      },
      "ImageCropState": {
        "type": "object",
        "description": "Where a crop sits on the ORIGINAL image: the cropped area as percentages of the original after rotation, the zoom and a quarter-turn rotation.",
        "required": [
          "area",
          "zoom",
          "rotation"
        ],
        "properties": {
          "area": {
            "type": "object",
            "required": [
              "x",
              "y",
              "width",
              "height"
            ],
            "properties": {
              "x": {
                "type": "number",
                "minimum": 0,
                "maximum": 100
              },
              "y": {
                "type": "number",
                "minimum": 0,
                "maximum": 100
              },
              "width": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 100
              },
              "height": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 100
              }
            }
          },
          "zoom": {
            "type": "number",
            "minimum": 1,
            "maximum": 10
          },
          "rotation": {
            "type": "integer",
            "enum": [
              0,
              90,
              180,
              270
            ]
          }
        },
        "example": {
          "area": {
            "x": 12.5,
            "y": 0,
            "width": 75,
            "height": 100
          },
          "zoom": 1.2,
          "rotation": 0
        }
      },
      "CampaignEditorMedia": {
        "type": "array",
        "maxItems": 13,
        "description": "Optional ordered gallery replacing visible media atomically. First item is cover; empty clears visible media. At most 10 images and 3 videos. Unavailable and taken-down rows stay protected. New videos must be supported links. video_upload requires an existing owned row's matching id and URL. Omit to preserve legacy payload behavior.",
        "items": {
          "type": "object",
          "required": [
            "kind",
            "url"
          ],
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid"
            },
            "kind": {
              "type": "string",
              "enum": [
                "image",
                "video_link",
                "video_upload"
              ]
            },
            "url": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2048
            }
          }
        }
      },
      "CampaignGalleryMedia": {
        "type": "object",
        "description": "Safe visible gallery projection; unavailable and taken-down rows are omitted.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "image",
              "video_link",
              "video_upload"
            ]
          },
          "url": {
            "type": "string"
          },
          "thumbnail_url": {
            "type": "string",
            "nullable": true
          },
          "embed_url": {
            "type": "string",
            "nullable": true
          },
          "aspect_ratio": {
            "type": "string",
            "nullable": true,
            "description": "Width:height."
          },
          "is_cover": {
            "type": "boolean"
          }
        }
      },
      "FundraiserMedia": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "fundraiser_id": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "image",
              "video_link",
              "video_upload"
            ]
          },
          "url": {
            "type": "string"
          },
          "provider": {
            "type": "string",
            "nullable": true,
            "description": "Video provider, `cloudflare_stream` for uploads, or `unknown`."
          },
          "provider_video_id": {
            "type": "string",
            "nullable": true
          },
          "embed_url": {
            "type": "string",
            "nullable": true
          },
          "thumbnail_url": {
            "type": "string",
            "nullable": true
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "aspect_ratio": {
            "type": "string",
            "nullable": true
          },
          "width": {
            "type": "integer",
            "nullable": true
          },
          "height": {
            "type": "integer",
            "nullable": true
          },
          "duration_seconds": {
            "type": "number",
            "nullable": true
          },
          "file_size_bytes": {
            "type": "integer",
            "nullable": true
          },
          "playback_status": {
            "type": "string",
            "enum": [
              "processing",
              "ready",
              "errored",
              "taken_down"
            ]
          },
          "moderation_status": {
            "type": "string",
            "enum": [
              "ok",
              "dmca_pending",
              "dmca_taken_down"
            ]
          },
          "storage_path": {
            "type": "string",
            "nullable": true
          },
          "position": {
            "type": "integer"
          },
          "is_cover": {
            "type": "boolean"
          },
          "created_by": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "FundraiserMediaError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "NOT_FOUND",
              "FORBIDDEN",
              "CAP_EXCEEDED",
              "STREAM_NOT_CONFIGURED",
              "INVALID_URL",
              "INVALID_IMAGE_URL",
              "UNSUPPORTED_PROVIDER",
              "UPSTREAM_FAILED"
            ]
          }
        }
      },
      "AchievementError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "e.g. `NOT_FOUND`, `INVALID_INPUT`, `WITHDRAWN`, `RENDER_BUSY`."
          },
          "data": {
            "type": "object",
            "description": "On `WITHDRAWN`, the card's `code`.",
            "properties": {
              "code": {
                "type": "string"
              }
            }
          }
        }
      },
      "WalletStatus": {
        "type": "object",
        "required": [
          "available"
        ],
        "properties": {
          "available": {
            "type": "boolean",
            "description": "Whether Apple Wallet passes can be added right now."
          }
        }
      },
      "WalletPassLink": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "`GET /wallet/passes/{token}`, valid for ten minutes."
          }
        }
      },
      "WalletError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "`wallet_unavailable`, `NOT_CARD_HOLDER`, `LINK_EXPIRED` or `NOT_FOUND`; from the PassKit web service also `UNAUTHORIZED` and `INVALID_PUSH_TOKEN`."
          }
        }
      },
      "PassKitSerialNumbers": {
        "type": "object",
        "required": [
          "serialNumbers",
          "lastUpdated"
        ],
        "properties": {
          "serialNumbers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "lastUpdated": {
            "type": "string",
            "description": "Send back as `passesUpdatedSince` next time."
          }
        }
      },
      "AchievementVocabulary": {
        "type": "object",
        "additionalProperties": true,
        "description": "Admin-authored labels and colours, keyed by family (for example `tier` and `track`), each mapping a key to its label and `style` colours. Dynamic."
      },
      "AchievementArt": {
        "type": "object",
        "additionalProperties": true,
        "description": "How to draw the badge art.",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "image",
              "sheet",
              "none"
            ]
          }
        }
      },
      "AchievementLabel": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "label": {
            "type": "string"
          }
        }
      },
      "AchievementView": {
        "type": "object",
        "additionalProperties": true,
        "description": "One badge as a reader sees it. The main fields are listed; nested rarity, supply, series and progress objects are dynamic. Viewer fields (`earned`, `tier`, `progress`, …) are false or null for an anonymous reader.",
        "properties": {
          "slug": {
            "type": "string"
          },
          "track": {
            "type": "string"
          },
          "loop": {
            "type": "string"
          },
          "badge_art_url": {
            "type": "string",
            "nullable": true
          },
          "background_color": {
            "type": "string",
            "nullable": true
          },
          "art": {
            "$ref": "#/components/schemas/AchievementArt"
          },
          "status": {
            "type": "string"
          },
          "hidden_until_earned": {
            "type": "boolean"
          },
          "visibility": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "tagline": {
            "type": "string",
            "nullable": true
          },
          "persona_name": {
            "type": "string",
            "nullable": true
          },
          "persona_line": {
            "type": "string",
            "nullable": true
          },
          "how_to_earn": {
            "type": "string",
            "nullable": true
          },
          "what_counts": {
            "type": "string",
            "nullable": true
          },
          "story": {
            "type": "string",
            "nullable": true
          },
          "full_rules": {
            "type": "string",
            "nullable": true
          },
          "tiers": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "rarity": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true
          },
          "rarity_share_percent": {
            "type": "number",
            "nullable": true
          },
          "rarity_holders": {
            "type": "integer",
            "nullable": true
          },
          "rarity_population": {
            "type": "integer",
            "nullable": true
          },
          "rarity_computed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "series_number": {
            "type": "integer",
            "nullable": true
          },
          "issued": {
            "type": "integer",
            "nullable": true
          },
          "supply": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true
          },
          "earned": {
            "type": "boolean"
          },
          "holder": {
            "type": "object",
            "nullable": true,
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "user",
                  "organization"
                ]
              },
              "id": {
                "type": "string",
                "format": "uuid"
              }
            }
          },
          "tier": {
            "type": "string",
            "nullable": true
          },
          "awarded_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "tier_awarded_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "high_water_tier": {
            "type": "string",
            "nullable": true
          },
          "stats": {
            "type": "object",
            "nullable": true,
            "properties": {
              "value": {
                "type": "number"
              }
            }
          },
          "progress": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true
          },
          "visibility_override": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "AchievementFeedRow": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "The card's short code (`/cards/{code}`)."
          },
          "serial": {
            "type": "integer"
          },
          "event": {
            "type": "string",
            "enum": [
              "issued",
              "upgraded"
            ]
          },
          "tier": {
            "$ref": "#/components/schemas/AchievementLabel"
          },
          "species": {
            "type": "object",
            "properties": {
              "slug": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "art": {
                "$ref": "#/components/schemas/AchievementArt"
              },
              "background_color": {
                "type": "string",
                "nullable": true
              },
              "track": {
                "$ref": "#/components/schemas/AchievementLabel"
              }
            }
          },
          "frame_rarity": {
            "$ref": "#/components/schemas/AchievementLabel"
          },
          "holder": {
            "type": "object",
            "properties": {
              "short_name": {
                "type": "string",
                "nullable": true
              },
              "initials": {
                "type": "string",
                "nullable": true
              },
              "profile_path": {
                "type": "string",
                "nullable": true
              },
              "source": {
                "type": "string",
                "enum": [
                  "name",
                  "handle",
                  "none"
                ]
              }
            }
          },
          "cause": {
            "type": "object",
            "nullable": true,
            "properties": {
              "title": {
                "type": "string"
              },
              "path": {
                "type": "string"
              }
            }
          },
          "cause_label": {
            "type": "string",
            "nullable": true
          },
          "issued_bucket": {
            "type": "object",
            "description": "When it was issued, rounded to the minute or the hour.",
            "properties": {
              "start": {
                "type": "string",
                "format": "date-time"
              },
              "precision": {
                "type": "string",
                "enum": [
                  "minute",
                  "hour"
                ]
              }
            }
          }
        }
      },
      "AchievementEarnedCard": {
        "type": "object",
        "additionalProperties": true,
        "description": "One earned card. The main fields are listed; `evidence`, `stamp`, `ladder`, `rarity_line` and `cta` are dynamic objects.",
        "properties": {
          "code": {
            "type": "string"
          },
          "serial": {
            "type": "integer"
          },
          "issued": {
            "type": "integer"
          },
          "language": {
            "type": "string"
          },
          "species": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "slug": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "tagline": {
                "type": "string",
                "nullable": true
              },
              "art": {
                "$ref": "#/components/schemas/AchievementArt"
              },
              "background_color": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "holder": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "user",
                  "organization"
                ]
              },
              "first_name": {
                "type": "string",
                "nullable": true
              },
              "short_name": {
                "type": "string",
                "nullable": true
              },
              "initials": {
                "type": "string",
                "nullable": true
              },
              "profile_path": {
                "type": "string",
                "nullable": true
              },
              "source": {
                "type": "string",
                "enum": [
                  "name",
                  "handle",
                  "none"
                ]
              }
            }
          },
          "tier": {
            "$ref": "#/components/schemas/AchievementLabel"
          },
          "earned_on": {
            "$ref": "#/components/schemas/AchievementCardDate"
          },
          "tier_reached_on": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AchievementCardDate"
              }
            ],
            "nullable": true
          },
          "frame_rarity": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AchievementLabel"
              }
            ],
            "nullable": true
          },
          "issued_rarity": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AchievementLabel"
              }
            ],
            "nullable": true
          },
          "earned_sentence": {
            "type": "string",
            "nullable": true
          },
          "verify_url": {
            "type": "string"
          },
          "share": {
            "type": "object",
            "properties": {
              "og": {
                "type": "string"
              },
              "story": {
                "type": "string"
              },
              "post": {
                "type": "string"
              }
            }
          },
          "head": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string"
              },
              "description": {
                "type": "string"
              }
            }
          },
          "vocabulary": {
            "$ref": "#/components/schemas/AchievementVocabulary"
          },
          "owner": {
            "type": "object",
            "additionalProperties": true,
            "description": "Present only for the card's holder.",
            "properties": {
              "publicly_readable": {
                "type": "boolean"
              },
              "visibility_override": {
                "type": "string",
                "enum": [
                  "default",
                  "public",
                  "private"
                ]
              },
              "full_name": {
                "type": "string",
                "nullable": true
              }
            }
          }
        }
      },
      "AchievementCardDate": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string"
          },
          "precision": {
            "type": "string",
            "enum": [
              "day",
              "month"
            ]
          }
        }
      },
      "CommentReportReceipt": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "status": {
                "type": "string",
                "enum": [
                  "pending"
                ]
              },
              "created": {
                "type": "boolean",
                "description": "False when this updated your existing pending report."
              }
            }
          }
        }
      },
      "BlockState": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "user_id": {
                "type": "string",
                "format": "uuid"
              },
              "blocked": {
                "type": "boolean",
                "enum": [
                  true
                ]
              },
              "blocked_at": {
                "type": "string",
                "format": "date-time"
              },
              "follows_removed": {
                "type": "integer",
                "minimum": 0,
                "maximum": 2,
                "description": "Follow edges between the two removed by this call, in either direction."
              }
            }
          }
        }
      },
      "BlockedUser": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "The public name: never an email; the @handle or \"FundlyHub member\" when there is no name."
          },
          "avatar": {
            "type": "string",
            "nullable": true
          },
          "profile_slug": {
            "type": "string",
            "nullable": true
          },
          "blocked_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CodedError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "example": "INVALID_INPUT"
          }
        }
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "prefix": {
            "type": "string",
            "description": "First 12 characters of the key, for recognising it.",
            "example": "fh_live_3f9c"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Currently always `[\"*\"]` (the key carries all of its owner's permissions). Scopes are reserved for future use and cannot be set yet."
          },
          "last_used_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Omitted from the create response."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the key stops working. Every key created now has one; `null` appears only on keys created before expiry became mandatory, which keep working until revoked."
          },
          "revoked_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Omitted from the create response."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ProfileCampaignCard": {
        "type": "object",
        "description": "A campaign card built from the campaign's public fields, with the owner and stats joined on.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "owner_user_id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "summary": {
            "type": "string",
            "nullable": true
          },
          "goal_amount_cents": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "nullable": true
          },
          "tags": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            }
          },
          "cover_image": {
            "type": "string",
            "nullable": true
          },
          "images": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string"
            }
          },
          "video_url": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string"
          },
          "visibility": {
            "type": "string",
            "enum": [
              "public",
              "unlisted",
              "private"
            ]
          },
          "beneficiary_name": {
            "type": "string",
            "nullable": true
          },
          "location": {
            "type": "string",
            "nullable": true
          },
          "end_date": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "cover_image_focal_x": {
            "type": "number",
            "nullable": true
          },
          "cover_image_focal_y": {
            "type": "number",
            "nullable": true
          },
          "approved_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "source_language": {
            "type": "string",
            "nullable": true
          },
          "is_project": {
            "type": "boolean"
          },
          "type": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "profiles_name": {
            "type": "string",
            "nullable": true
          },
          "profiles_profile_slug": {
            "type": "string",
            "nullable": true
          },
          "profiles_avatar": {
            "type": "string",
            "nullable": true
          },
          "profiles_email_verified": {
            "type": "boolean",
            "nullable": true
          },
          "category_name": {
            "type": "string",
            "nullable": true
          },
          "total_raised_cents": {
            "type": "integer"
          },
          "donor_count": {
            "type": "integer"
          },
          "gallery": {
            "type": "array",
            "maxItems": 6,
            "description": "The campaign card's photos, at most six: the cover first, then its other public images in gallery order, each URL once. Images only — no videos, no photos taken down, no uploads still processing. Empty when the campaign has no photo. The same list and rule as `gallery` on `GET /fundraisers` items.",
            "items": {
              "type": "string"
            }
          },
          "profiles": {
            "type": "object",
            "nullable": true,
            "description": "The owner, nested. Null when the owner has no name.",
            "properties": {
              "name": {
                "type": "string"
              },
              "avatar": {
                "type": "string",
                "nullable": true
              },
              "email_verified": {
                "type": "boolean",
                "nullable": true
              },
              "profile_slug": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "is_endorsed": {
            "type": "boolean",
            "description": "True for a campaign this person endorsed rather than runs."
          },
          "translation_source": {
            "type": "string",
            "enum": [
              "source",
              "machine",
              "human"
            ],
            "description": "Present when a reader language was requested."
          },
          "original_title": {
            "type": "string",
            "nullable": true,
            "description": "Present when `title` was translated."
          },
          "original_summary": {
            "type": "string",
            "nullable": true,
            "description": "Present when `summary` was translated."
          }
        }
      },
      "RecentGift": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "amount_cents": {
            "type": "integer",
            "description": "Net of the Stripe fee."
          },
          "currency": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "comment": {
            "type": "string",
            "nullable": true,
            "description": "The donor's receipt note, else the legacy gift message."
          },
          "donor_name": {
            "type": "string",
            "nullable": true,
            "description": "Null for an anonymous gift."
          },
          "donor_avatar": {
            "type": "string",
            "nullable": true
          },
          "donor_city": {
            "type": "string",
            "nullable": true
          },
          "anonymous_key": {
            "type": "string",
            "nullable": true,
            "description": "A stable public key for an anonymous donor's page."
          },
          "donor_href": {
            "type": "string",
            "nullable": true,
            "description": "The donor's page — `/@slug`, `/d/guest/<key>` or `/d/anon/<key>`."
          },
          "gift_ordinal": {
            "type": "integer",
            "nullable": true,
            "description": "How many paid gifts this signed-in donor has made. Null for anonymous or guest gifts."
          },
          "fundraiser": {
            "type": "object",
            "properties": {
              "slug": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "image_url": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "via": {
            "type": "object",
            "nullable": true,
            "description": "The ambassador whose link drove the gift, if any.",
            "properties": {
              "name": {
                "type": "string"
              },
              "avatar": {
                "type": "string",
                "nullable": true
              },
              "slug": {
                "type": "string",
                "nullable": true
              }
            }
          }
        }
      },
      "HeroActivityEvent": {
        "type": "object",
        "description": "One chip. Discriminated on `kind`; which other fields are present depends on it — `donation`: actor, via, campaign, amount_cents, currency; `referral_views`: via, campaign, count; `referral_click`: via, campaign; `viewers`: campaign, count; `fundraiser_submitted`: nothing else; `achievement`: actor, achievement.",
        "required": [
          "id",
          "kind",
          "at",
          "live"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Opaque and stable."
          },
          "kind": {
            "type": "string",
            "enum": [
              "donation",
              "referral_views",
              "referral_click",
              "viewers",
              "fundraiser_submitted",
              "achievement"
            ]
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "live": {
            "type": "boolean"
          },
          "actor": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "nullable": true
              },
              "anonymous_key": {
                "type": "string",
                "nullable": true
              },
              "avatar": {
                "type": "string",
                "nullable": true
              },
              "href": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "via": {
            "type": "object",
            "nullable": true,
            "properties": {
              "name": {
                "type": "string"
              },
              "avatar": {
                "type": "string",
                "nullable": true
              },
              "href": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "campaign": {
            "type": "object",
            "properties": {
              "slug": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "href": {
                "type": "string"
              }
            }
          },
          "amount_cents": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "achievement": {
            "type": "object",
            "properties": {
              "slug": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "tier": {
                "type": "string",
                "nullable": true
              }
            }
          }
        }
      },
      "PlatformNumbers": {
        "type": "object",
        "properties": {
          "users": {
            "type": "integer",
            "description": "All-time active users from Google Analytics, or `registered_accounts` when GA is unavailable."
          },
          "users_source": {
            "type": "string",
            "enum": [
              "analytics",
              "accounts"
            ]
          },
          "registered_accounts": {
            "type": "integer",
            "description": "Excludes banned accounts."
          },
          "donations": {
            "type": "integer",
            "description": "Counted gifts (paid or refunded) to counted campaigns."
          },
          "median_gift_cents": {
            "type": "integer",
            "description": "The median of those gifts, each at what reached its creator, in integer cents."
          },
          "fundraisers_launched": {
            "type": "integer",
            "description": "Counted campaigns (approved, public, not deleted)."
          },
          "fundraisers_goal_reached": {
            "type": "integer",
            "description": "Counted campaigns that reached their goal."
          },
          "cities": {
            "type": "integer",
            "description": "The cities on the /cities index: every city with a verified Fundly or a donor, the same count as `totals.cities` on `GET /cities`. Replaces `cities_seen` and `cities_known_ratio`."
          },
          "ambassadors": {
            "type": "integer"
          },
          "ambassadors_active": {
            "type": "integer",
            "description": "Drove a counted gift in the last 30 days."
          },
          "raised_for_causes_cents": {
            "type": "integer",
            "description": "What reached the creators of every counted campaign, in integer cents: each counted gift at its donation less the Stripe fee, never the tip. The sum of the campaign cards."
          },
          "commission_taken_cents": {
            "type": "integer",
            "description": "Always `0` — FundlyHub takes no commission."
          },
          "computed_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PlatformTeamMember": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "handle": {
            "type": "string",
            "description": "The profile slug."
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "avatar": {
            "type": "string",
            "nullable": true
          },
          "role": {
            "type": "string",
            "enum": [
              "super_admin",
              "moderator"
            ]
          },
          "href": {
            "type": "string",
            "description": "Profile path."
          },
          "impact": {
            "type": "integer",
            "description": "Raised + given + driven, all time, in cents."
          }
        }
      },
      "PlatformAmbassador": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "handle": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "avatar": {
            "type": "string",
            "nullable": true
          },
          "href": {
            "type": "string"
          },
          "impact": {
            "type": "integer",
            "description": "raised + given + driven, cents."
          },
          "raised": {
            "type": "integer",
            "description": "Cents."
          },
          "given": {
            "type": "integer",
            "description": "Cents."
          },
          "driven": {
            "type": "integer",
            "description": "Cents."
          },
          "impressions": {
            "type": "integer"
          }
        }
      },
      "PlatformTipReceipt": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "amount_cents": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "one_time",
              "recurring"
            ]
          },
          "status": {
            "type": "string",
            "description": "The payment status, e.g. `pending`, `paid`, `failed`, `refunded`."
          },
          "settled_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "donor_name": {
            "type": "string",
            "nullable": true,
            "description": "The signed-in tipper's profile name; null for guests and anonymous tips."
          },
          "subscription": {
            "type": "object",
            "description": "Monthly tips only; absent on a failed one.",
            "properties": {
              "interval": {
                "type": "string",
                "enum": [
                  "month"
                ]
              },
              "amount_cents": {
                "type": "integer"
              },
              "status": {
                "type": "string",
                "enum": [
                  "confirming",
                  "active",
                  "cancelled",
                  "on_hold"
                ]
              },
              "started_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "next_charge_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "ends_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              }
            }
          }
        }
      },
      "CreatorTierInput": {
        "type": "object",
        "required": [
          "name",
          "amount_cents"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 100
          },
          "description": {
            "type": "string",
            "maxLength": 1000,
            "nullable": true
          },
          "amount_cents": {
            "type": "integer",
            "minimum": 1,
            "description": "Monthly price."
          },
          "currency": {
            "type": "string",
            "default": "USD",
            "description": "Upper-cased. Fixed once created."
          },
          "annual_amount_cents": {
            "type": "integer",
            "minimum": 1,
            "nullable": true,
            "description": "Omit for monthly-only billing."
          },
          "benefits": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "string",
              "maxLength": 200
            }
          },
          "cover_image": {
            "type": "string",
            "maxLength": 2048,
            "nullable": true
          },
          "sort_order": {
            "type": "integer",
            "default": 0
          },
          "subscriber_limit": {
            "type": "integer",
            "minimum": 1,
            "nullable": true,
            "description": "Cap on active subscribers, e.g. \"first 100 supporters\"."
          }
        }
      },
      "CreatorTier": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "creator_user_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "amount_cents": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          },
          "annual_amount_cents": {
            "type": "integer",
            "nullable": true
          },
          "benefits": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cover_image": {
            "type": "string",
            "nullable": true
          },
          "is_active": {
            "type": "boolean",
            "description": "False once archived."
          },
          "sort_order": {
            "type": "integer"
          },
          "subscriber_limit": {
            "type": "integer",
            "nullable": true
          },
          "stripe_product_id": {
            "type": "string",
            "nullable": true
          },
          "stripe_monthly_price_id": {
            "type": "string",
            "nullable": true
          },
          "stripe_annual_price_id": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CreatorSubscriptionStatus": {
        "type": "string",
        "enum": [
          "incomplete",
          "trialing",
          "active",
          "past_due",
          "canceled",
          "unpaid",
          "paused"
        ]
      },
      "CreatorSubscription": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "subscriber_user_id": {
            "type": "string",
            "format": "uuid"
          },
          "creator_user_id": {
            "type": "string",
            "format": "uuid"
          },
          "tier_id": {
            "type": "string",
            "format": "uuid"
          },
          "stripe_subscription_id": {
            "type": "string",
            "nullable": true
          },
          "stripe_price_id": {
            "type": "string"
          },
          "billing_interval": {
            "type": "string",
            "enum": [
              "month",
              "year"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/CreatorSubscriptionStatus"
          },
          "current_period_start": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "current_period_end": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "cancel_at_period_end": {
            "type": "boolean"
          },
          "canceled_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "started_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "tier_name": {
            "type": "string"
          },
          "tier_amount_cents": {
            "type": "integer"
          },
          "tier_annual_amount_cents": {
            "type": "integer",
            "nullable": true
          },
          "tier_currency": {
            "type": "string"
          },
          "creator_name": {
            "type": "string",
            "nullable": true
          },
          "creator_profile_slug": {
            "type": "string",
            "nullable": true
          },
          "creator_avatar": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "UnsubscribeRequest": {
        "type": "object",
        "required": [
          "token"
        ],
        "properties": {
          "token": {
            "type": "string",
            "description": "The signed token from the email's link."
          },
          "all": {
            "type": "boolean",
            "description": "`true` applies to every kind of mail rather than the token's scope."
          }
        }
      },
      "UnsubscribeResult": {
        "type": "object",
        "properties": {
          "email_masked": {
            "type": "string",
            "example": "j***e@example.com"
          },
          "scope": {
            "type": "string",
            "description": "`all`, or the email category the link was minted for."
          }
        }
      },
      "ReferralFundsByCurrency": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "currency": {
              "type": "string"
            },
            "amount_cents": {
              "type": "integer"
            }
          }
        }
      },
      "ReferralClicksByType": {
        "type": "object",
        "properties": {
          "human": {
            "type": "integer"
          },
          "bot": {
            "type": "integer"
          },
          "unknown": {
            "type": "integer"
          }
        }
      },
      "ReferralClickResult": {
        "type": "object",
        "properties": {
          "target_path": {
            "type": "string",
            "description": "Where to redirect — the campaign or home page, with `utm_*` preserved and the code in `utm_content`."
          },
          "visitor_id": {
            "type": "string",
            "format": "uuid"
          },
          "resolved": {
            "type": "boolean",
            "description": "Whether the code exists."
          },
          "recorded": {
            "type": "boolean",
            "description": "Whether a click row was written."
          }
        }
      },
      "ReferralAnalytics": {
        "type": "object",
        "properties": {
          "totals": {
            "type": "object",
            "properties": {
              "clicks_by_traffic_type": {
                "$ref": "#/components/schemas/ReferralClicksByType"
              },
              "distinct_human_visitors": {
                "type": "integer"
              },
              "conversions": {
                "type": "integer"
              },
              "funds_attributed": {
                "$ref": "#/components/schemas/ReferralFundsByCurrency"
              },
              "human_conversion_rate": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              }
            }
          },
          "by_fundraiser": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "fundraiser_id": {
                  "type": "string",
                  "format": "uuid",
                  "nullable": true
                },
                "fundraiser_title": {
                  "type": "string",
                  "nullable": true
                },
                "clicks_human": {
                  "type": "integer"
                },
                "clicks_bot": {
                  "type": "integer"
                },
                "clicks_unknown": {
                  "type": "integer"
                },
                "conversions": {
                  "type": "integer"
                },
                "funds_attributed": {
                  "$ref": "#/components/schemas/ReferralFundsByCurrency"
                }
              }
            }
          },
          "by_utm_source": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "utm_source": {
                  "type": "string",
                  "nullable": true
                },
                "clicks_human": {
                  "type": "integer"
                },
                "clicks_bot": {
                  "type": "integer"
                },
                "clicks_unknown": {
                  "type": "integer"
                },
                "conversions": {
                  "type": "integer"
                }
              }
            }
          },
          "time_series": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string",
                  "format": "date"
                },
                "clicks_human": {
                  "type": "integer"
                },
                "clicks_bot": {
                  "type": "integer"
                },
                "clicks_unknown": {
                  "type": "integer"
                },
                "conversions": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "AmbassadorGift": {
        "type": "object",
        "description": "One gift attributed to the caller's referral links, as the ambassador portal returns it. These are the only fields returned: no donor email, no payment card details and no receipt reference. For an anonymous gift `donor_name` is always `null`.",
        "properties": {
          "donation_id": {
            "type": "string",
            "format": "uuid",
            "description": "Stable row key."
          },
          "attributed_at": {
            "type": "string",
            "format": "date-time"
          },
          "donor_name": {
            "type": "string",
            "nullable": true,
            "description": "The donor's public name. Always `null` for an anonymous gift."
          },
          "donor_is_anonymous": {
            "type": "boolean"
          },
          "anonymous_key": {
            "type": "string",
            "nullable": true,
            "description": "For an anonymous gift, the opaque public key of the anonymous donor (the same key the campaign's donor wall sends), so clients give the donor the same alias everywhere. `null` otherwise."
          },
          "fundraiser_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "fundraiser_title": {
            "type": "string",
            "nullable": true
          },
          "amount_cents": {
            "type": "integer"
          },
          "tip_amount_cents": {
            "type": "integer"
          },
          "fee_amount_cents": {
            "type": "integer"
          },
          "net_amount_cents": {
            "type": "integer"
          },
          "raised_cents": {
            "type": "integer",
            "description": "What the gift raised: its ledger credit less its Stripe fee, the tip excluded. The figure every portal total sums."
          },
          "counted": {
            "type": "boolean",
            "description": "Whether the gift is in the portal's totals: paid or refunded, to a public campaign, and not self-referred."
          },
          "currency": {
            "type": "string",
            "nullable": true
          },
          "payment_status": {
            "type": "string",
            "nullable": true
          },
          "clicked_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the referral click that led to the gift happened, when known."
          },
          "seconds_to_convert": {
            "type": "number",
            "nullable": true
          },
          "is_self_referral": {
            "type": "boolean",
            "description": "The ambassador gave through their own link. Listed, never counted."
          }
        }
      },
      "AmbassadorPortalRange": {
        "type": "object",
        "description": "The window actually applied, after defaults.",
        "properties": {
          "from": {
            "type": "string",
            "format": "date-time"
          },
          "to": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AmbassadorPortalSummary": {
        "type": "object",
        "properties": {
          "totals": {
            "type": "object",
            "properties": {
              "clicks_by_traffic_type": {
                "$ref": "#/components/schemas/ReferralClicksByType"
              },
              "distinct_human_visitors": {
                "type": "integer"
              },
              "driven_gifts": {
                "type": "integer",
                "description": "Paid or refunded, non-self-referred gifts through the caller's links."
              },
              "raised_cents": {
                "type": "integer",
                "description": "What those gifts raised, net of fees, tips excluded. A refunded gift stays in it."
              },
              "tips_cents": {
                "type": "integer",
                "description": "The tips on those gifts, which are FundlyHub's and never part of `raised_cents`."
              },
              "distinct_donors": {
                "type": "integer"
              },
              "refunded_count": {
                "type": "integer",
                "description": "Of `driven_gifts`, how many were later refunded. Still counted."
              },
              "refunded_amount_cents": {
                "type": "integer",
                "description": "What those refunded gifts raised; included in `raised_cents`."
              },
              "human_conversion_rate": {
                "type": "number"
              },
              "currencies": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "funnel": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                }
              }
            }
          },
          "time_series": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string",
                  "format": "date"
                },
                "clicks_human": {
                  "type": "integer"
                },
                "clicks_bot": {
                  "type": "integer"
                },
                "clicks_unknown": {
                  "type": "integer"
                },
                "driven_gifts": {
                  "type": "integer"
                },
                "raised_cents": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "AmbassadorPortalTraffic": {
        "type": "object",
        "properties": {
          "by_source": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "clicks": {
                  "type": "integer"
                },
                "human": {
                  "type": "integer"
                },
                "driven_gifts": {
                  "type": "integer"
                }
              }
            }
          },
          "by_referer": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "clicks": {
                  "type": "integer"
                },
                "human": {
                  "type": "integer"
                }
              }
            }
          },
          "by_medium": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "clicks": {
                  "type": "integer"
                },
                "human": {
                  "type": "integer"
                }
              }
            }
          },
          "traffic_type": {
            "$ref": "#/components/schemas/ReferralClicksByType"
          },
          "geography": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "object",
              "properties": {
                "country": {
                  "type": "string"
                },
                "countryCode": {
                  "type": "string"
                },
                "sessions": {
                  "type": "integer"
                },
                "donations": {
                  "type": "integer"
                }
              }
            }
          },
          "devices": {
            "type": "object",
            "nullable": true,
            "properties": {
              "devices": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "device": {
                      "type": "string"
                    },
                    "sessions": {
                      "type": "integer"
                    },
                    "share": {
                      "type": "number"
                    }
                  }
                }
              },
              "browsers": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "browser": {
                      "type": "string"
                    },
                    "sessions": {
                      "type": "integer"
                    },
                    "share": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "ga_note": {
            "type": "string",
            "enum": [
              "ok",
              "unconfigured",
              "no_codes",
              "no_data"
            ]
          }
        }
      },
      "DmcaError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "NOT_FOUND",
              "FORBIDDEN",
              "INVALID_STATE",
              "INVALID_INPUT",
              "NO_TARGET"
            ]
          }
        }
      },
      "AchievementHolder": {
        "type": "object",
        "description": "The public name block. Never the full name or email.",
        "nullable": true,
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "user"
            ]
          },
          "first_name": {
            "type": "string",
            "nullable": true
          },
          "short_name": {
            "type": "string",
            "nullable": true,
            "example": "Vitaliy R."
          },
          "handle": {
            "type": "string",
            "nullable": true,
            "description": "Null when the handle would reveal the email."
          },
          "profile_path": {
            "type": "string"
          },
          "source": {
            "type": "string"
          }
        }
      },
      "AchievementPin": {
        "type": "object",
        "nullable": true,
        "description": "Null only when nothing is earned.",
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "pinned",
              "automatic"
            ]
          },
          "slug": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "nullable": true,
            "description": "The card code (`/c/{code}` on the site)."
          }
        }
      },
      "PublicSponsorError": {
        "type": "object",
        "description": "Every public sponsor refusal (#2315).",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "The machine reason, e.g. `not_found`, `sponsor_closed`, `already_confirmed`, `not_on_team`, `validation_error`."
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "additionalProperties": true
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "PublicPerkView": {
        "type": "object",
        "description": "What a perk is, read from its terms in force (the newest approved version already effective), its switches and the clock. `state`: live, scheduled (starts later), paused (by the sponsor, until `pause.until`, with the reason givers see), ended, stopped (by FundlyHub) or not_live. `upcoming` is a change already scheduled (a smaller perk or an ending takes effect 14 days out).",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "sponsorId": {
            "type": "string",
            "format": "uuid"
          },
          "versionId": {
            "type": "string",
            "format": "uuid"
          },
          "versionStatus": {
            "type": "string"
          },
          "position": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "value": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "percent_off",
                  "amount_off",
                  "free_item",
                  "bogo",
                  "upgrade",
                  "other"
                ]
              },
              "percentOff": {
                "type": "integer",
                "nullable": true
              },
              "maxDiscountCents": {
                "type": "integer",
                "nullable": true
              },
              "amountOffCents": {
                "type": "integer",
                "nullable": true
              },
              "minPurchaseCents": {
                "type": "integer",
                "nullable": true
              },
              "worthCents": {
                "type": "integer",
                "nullable": true
              }
            }
          },
          "who": {
            "type": "object",
            "description": "Holders of this tier of the achievement or higher.",
            "properties": {
              "achievementId": {
                "type": "string",
                "format": "uuid"
              },
              "achievementSlug": {
                "type": "string"
              },
              "tierId": {
                "type": "string",
                "format": "uuid"
              },
              "tier": {
                "type": "string",
                "enum": [
                  "base",
                  "bronze",
                  "silver",
                  "gold"
                ]
              }
            }
          },
          "where": {
            "type": "object",
            "properties": {
              "inStore": {
                "type": "boolean"
              },
              "allLocations": {
                "type": "boolean",
                "nullable": true
              },
              "locationIds": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "online": {
                "type": "boolean"
              }
            }
          },
          "frequency": {
            "type": "string",
            "enum": [
              "day",
              "week",
              "month",
              "year",
              "once"
            ]
          },
          "monthlyCap": {
            "type": "integer",
            "nullable": true
          },
          "hours": {
            "type": "array",
            "description": "ISO weekday (1 = Monday) and local \"HH:MM\" times; empty = whenever the location is open.",
            "items": {
              "type": "object",
              "properties": {
                "weekday": {
                  "type": "integer"
                },
                "startsAt": {
                  "type": "string"
                },
                "endsAt": {
                  "type": "string"
                }
              }
            }
          },
          "startsAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "endsAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "finePrint": {
            "type": "string",
            "nullable": true
          },
          "state": {
            "type": "string",
            "enum": [
              "live",
              "scheduled",
              "paused",
              "ended",
              "stopped",
              "not_live"
            ]
          },
          "effectiveAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "pause": {
            "type": "object",
            "nullable": true,
            "properties": {
              "until": {
                "type": "string",
                "format": "date-time"
              },
              "reason": {
                "type": "string"
              }
            }
          },
          "upcoming": {
            "type": "object",
            "nullable": true,
            "properties": {
              "versionId": {
                "type": "string",
                "format": "uuid"
              },
              "title": {
                "type": "string"
              },
              "effectiveAt": {
                "type": "string",
                "format": "date-time"
              },
              "endsAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              }
            }
          }
        }
      },
      "PublicPerkItem": {
        "type": "object",
        "description": "A perk with whether anyone can use it now and whether the viewer can.",
        "properties": {
          "perk": {
            "$ref": "#/components/schemas/PublicPerkView"
          },
          "availability": {
            "type": "object",
            "description": "The same for every viewer: `available`, `sponsor_paused` (with `until`), `sponsor_unavailable` (suspended, closed or not live yet), `key_paused` (FundlyHub paused the achievement, with `reason`), `cap_reached` (with `cap` and `resetsAt`, the 1st in the sponsor's time zone) or `out_of_codes` (an online perk).",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "available",
                  "sponsor_paused",
                  "sponsor_unavailable",
                  "key_paused",
                  "cap_reached",
                  "out_of_codes"
                ]
              },
              "until": {
                "type": "string",
                "format": "date-time"
              },
              "reason": {
                "type": "string"
              },
              "cap": {
                "type": "integer"
              },
              "resetsAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "eligibility": {
            "type": "object",
            "nullable": true,
            "description": "The viewer's, null when signed out: `ready`, `unlocks_on` (with `at`, 7 days after reaching the tier), `needs_tier` (with `heldTier`), `used` (as often as it allows), `perks_off`, `team_member`, `account` or `region`. Never a count toward a tier.",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "ready",
                  "unlocks_on",
                  "needs_tier",
                  "used",
                  "perks_off",
                  "team_member",
                  "account",
                  "region"
                ]
              },
              "at": {
                "type": "string",
                "format": "date-time"
              },
              "heldTier": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "saved": {
            "type": "boolean"
          },
          "watching": {
            "type": "boolean",
            "description": "The viewer asked to hear when an online perk's codes are back (\"Tell me when it's back\"); false when signed out."
          },
          "lastUsedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "lastUseId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "The viewer's last counted use (its receipt, where an online perk's one-time code is); null when signed out or never used."
          },
          "codeDays": {
            "type": "integer",
            "nullable": true,
            "description": "An online perk's code must be used within this many days (\"7-day code\"); null in store only."
          },
          "usedCount": {
            "type": "integer",
            "nullable": true,
            "description": "The perk's counted uses, for the sponsor's team and staff only."
          }
        }
      },
      "PublicPerkListItem": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PublicPerkItem"
          },
          {
            "type": "object",
            "properties": {
              "sponsor": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "slug": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "logoUrl": {
                    "type": "string",
                    "nullable": true
                  },
                  "categoryId": {
                    "type": "string",
                    "nullable": true
                  },
                  "timeZone": {
                    "type": "string",
                    "nullable": true
                  }
                }
              },
              "nearest": {
                "type": "object",
                "nullable": true,
                "properties": {
                  "label": {
                    "type": "string",
                    "nullable": true
                  },
                  "distanceMiles": {
                    "type": "number",
                    "nullable": true
                  },
                  "now": {
                    "type": "object",
                    "description": "Whether that place is open now: `open` (with `closesAt`), `closed` (with `opens`), `temporarily_closed` (with `until` and `reason`) or `no_hours`.",
                    "properties": {
                      "state": {
                        "type": "string",
                        "enum": [
                          "open",
                          "closed",
                          "temporarily_closed",
                          "no_hours"
                        ]
                      },
                      "closesAt": {
                        "type": "string"
                      },
                      "opens": {
                        "type": "object",
                        "nullable": true,
                        "properties": {
                          "weekday": {
                            "type": "integer"
                          },
                          "time": {
                            "type": "string"
                          }
                        }
                      },
                      "until": {
                        "type": "string",
                        "format": "date"
                      },
                      "reason": {
                        "type": "string",
                        "nullable": true
                      }
                    }
                  }
                }
              },
              "placeCount": {
                "type": "integer"
              }
            }
          }
        ]
      },
      "PerkAchievementRef": {
        "type": "object",
        "description": "An achievement a listed perk is for, in the reader's language, with its current canonical artwork and what each tier takes.",
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "art": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/AchievementArt"
              }
            ],
            "description": "Optional current artwork from achievement_art through artDescriptorOf; never derived from a slug."
          },
          "unit": {
            "type": "string",
            "enum": [
              "count",
              "cents"
            ],
            "description": "What its thresholds count. `cents` thresholds are money (5000 is $50)."
          },
          "units": {
            "type": "object",
            "description": "The noun its thresholds count, by plural form.",
            "properties": {
              "one": {
                "type": "string",
                "nullable": true
              },
              "few": {
                "type": "string",
                "nullable": true
              },
              "many": {
                "type": "string",
                "nullable": true
              },
              "other": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "tiers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "tier": {
                  "type": "string",
                  "enum": [
                    "base",
                    "bronze",
                    "silver",
                    "gold"
                  ]
                },
                "threshold": {
                  "type": "number"
                }
              }
            }
          }
        }
      },
      "PerkAchievementMap": {
        "type": "object",
        "description": "The achievements the listed perks are for, by id.",
        "additionalProperties": {
          "$ref": "#/components/schemas/PerkAchievementRef"
        }
      },
      "HeldPerkAchievement": {
        "type": "object",
        "properties": {
          "achievementId": {
            "type": "string",
            "format": "uuid"
          },
          "tier": {
            "type": "string",
            "enum": [
              "base",
              "bronze",
              "silver",
              "gold"
            ]
          },
          "cardCode": {
            "type": "string",
            "description": "The card's page is /c/{cardCode}."
          },
          "since": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When they reached this tier (\"You've held Bronze since Sep 2\"): the latest time it was recorded on their card, else when it was awarded."
          }
        }
      },
      "PublicSponsorCard": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "logoUrl": {
            "type": "string",
            "nullable": true
          },
          "categoryId": {
            "type": "string",
            "nullable": true
          },
          "area": {
            "type": "string",
            "nullable": true,
            "description": "The nearest (or home) location's name."
          },
          "cityLabel": {
            "type": "string",
            "nullable": true
          },
          "citySlug": {
            "type": "string",
            "nullable": true,
            "description": "Optional canonical slug of the shown location's city; null when the city has no public page."
          },
          "distanceMiles": {
            "type": "number",
            "nullable": true
          },
          "locationCount": {
            "type": "integer",
            "description": "Open storefronts."
          },
          "serviceArea": {
            "type": "boolean"
          },
          "serviceZipCount": {
            "type": "integer"
          },
          "onlineOnly": {
            "type": "boolean"
          },
          "followers": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "live",
              "paused"
            ]
          },
          "pausedUntil": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "headlinePerk": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicPerkView"
              }
            ]
          },
          "usableCount": {
            "type": "integer",
            "nullable": true,
            "description": "How many of its perks the viewer can use: they hold the perk's tier and its 7 days have passed (one they used as often as it allows still counts). Null when signed out."
          },
          "headlineAvailability": {
            "type": "object",
            "nullable": true,
            "description": "The lead perk's availability (as PublicPerkItem.availability)."
          },
          "headlineEligibility": {
            "type": "object",
            "nullable": true,
            "description": "The viewer's eligibility for the lead perk (as PublicPerkItem.eligibility); null when signed out."
          },
          "point": {
            "type": "object",
            "nullable": true,
            "description": "The shown storefront's map point.",
            "properties": {
              "lat": {
                "type": "number"
              },
              "lng": {
                "type": "number"
              }
            }
          },
          "offersHelp": {
            "type": "boolean",
            "description": "It has help in Find help (#2423): help anyone can find, read through its Resources provider. The \"Offers help\" tag. Always false while Resources are switched off."
          }
        }
      },
      "PublicSponsorDirectory": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicSponsorCard"
            }
          },
          "total": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "city": {
            "type": "object",
            "nullable": true,
            "properties": {
              "slug": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "hasPage": {
                "type": "boolean"
              },
              "sponsors": {
                "type": "integer"
              },
              "perksUsed": {
                "type": "integer"
              }
            }
          },
          "cityDefault": {
            "type": "boolean",
            "description": "The city is the signed-in viewer's own, not the address's."
          },
          "cities": {
            "type": "array",
            "description": "The cities with listed sponsors, most first (the city picker).",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "sponsors": {
                  "type": "integer"
                }
              }
            }
          },
          "sort": {
            "type": "string",
            "enum": [
              "nearest",
              "name"
            ]
          },
          "from": {
            "type": "string",
            "nullable": true,
            "description": "Where \"nearest\" is measured from: the viewer's own place; null for the browser's position or no point."
          },
          "achievements": {
            "$ref": "#/components/schemas/PerkAchievementMap"
          },
          "viewer": {
            "type": "object",
            "properties": {
              "signedIn": {
                "type": "boolean"
              },
              "perksOff": {
                "type": "boolean"
              },
              "held": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/HeldPerkAchievement"
                }
              },
              "usable": {
                "type": "object",
                "nullable": true,
                "description": "\"You can use 11 perks at 7 sponsors\": the perks the viewer can use, counted as My perks counts its Ready to use tab. Null when signed out.",
                "properties": {
                  "perks": {
                    "type": "integer"
                  },
                  "sponsors": {
                    "type": "integer"
                  }
                }
              },
              "example": {
                "type": "object",
                "nullable": true,
                "description": "For a signed-in viewer who holds no achievement yet: the achievement most sponsors here thank, how many, and one of its lowest-tier perks. Null otherwise.",
                "properties": {
                  "achievementId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "sponsors": {
                    "type": "integer"
                  },
                  "perkTitle": {
                    "type": "string"
                  },
                  "sponsorName": {
                    "type": "string"
                  },
                  "sponsorSlug": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "PublicSponsorCategory": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "policy": {
            "type": "string",
            "enum": [
              "allowed",
              "limited",
              "not_allowed"
            ]
          },
          "sponsors": {
            "type": "integer"
          }
        }
      },
      "PublicSponsorLocation": {
        "type": "object",
        "description": "An open location. `address` and `point` for a storefront only; `zips` for a business that comes to customers; an online-only base shows only its city. `city.slug` is set when the city has a page.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "sponsorId": {
            "type": "string",
            "format": "uuid"
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "kind": {
            "type": "string",
            "enum": [
              "premises",
              "service_area",
              "online"
            ]
          },
          "isPrimary": {
            "type": "boolean"
          },
          "tradingName": {
            "type": "string",
            "nullable": true
          },
          "pickupOnly": {
            "type": "boolean",
            "description": "A storefront where customers only pick up orders; its hours are pickup hours (\"Pickup only · Sat - Sun 9 AM - 1 PM\")."
          },
          "address": {
            "type": "object",
            "nullable": true,
            "properties": {
              "line1": {
                "type": "string"
              },
              "line2": {
                "type": "string"
              },
              "city": {
                "type": "string"
              },
              "region": {
                "type": "string"
              },
              "postal_code": {
                "type": "string"
              },
              "country": {
                "type": "string"
              }
            }
          },
          "point": {
            "type": "object",
            "nullable": true,
            "properties": {
              "lat": {
                "type": "number"
              },
              "lng": {
                "type": "number"
              }
            }
          },
          "city": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "slug": {
                "type": "string",
                "nullable": true
              },
              "label": {
                "type": "string"
              }
            }
          },
          "timeZone": {
            "type": "string"
          },
          "zips": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "hours": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "weekday": {
                  "type": "integer"
                },
                "opensAt": {
                  "type": "string"
                },
                "closesAt": {
                  "type": "string"
                }
              }
            }
          },
          "now": {
            "type": "object",
            "description": "`open` (with `closesAt`), `closed` (with `opens`), `temporarily_closed` (with `until` and `reason`) or `no_hours`.",
            "properties": {
              "state": {
                "type": "string",
                "enum": [
                  "open",
                  "closed",
                  "temporarily_closed",
                  "no_hours"
                ]
              },
              "closesAt": {
                "type": "string"
              },
              "opens": {
                "type": "object",
                "nullable": true,
                "properties": {
                  "weekday": {
                    "type": "integer"
                  },
                  "time": {
                    "type": "string"
                  }
                }
              },
              "until": {
                "type": "string",
                "format": "date"
              },
              "reason": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "closure": {
            "type": "object",
            "nullable": true,
            "properties": {
              "startsOn": {
                "type": "string",
                "format": "date"
              },
              "endsOn": {
                "type": "string",
                "format": "date"
              },
              "reason": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "addressConfirmed": {
            "type": "boolean"
          },
          "movedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When it moved to this address, within the last 30 days (\"New address\"; its old stickers stopped working); null otherwise."
          },
          "distanceMiles": {
            "type": "number",
            "nullable": true
          }
        }
      },
      "PublicSponsorUpdate": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "manual",
              "new_perk"
            ]
          },
          "body": {
            "type": "string"
          },
          "photoUrl": {
            "type": "string",
            "nullable": true
          },
          "perkId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "postedAs": {
            "type": "string",
            "enum": [
              "team",
              "staff",
              "system"
            ]
          },
          "author": {
            "type": "object",
            "nullable": true,
            "properties": {
              "name": {
                "type": "string"
              },
              "role": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "locations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "label": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PublicSponsorViewer": {
        "type": "object",
        "properties": {
          "signedIn": {
            "type": "boolean"
          },
          "following": {
            "type": "boolean"
          },
          "role": {
            "type": "string",
            "nullable": true,
            "description": "Their role on the team: owner, admin, manager or cashier."
          },
          "staff": {
            "type": "boolean"
          },
          "canManage": {
            "type": "boolean",
            "description": "May open the workspace."
          },
          "perksOff": {
            "type": "boolean"
          },
          "held": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HeldPerkAchievement"
            }
          },
          "usable": {
            "type": "integer",
            "nullable": true,
            "description": "\"You can use 2 of 5\": how many of the perks shown the viewer can use, counted as My perks counts its Ready to use tab. Null when signed out."
          }
        }
      },
      "PublicSponsorPage": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "renamed": {
            "type": "boolean",
            "description": "The key named an old slug."
          },
          "name": {
            "type": "string"
          },
          "logoUrl": {
            "type": "string",
            "nullable": true
          },
          "categoryId": {
            "type": "string",
            "nullable": true
          },
          "about": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "live",
              "paused",
              "suspended",
              "closed",
              "draft",
              "waiting_for_owner",
              "under_review",
              "changes_requested",
              "not_approved"
            ]
          },
          "pausedUntil": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "pauseMessage": {
            "type": "string",
            "nullable": true,
            "maxLength": 80,
            "description": "While the sponsor is paused, its own words after the date (\"Perks paused until Jan 3 - back after the holidays\"); null otherwise."
          },
          "closesAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "sponsorSince": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "operatedBy": {
            "type": "object",
            "nullable": true,
            "description": "A FundlyHub non-profit runs this business. Shopping there is not a donation.",
            "properties": {
              "name": {
                "type": "string"
              },
              "slug": {
                "type": "string",
                "nullable": true
              },
              "kind": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "home": {
            "type": "object",
            "nullable": true,
            "properties": {
              "cityId": {
                "type": "string",
                "format": "uuid"
              },
              "citySlug": {
                "type": "string",
                "nullable": true
              },
              "cityLabel": {
                "type": "string"
              },
              "timeZone": {
                "type": "string"
              }
            }
          },
          "otherCities": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string",
                  "nullable": true
                },
                "label": {
                  "type": "string"
                }
              }
            }
          },
          "stats": {
            "type": "object",
            "properties": {
              "followers": {
                "type": "integer"
              },
              "perksUsed": {
                "type": "integer"
              },
              "giversThanked": {
                "type": "integer",
                "nullable": true,
                "description": "Null under 5."
              },
              "perks": {
                "type": "integer"
              },
              "locations": {
                "type": "integer"
              }
            }
          },
          "city": {
            "type": "object",
            "nullable": true,
            "properties": {
              "slug": {
                "type": "string",
                "nullable": true
              },
              "label": {
                "type": "string"
              },
              "sponsors": {
                "type": "integer"
              },
              "perksUsed": {
                "type": "integer"
              },
              "photoUrl": {
                "type": "string",
                "nullable": true,
                "description": "The city's square photo (an https URL or an /uploads/ path); null when it has none."
              }
            }
          },
          "services": {
            "type": "array",
            "description": "What we offer, each item with the line about it.",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "description": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "finePrint": {
            "type": "array",
            "description": "Fine print for every perk, the lines the sponsor sets once; a perk's own fine print adds to them.",
            "items": {
              "type": "string"
            }
          },
          "links": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string"
                },
                "platform": {
                  "type": "string"
                },
                "label": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "contact": {
            "type": "object",
            "properties": {
              "email": {
                "type": "string",
                "nullable": true
              },
              "phone": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "names": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "main": {
                  "type": "boolean"
                },
                "locations": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "team": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "avatarUrl": {
                  "type": "string",
                  "nullable": true
                },
                "role": {
                  "type": "string"
                },
                "title": {
                  "type": "string",
                  "nullable": true
                },
                "locations": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "business": {
            "type": "object",
            "properties": {
              "legalName": {
                "type": "string",
                "nullable": true
              },
              "entityType": {
                "type": "string",
                "nullable": true
              },
              "registrationState": {
                "type": "string",
                "nullable": true
              },
              "openedYear": {
                "type": "integer",
                "nullable": true,
                "description": "The year the state registry says the business was formed (\"Open since 2017\"), from the registry check that passed."
              }
            }
          },
          "checks": {
            "type": "object",
            "description": "What FundlyHub checked and passed; a failed check is never public.",
            "properties": {
              "registry": {
                "type": "object",
                "nullable": true,
                "properties": {
                  "checkedAt": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              },
              "authority": {
                "type": "object",
                "nullable": true,
                "properties": {
                  "method": {
                    "type": "string",
                    "enum": [
                      "work_email",
                      "document",
                      "staff_evidence"
                    ]
                  },
                  "domain": {
                    "type": "string",
                    "nullable": true
                  }
                }
              },
              "sanctions": {
                "type": "object",
                "nullable": true,
                "properties": {
                  "checkedAt": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              },
              "addressesConfirmed": {
                "type": "array",
                "description": "Confirmed current addresses, labeled by custom location name or a public address/location fallback. Confirmation can come from staff or a mailed-sticker scan; sponsor approval alone is not address confirmation.",
                "items": {
                  "type": "string"
                }
              },
              "nextCheckAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              }
            }
          },
          "perks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicPerkItem"
            }
          },
          "achievements": {
            "$ref": "#/components/schemas/PerkAchievementMap"
          },
          "locations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicSponsorLocation"
            }
          },
          "updates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicSponsorUpdate"
            }
          },
          "viewer": {
            "$ref": "#/components/schemas/PublicSponsorViewer"
          },
          "teamWeek": {
            "type": "object",
            "nullable": true,
            "description": "The team's and staff's own numbers this week (Monday in the home city's time zone).",
            "properties": {
              "perksUsed": {
                "type": "integer"
              },
              "newFollowers": {
                "type": "integer"
              }
            }
          }
        }
      },
      "PublicSponsorPerks": {
        "type": "object",
        "properties": {
          "perks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicPerkItem"
            }
          },
          "finePrint": {
            "type": "array",
            "description": "The sponsor's fine print for every perk.",
            "items": {
              "type": "string"
            }
          },
          "achievements": {
            "$ref": "#/components/schemas/PerkAchievementMap"
          },
          "places": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "label": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "timeZone": {
            "type": "string",
            "nullable": true
          },
          "viewer": {
            "$ref": "#/components/schemas/PublicSponsorViewer"
          }
        }
      },
      "PublicSponsorPerk": {
        "type": "object",
        "properties": {
          "sponsor": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "logoUrl": {
                "type": "string",
                "nullable": true
              },
              "categoryId": {
                "type": "string",
                "nullable": true
              },
              "status": {
                "type": "string"
              },
              "pausedUntil": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              }
            }
          },
          "perk": {
            "$ref": "#/components/schemas/PublicPerkItem"
          },
          "finePrint": {
            "type": "array",
            "description": "The sponsor's fine print for every perk; the perk's own fine print adds to it.",
            "items": {
              "type": "string"
            }
          },
          "achievements": {
            "$ref": "#/components/schemas/PerkAchievementMap"
          },
          "places": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "label": {
                  "type": "string",
                  "nullable": true
                },
                "kind": {
                  "type": "string"
                },
                "now": {
                  "type": "object",
                  "additionalProperties": true
                },
                "closure": {
                  "type": "object",
                  "nullable": true,
                  "additionalProperties": true
                }
              }
            }
          },
          "liveSince": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "timeZone": {
            "type": "string",
            "nullable": true
          },
          "viewer": {
            "$ref": "#/components/schemas/PublicSponsorViewer"
          }
        }
      },
      "PublicSponsorImpact": {
        "type": "object",
        "properties": {
          "sponsorSince": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "perksUsed": {
            "type": "integer"
          },
          "giversThanked": {
            "type": "integer",
            "nullable": true
          },
          "followers": {
            "type": "integer"
          },
          "followersThisWeek": {
            "type": "integer"
          },
          "eventsSponsored": {
            "type": "integer",
            "nullable": true,
            "description": "Published events (not cancelled, suspended or deleted) that show this sponsor as a sponsor, past and upcoming. Null while Events are off."
          },
          "byPerk": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "perkId": {
                  "type": "string",
                  "format": "uuid"
                },
                "title": {
                  "type": "string"
                },
                "online": {
                  "type": "boolean"
                },
                "uses": {
                  "type": "integer"
                }
              }
            }
          },
          "byPlace": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "locationId": {
                  "type": "string",
                  "format": "uuid"
                },
                "label": {
                  "type": "string",
                  "nullable": true
                },
                "uses": {
                  "type": "integer"
                }
              }
            }
          },
          "online": {
            "type": "integer",
            "description": "Codes handed out for online perks."
          },
          "byMonth": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "month": {
                  "type": "string",
                  "example": "2026-07"
                },
                "uses": {
                  "type": "integer"
                }
              }
            }
          },
          "city": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true
          },
          "timeZone": {
            "type": "string"
          }
        }
      },
      "PublicSponsorFollow": {
        "type": "object",
        "properties": {
          "following": {
            "type": "boolean"
          },
          "followers": {
            "type": "integer"
          }
        }
      },
      "PublicSponsorReport": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "duplicate": {
            "type": "boolean"
          }
        }
      },
      "PublicStickerPage": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "real",
              "replaced",
              "location_closed",
              "ended",
              "unknown"
            ]
          },
          "sticker": {
            "type": "object",
            "nullable": true,
            "properties": {
              "formatId": {
                "type": "string",
                "enum": [
                  "door",
                  "round",
                  "counter"
                ]
              },
              "revokedAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              }
            }
          },
          "sponsor": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "logoUrl": {
                "type": "string",
                "nullable": true
              },
              "status": {
                "type": "string"
              },
              "sponsorSince": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "endedAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              }
            }
          },
          "location": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "label": {
                "type": "string",
                "nullable": true
              },
              "tradingName": {
                "type": "string",
                "nullable": true,
                "description": "The name the place trades under, when it is not the sponsor's (\"Fast Cat Roastery\")."
              },
              "kind": {
                "type": "string"
              },
              "line1": {
                "type": "string",
                "nullable": true,
                "description": "A storefront's street line only."
              }
            }
          },
          "city": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "slug": {
                "type": "string",
                "nullable": true
              },
              "name": {
                "type": "string",
                "description": "The city alone (\"Sacramento\"); label adds its state."
              },
              "label": {
                "type": "string"
              }
            }
          },
          "fundlies": {
            "type": "array",
            "description": "The city's Fundlies people can give to, as the city page lists them.",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "perks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicPerkItem"
            }
          },
          "achievements": {
            "$ref": "#/components/schemas/PerkAchievementMap"
          },
          "timeZone": {
            "type": "string",
            "nullable": true
          },
          "team": {
            "type": "object",
            "nullable": true,
            "properties": {
              "role": {
                "type": "string"
              },
              "addressConfirmed": {
                "type": "boolean"
              },
              "canConfirm": {
                "type": "boolean"
              },
              "kitDeliveredAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              }
            }
          },
          "viewer": {
            "type": "object",
            "properties": {
              "signedIn": {
                "type": "boolean"
              },
              "following": {
                "type": "boolean"
              }
            }
          }
        }
      },
      "PublicMyPerks": {
        "type": "object",
        "properties": {
          "tab": {
            "type": "string",
            "enum": [
              "ready",
              "other",
              "saved",
              "used"
            ]
          },
          "city": {
            "type": "object",
            "nullable": true,
            "description": "The city listed (the address's, or the person's own); null for every city.",
            "properties": {
              "slug": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "hasPage": {
                "type": "boolean"
              },
              "sponsors": {
                "type": "integer"
              },
              "perksUsed": {
                "type": "integer"
              }
            }
          },
          "cityDefault": {
            "type": "boolean"
          },
          "cities": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "sponsors": {
                  "type": "integer"
                }
              }
            }
          },
          "sort": {
            "type": "string",
            "enum": [
              "nearest",
              "name"
            ]
          },
          "from": {
            "type": "string",
            "nullable": true
          },
          "recent": {
            "type": "array",
            "description": "Their latest uses, on every tab (\"Recently used\"); each as in `uses`.",
            "items": {
              "type": "object"
            }
          },
          "counts": {
            "type": "object",
            "properties": {
              "ready": {
                "type": "integer"
              },
              "other": {
                "type": "integer"
              },
              "saved": {
                "type": "integer"
              },
              "used": {
                "type": "integer"
              }
            }
          },
          "perksOff": {
            "type": "boolean"
          },
          "accountHold": {
            "type": "boolean",
            "description": "The account is under review; no perks for now."
          },
          "held": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HeldPerkAchievement"
            }
          },
          "usable": {
            "type": "object",
            "description": "\"You can use 11 perks at 7 sponsors\": the Ready to use tab, by perks and by sponsors.",
            "properties": {
              "perks": {
                "type": "integer"
              },
              "sponsors": {
                "type": "integer"
              }
            }
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicPerkListItem"
            }
          },
          "uses": {
            "type": "array",
            "description": "The `used` tab, newest first. Each use's receipt is /perk-uses/{useId} on the site.",
            "items": {
              "type": "object",
              "properties": {
                "useId": {
                  "type": "string",
                  "format": "uuid"
                },
                "at": {
                  "type": "string",
                  "format": "date-time"
                },
                "perk": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "title": {
                      "type": "string"
                    }
                  }
                },
                "sponsor": {
                  "type": "object",
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    }
                  }
                },
                "location": {
                  "type": "object",
                  "nullable": true,
                  "properties": {
                    "label": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "unlocking": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "achievementId": {
                  "type": "string",
                  "format": "uuid"
                },
                "tier": {
                  "type": "string"
                },
                "at": {
                  "type": "string",
                  "format": "date-time"
                },
                "perks": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "title": {
                        "type": "string"
                      },
                      "sponsorSlug": {
                        "type": "string"
                      },
                      "sponsorName": {
                        "type": "string"
                      },
                      "logoUrl": {
                        "type": "string",
                        "nullable": true
                      },
                      "distanceMiles": {
                        "type": "number",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "achievements": {
            "$ref": "#/components/schemas/PerkAchievementMap"
          },
          "total": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          }
        }
      },
      "PublicCardPerks": {
        "type": "object",
        "properties": {
          "achievement": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "slug": {
                "type": "string"
              }
            }
          },
          "tier": {
            "type": "string",
            "enum": [
              "base",
              "bronze",
              "silver",
              "gold"
            ]
          },
          "unlocks": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "sponsors": {
                "type": "integer"
              },
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PublicPerkListItem"
                }
              }
            }
          },
          "higher": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "tier": {
                  "type": "string",
                  "enum": [
                    "base",
                    "bronze",
                    "silver",
                    "gold"
                  ]
                },
                "total": {
                  "type": "integer"
                },
                "sample": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "title": {
                        "type": "string"
                      },
                      "sponsorName": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "achievements": {
            "$ref": "#/components/schemas/PerkAchievementMap"
          },
          "perksOff": {
            "type": "boolean"
          }
        }
      },
      "ResourcePublicError": {
        "type": "object",
        "description": "Every public Resources refusal (#2423).",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "The machine reason, e.g. `validation_error`, `unknown_city`, `unknown_zip`, `no_city_near`, `unknown_kind`, `not_found`, `too_many_reports`, `too_many_suggestions`, `invalid_phone`, `invalid_website`, `unavailable`."
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "additionalProperties": true
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "ResourceOpenState": {
        "type": "object",
        "description": "Now, in the place's own time zone: `open` (until `closesAt`, local, which may be after midnight), `closed` (with the next opening this week, or null), `closed_today` (a special date closes today, with its reason, until `until`) or `no_hours`.",
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "open",
              "closed",
              "closed_today",
              "no_hours"
            ]
          },
          "closesAt": {
            "type": "string",
            "example": "17:00"
          },
          "opens": {
            "type": "object",
            "nullable": true,
            "properties": {
              "date": {
                "type": "string",
                "format": "date"
              },
              "weekday": {
                "type": "integer",
                "minimum": 1,
                "maximum": 7,
                "description": "ISO weekday",
                "1 is Monday.": null
              },
              "time": {
                "type": "string",
                "example": "09:00"
              }
            }
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "until": {
            "type": "string",
            "format": "date"
          }
        },
        "required": [
          "state"
        ]
      },
      "ResourceCityRef": {
        "type": "object",
        "nullable": true,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string",
            "nullable": true,
            "description": "Only when the city has a page."
          },
          "label": {
            "type": "string",
            "example": "Folsom, CA"
          },
          "hasPage": {
            "type": "boolean"
          }
        }
      },
      "ResourceProviderCard": {
        "type": "object",
        "description": "A provider as a list shows it. Its name, logo and city are its organization's, business's or community's own. A person (#2436, `kind: person`, \"Individual\") shows their public name, profile photo and city, and nothing else of their profile: never its email or phone. The only contact is what the help itself lists.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string",
            "description": "Its page: /resources/{slug}."
          },
          "kind": {
            "type": "string",
            "enum": [
              "nonprofit",
              "business",
              "community",
              "program",
              "person"
            ]
          },
          "isChurch": {
            "type": "boolean",
            "description": "A non-profit FundlyHub classifies as a church."
          },
          "name": {
            "type": "string"
          },
          "logoUrl": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "$ref": "#/components/schemas/ResourceCityRef"
          },
          "verified": {
            "type": "boolean",
            "description": "Shown with the verified mark: a non-profit, a business or a public program; never a community or a person."
          },
          "trust": {
            "type": "string",
            "enum": [
              "irs",
              "business_checked",
              "leaders_checked",
              "official_source",
              "listing_reviewed"
            ],
            "description": "How FundlyHub checked it: a person's help is each reviewed by staff (listing_reviewed)."
          },
          "proudSponsor": {
            "type": "boolean",
            "description": "A business that is also a FundlyHub sponsor."
          },
          "entity": {
            "type": "object",
            "nullable": true,
            "description": "Its own page: /nonprofits/{slug}, /sponsors/{slug} (sponsors only) or /communities/{slug}.",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "nonprofit",
                  "sponsor",
                  "community"
                ]
              },
              "slug": {
                "type": "string"
              }
            }
          },
          "community": {
            "type": "object",
            "nullable": true,
            "description": "A community's visibility and how people join (Join, or Request to join).",
            "properties": {
              "visibility": {
                "type": "string",
                "enum": [
                  "public",
                  "private"
                ]
              },
              "joinApproval": {
                "type": "string",
                "enum": [
                  "none",
                  "leaders"
                ]
              },
              "kind": {
                "type": "string"
              }
            }
          }
        }
      },
      "ResourceCard": {
        "type": "object",
        "description": "One kind of help, as a card shows it.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "providerId": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "costModel": {
            "type": "string",
            "enum": [
              "free",
              "free_if_qualify",
              "sliding_scale",
              "flat_fee",
              "free_consult_then_fee",
              "suggested_donation"
            ]
          },
          "feeMinCents": {
            "type": "integer",
            "nullable": true
          },
          "feeMaxCents": {
            "type": "integer",
            "nullable": true
          },
          "audience": {
            "type": "string",
            "enum": [
              "everyone",
              "members",
              "members_approved"
            ],
            "description": "Members-only help says so."
          },
          "faithParticipation": {
            "type": "boolean",
            "description": "A church's help asks people to join a service or class."
          },
          "faithNote": {
            "type": "string",
            "nullable": true,
            "maxLength": 140,
            "example": "A short prayer before the pantry opens",
            "description": "What a church's help asks people to join, as the church wrote it (CH-01). Only with `faithParticipation`; null otherwise."
          },
          "eligibility": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "incomeLimitPctFpl": {
            "type": "integer",
            "nullable": true
          },
          "howToStart": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "walk_in",
                "appointment",
                "phone",
                "online",
                "home_visit"
              ]
            }
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "delivery": {
            "type": "string",
            "enum": [
              "none",
              "available",
              "required"
            ]
          },
          "referralRequired": {
            "type": "boolean"
          },
          "stockNote": {
            "type": "string",
            "nullable": true
          },
          "stockNoteAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "capacity": {
            "type": "string",
            "enum": [
              "taking",
              "waitlist",
              "paused"
            ]
          },
          "capacityNote": {
            "type": "string",
            "nullable": true
          },
          "pausedUntil": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "online": {
            "type": "boolean"
          },
          "confidentialAddress": {
            "type": "boolean",
            "description": "Its address is given by phone: never a street or a pin."
          },
          "lastConfirmedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "mayBeOutOfDate": {
            "type": "boolean",
            "description": "Not confirmed in over 120 days: \"May be out of date, call to check\"."
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Topic slugs",
            "the primary one first.": null
          },
          "primaryTopic": {
            "type": "string",
            "nullable": true
          },
          "needs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "now": {
            "$ref": "#/components/schemas/ResourceOpenState"
          }
        }
      },
      "ResourceDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ResourceCard"
          },
          {
            "type": "object",
            "properties": {
              "details": {
                "type": "string",
                "nullable": true
              },
              "applyUrl": {
                "type": "string",
                "nullable": true
              },
              "phone": {
                "type": "string",
                "nullable": true,
                "example": "+19165550142"
              },
              "referralNote": {
                "type": "string",
                "nullable": true
              },
              "hoursSource": {
                "type": "string",
                "enum": [
                  "location",
                  "own"
                ]
              },
              "hours": {
                "type": "array",
                "description": "Its own week, when `hoursSource` is `own`.",
                "items": {
                  "type": "object",
                  "properties": {
                    "weekday": {
                      "type": "integer",
                      "minimum": 1,
                      "maximum": 7
                    },
                    "opensAt": {
                      "type": "string",
                      "example": "09:00"
                    },
                    "closesAt": {
                      "type": "string",
                      "example": "17:00"
                    }
                  }
                }
              },
              "timeZone": {
                "type": "string",
                "nullable": true
              },
              "locationIds": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Where it happens: ids in the page's `locations`."
              },
              "serviceAreas": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "city",
                        "zip",
                        "state",
                        "nationwide"
                      ]
                    },
                    "label": {
                      "type": "string"
                    },
                    "citySlug": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "ResourceLocation": {
        "type": "object",
        "description": "A place help happens. The street address, its name and its map point only for a public storefront that no confidential help shares; otherwise the city alone.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "$ref": "#/components/schemas/ResourceCityRef"
          },
          "address": {
            "type": "object",
            "nullable": true,
            "properties": {
              "line1": {
                "type": "string"
              },
              "line2": {
                "type": "string"
              },
              "city": {
                "type": "string"
              },
              "region": {
                "type": "string"
              },
              "postal_code": {
                "type": "string"
              },
              "country": {
                "type": "string"
              }
            }
          },
          "point": {
            "type": "object",
            "nullable": true,
            "properties": {
              "lat": {
                "type": "number"
              },
              "lng": {
                "type": "number"
              }
            }
          },
          "addressGivenByPhone": {
            "type": "boolean",
            "description": "Confidential: \"Address given by phone\", never a pin."
          },
          "timeZone": {
            "type": "string",
            "nullable": true
          },
          "hours": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "weekday": {
                  "type": "integer"
                },
                "opensAt": {
                  "type": "string"
                },
                "closesAt": {
                  "type": "string"
                }
              }
            }
          },
          "now": {
            "$ref": "#/components/schemas/ResourceOpenState"
          }
        }
      },
      "ResourceSimilarProvider": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "nonprofit",
              "business",
              "community",
              "program",
              "person"
            ]
          },
          "isChurch": {
            "type": "boolean"
          },
          "logoUrl": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "ResourceSearchRequest": {
        "type": "object",
        "description": "At most one of `city`, `zip` and `point`; none is every city.",
        "properties": {
          "city": {
            "type": "string",
            "description": "A city page's slug."
          },
          "zip": {
            "type": "string",
            "pattern": "^[0-9]{5}$",
            "description": "A US ZIP code; it resolves to its city."
          },
          "point": {
            "type": "object",
            "description": "A point the person chose to share; it resolves to the nearest city within 60 miles and sorts by distance from itself.",
            "properties": {
              "lat": {
                "type": "number",
                "minimum": -90,
                "maximum": 90
              },
              "lng": {
                "type": "number",
                "minimum": -180,
                "maximum": 180
              }
            },
            "required": [
              "lat",
              "lng"
            ]
          },
          "topic": {
            "type": "string",
            "description": "A topic's slug; its child topics match too."
          },
          "needs": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "type": "string"
            },
            "description": "Need slugs (type of help)."
          },
          "cost": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "free",
                "free_if_qualify",
                "sliding_scale",
                "flat_fee",
                "free_consult_then_fee",
                "suggested_donation"
              ]
            }
          },
          "openNow": {
            "type": "boolean",
            "default": false,
            "description": "Open now in the place's time zone, or online help that keeps no hours. Open ones rank first."
          },
          "language": {
            "type": "string",
            "example": "es"
          },
          "online": {
            "type": "boolean",
            "default": false,
            "description": "By phone or online."
          },
          "taking": {
            "type": "boolean",
            "default": false,
            "description": "Taking new people."
          },
          "howToStart": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "walk_in",
                "appointment",
                "phone",
                "online",
                "home_visit"
              ]
            }
          },
          "providerKinds": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "nonprofit",
                "church",
                "business",
                "community",
                "program",
                "person"
              ]
            }
          },
          "q": {
            "type": "string",
            "maxLength": 200,
            "description": "From 2 characters (80 are used): titles, summaries, provider names, topic names and synonyms in any language, and need names."
          },
          "limit": {
            "type": "integer",
            "default": 24,
            "maximum": 48
          },
          "offset": {
            "type": "integer",
            "default": 0
          }
        }
      },
      "ResourceSearch": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/ResourceProviderCard"
                },
                {
                  "type": "object",
                  "properties": {
                    "distanceMiles": {
                      "type": "number",
                      "nullable": true,
                      "description": "To its nearest public storefront; null for online or confidential help",
                      "or with no place.": null
                    },
                    "point": {
                      "type": "object",
                      "nullable": true,
                      "description": "The map pin, its nearest public storefront. Null is \"Help by phone or online\".",
                      "properties": {
                        "lat": {
                          "type": "number"
                        },
                        "lng": {
                          "type": "number"
                        }
                      }
                    },
                    "openNow": {
                      "type": "boolean",
                      "nullable": true
                    },
                    "matching": {
                      "type": "integer",
                      "description": "How many of its resources match."
                    },
                    "resourceCount": {
                      "type": "integer",
                      "description": "All its help in Find help."
                    },
                    "resources": {
                      "type": "array",
                      "maxItems": 3,
                      "items": {
                        "$ref": "#/components/schemas/ResourceCard"
                      }
                    },
                    "lastConfirmedAt": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    }
                  }
                }
              ]
            }
          },
          "total": {
            "type": "integer",
            "description": "Providers in all."
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "where": {
            "type": "object",
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "all",
                  "city"
                ]
              },
              "from": {
                "type": "string",
                "enum": [
                  "city",
                  "zip",
                  "point"
                ]
              },
              "city": {
                "type": "object",
                "properties": {
                  "slug": {
                    "type": "string"
                  },
                  "label": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "facets": {
            "type": "object",
            "description": "Each counts providers with every other filter applied and its own left out.",
            "properties": {
              "topics": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              },
              "needs": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "topic": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              },
              "cost": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "model": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              },
              "languages": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              },
              "online": {
                "type": "integer"
              },
              "taking": {
                "type": "integer"
              },
              "openNow": {
                "type": "integer",
                "nullable": true,
                "description": "Counted only while `openNow` is asked for."
              }
            }
          },
          "relax": {
            "type": "object",
            "nullable": true,
            "description": "With no results: how many providers each applied filter, removed alone, would bring back (`topic`, `needs`, `cost`, `language`, `online`, `taking`, `howToStart`, `providerKinds`, `q`, `openNow`).",
            "additionalProperties": {
              "type": "integer"
            }
          }
        }
      },
      "ResourceTopics": {
        "type": "object",
        "properties": {
          "language": {
            "type": "string",
            "enum": [
              "en",
              "ru",
              "uk",
              "es"
            ]
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "parent": {
                  "type": "string",
                  "nullable": true
                },
                "name": {
                  "type": "string"
                },
                "summary": {
                  "type": "string",
                  "nullable": true
                },
                "sensitive": {
                  "type": "boolean",
                  "description": "Quick exit, and never in a URL, a page title, analytics or a notification."
                },
                "licensed": {
                  "type": "boolean"
                },
                "firstSteps": {
                  "type": "array",
                  "maxItems": 3,
                  "items": {
                    "type": "string"
                  },
                  "description": "Written and reviewed by staff; empty until reviewed."
                },
                "fundraiserCategory": {
                  "type": "string",
                  "nullable": true
                },
                "hotlines": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Hotline slugs",
                  "in order.": null
                },
                "needs": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "slug": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "hotlines": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "note": {
                  "type": "string",
                  "nullable": true
                },
                "tel": {
                  "type": "string",
                  "example": "988"
                },
                "telDisplay": {
                  "type": "string"
                },
                "sms": {
                  "type": "string",
                  "nullable": true
                },
                "smsKeyword": {
                  "type": "string",
                  "nullable": true
                },
                "urgent": {
                  "type": "boolean"
                }
              }
            }
          },
          "urgent": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The urgent strip, in order: 911, 988, 211."
          }
        }
      },
      "ResourceProviderPage": {
        "type": "object",
        "description": "`listed`: the provider, every resource the viewer may see, its places and its verified licenses. `not_listed`: nothing of it is public now (\"No longer listed\"), with similar providers and nothing else about it.",
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "listed",
              "not_listed"
            ]
          },
          "slug": {
            "type": "string",
            "description": "With `not_listed`."
          },
          "provider": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResourceProviderCard"
              },
              {
                "type": "object",
                "properties": {
                  "about": {
                    "type": "string",
                    "nullable": true
                  },
                  "website": {
                    "type": "string",
                    "nullable": true
                  },
                  "phone": {
                    "type": "string",
                    "nullable": true
                  },
                  "memberCount": {
                    "type": "integer",
                    "nullable": true,
                    "description": "A public community's active members; never the members."
                  },
                  "partOf": {
                    "type": "object",
                    "nullable": true,
                    "properties": {
                      "slug": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      },
                      "entitySlug": {
                        "type": "string",
                        "nullable": true
                      }
                    }
                  },
                  "viewerIsMember": {
                    "type": "boolean"
                  },
                  "lastConfirmedAt": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  },
                  "mayBeOutOfDate": {
                    "type": "boolean"
                  }
                }
              }
            ]
          },
          "resources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResourceDetail"
            }
          },
          "locations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResourceLocation"
            }
          },
          "licenses": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A verified license. Never its number.",
              "properties": {
                "holderName": {
                  "type": "string"
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "attorney",
                    "physician",
                    "nurse",
                    "mental_health",
                    "tax_preparer",
                    "other"
                  ]
                },
                "state": {
                  "type": "string"
                },
                "checkedAt": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true
                }
              }
            }
          },
          "similar": {
            "type": "array",
            "maxItems": 3,
            "items": {
              "$ref": "#/components/schemas/ResourceSimilarProvider"
            }
          }
        },
        "required": [
          "state"
        ]
      },
      "ResourceForEntity": {
        "type": "object",
        "properties": {
          "provider": {
            "type": "object",
            "nullable": true,
            "description": "The provider page's slug, for See all; null when there is no help the viewer may see.",
            "properties": {
              "slug": {
                "type": "string"
              }
            }
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResourceCard"
            }
          },
          "total": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          }
        }
      },
      "ResourceReport": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "duplicate": {
            "type": "boolean",
            "description": "The same reporter already reported this resource today; this is that report."
          }
        }
      },
      "ResourceSaves": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "providerId": {
                  "type": "string",
                  "format": "uuid"
                },
                "slug": {
                  "type": "string",
                  "description": "Its page: /resources/{slug}."
                },
                "savedAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "listed": {
                  "type": "boolean",
                  "description": "It still has help the person may see; false is \"No longer listed\"."
                },
                "provider": {
                  "nullable": true,
                  "description": "Its card while listed; null otherwise.",
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ResourceProviderCard"
                    }
                  ]
                }
              }
            }
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "CommunityPerson": {
        "type": "object",
        "description": "A person, never an email.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "avatar_url": {
            "type": "string",
            "nullable": true
          },
          "handle": {
            "type": "string",
            "nullable": true
          },
          "href": {
            "type": "string",
            "nullable": true
          },
          "hidden": {
            "type": "boolean",
            "description": "A private profile: name \"A member\", no face, no link."
          }
        },
        "additionalProperties": true
      },
      "CommunityCard": {
        "type": "object",
        "description": "A community card (directory, home, profile, the share step).",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "href": {
            "type": "string",
            "example": "/communities/city-of-goodness"
          },
          "kind": {
            "type": "string",
            "enum": [
              "city",
              "church",
              "diaspora",
              "families",
              "school",
              "workplace",
              "other"
            ]
          },
          "city_text": {
            "type": "string",
            "nullable": true
          },
          "place_id": {
            "type": "string",
            "nullable": true
          },
          "place_slug": {
            "type": "string",
            "nullable": true
          },
          "photo_url": {
            "type": "string",
            "nullable": true
          },
          "avatar_url": {
            "type": "string",
            "nullable": true
          },
          "visibility": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ]
          },
          "listed": {
            "type": "boolean"
          },
          "membership": {
            "type": "string",
            "enum": [
              "free",
              "paid"
            ]
          },
          "price_cents": {
            "type": "integer",
            "nullable": true
          },
          "yearly_price_cents": {
            "type": "integer",
            "nullable": true
          },
          "currency": {
            "type": "string"
          },
          "join_approval": {
            "type": "string",
            "enum": [
              "none",
              "leaders"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "draft",
              "suspended",
              "hidden"
            ]
          },
          "featured": {
            "type": "boolean"
          },
          "member_count": {
            "type": "integer"
          },
          "fundly_count": {
            "type": "integer"
          },
          "impact_cents": {
            "type": "integer",
            "description": "Community impact: money into the fund, plus raised for Fundlies shared here, plus given and driven by members to other Fundlies, each settled gift once. The one figure for a community's money: the page header, the About tab, the directory and the leaderboard all show this number (#2090)."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "offers_help": {
            "type": "boolean",
            "description": "It has help in Find help (#2423): help anyone can find, read through its Resources provider. The \"Offers help\" tag. Always false while Resources are switched off."
          },
          "viewer": {
            "type": "object",
            "properties": {
              "role": {
                "type": "string",
                "enum": [
                  "owner",
                  "leader",
                  "volunteer",
                  "member"
                ],
                "nullable": true
              },
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "requested",
                  "invited"
                ],
                "nullable": true
              },
              "join_action": {
                "type": "string",
                "enum": [
                  "joined",
                  "join",
                  "request",
                  "pay",
                  "requested",
                  "accept_invite",
                  "none"
                ]
              }
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "CommunityLink": {
        "type": "object",
        "description": "A community link (#2094): normalized https, the platform detected from its hostname, in the owner's order.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string",
            "description": "Normalized: https only, host lowercased without www., no utm_*/fbclid/gclid, no trailing slash."
          },
          "host": {
            "type": "string"
          },
          "platform": {
            "type": "string",
            "enum": [
              "instagram",
              "telegram",
              "whatsapp",
              "facebook",
              "youtube",
              "tiktok",
              "x",
              "threads",
              "linkedin",
              "medium",
              "discord",
              "github",
              "twitch",
              "pinterest",
              "snapchat",
              "reddit",
              "spotify",
              "web"
            ]
          },
          "kind": {
            "type": "string",
            "nullable": true,
            "enum": [
              "group",
              "channel",
              "chat",
              null
            ],
            "description": "A WhatsApp, Telegram or Facebook group, a WhatsApp channel or chat; null otherwise."
          },
          "label": {
            "type": "string",
            "nullable": true,
            "maxLength": 40,
            "description": "The owner's name for it; null shows the platform's name."
          },
          "audience": {
            "type": "string",
            "enum": [
              "everyone",
              "members"
            ],
            "description": "members = shown to active members only (an invite into a group chat)."
          }
        },
        "required": [
          "id",
          "url",
          "host",
          "platform",
          "kind",
          "label",
          "audience"
        ]
      },
      "CommunityEditableLink": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CommunityLink"
          },
          {
            "type": "object",
            "properties": {
              "safety_status": {
                "type": "string",
                "enum": [
                  "unchecked",
                  "ok",
                  "flagged"
                ],
                "description": "Google Web Risk (Safe Browsing). A flagged link is hidden from the page."
              },
              "click_count_30d": {
                "type": "integer"
              }
            }
          }
        ]
      },
      "CommunityLinkInput": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The link's id, to keep it (and its clicks) when its URL or place changes."
          },
          "url": {
            "type": "string",
            "maxLength": 2048,
            "description": "Any link; http is upgraded to https. javascript:, data:, IPs, localhost and fundlyhub.org links are refused."
          },
          "label": {
            "type": "string",
            "nullable": true,
            "maxLength": 40
          },
          "audience": {
            "type": "string",
            "enum": [
              "everyone",
              "members"
            ],
            "description": "Defaults to members for a group invite and for every link in a private community, else everyone."
          }
        },
        "required": [
          "url"
        ]
      },
      "CommunityDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CommunityCard"
          },
          {
            "type": "object",
            "description": "CommunityCard plus settings, stats, team, pinned post, the viewer's standing and permissions.",
            "properties": {
              "about": {
                "type": "string",
                "nullable": true
              },
              "links": {
                "type": "array",
                "maxItems": 8,
                "description": "The community's links in order (#2094). Never flagged or staff-removed ones; members-only links only for active members.",
                "items": {
                  "$ref": "#/components/schemas/CommunityLink"
                }
              },
              "languages": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "guidelines": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "owner_id": {
                "type": "string",
                "nullable": true
              },
              "share_policy": {
                "type": "string",
                "enum": [
                  "auto",
                  "leader_approval"
                ]
              },
              "add_policy": {
                "type": "string",
                "enum": [
                  "leaders",
                  "members"
                ]
              },
              "default_alert": {
                "type": "string",
                "enum": [
                  "instant",
                  "digest"
                ]
              },
              "show_leaders": {
                "type": "boolean"
              },
              "photo_original_url": {
                "type": "string",
                "nullable": true
              },
              "photo_crop": {
                "type": "object",
                "description": "ImageCropState of the 4:5 card",
                "additionalProperties": true
              },
              "avatar_crop": {
                "type": "object",
                "description": "ImageCropState of the 1:1 avatar",
                "additionalProperties": true
              },
              "stats": {
                "type": "object",
                "properties": {
                  "member_count": {
                    "type": "integer"
                  },
                  "fundly_count": {
                    "type": "integer"
                  },
                  "active_count": {
                    "type": "integer"
                  },
                  "funded_count": {
                    "type": "integer"
                  },
                  "ended_count": {
                    "type": "integer"
                  },
                  "impact_cents": {
                    "type": "integer",
                    "description": "The card's `impact_cents`."
                  },
                  "impact": {
                    "type": "object",
                    "description": "Community impact's four parts. Each counted gift is in exactly one, so they add up to `impact_cents`.",
                    "properties": {
                      "fund_cents": {
                        "type": "integer",
                        "description": "Into the community fund (dues and one-time gifts), net."
                      },
                      "raised_cents": {
                        "type": "integer",
                        "description": "Raised for Fundlies shared here, less what this community's fund gave them."
                      },
                      "given_cents": {
                        "type": "integer",
                        "description": "Given by members to other Fundlies."
                      },
                      "driven_cents": {
                        "type": "integer",
                        "description": "Driven through members' links to other Fundlies."
                      },
                      "gifts": {
                        "type": "object",
                        "description": "How many gifts each part counts.",
                        "properties": {
                          "fund": {
                            "type": "integer"
                          },
                          "raised": {
                            "type": "integer"
                          },
                          "given": {
                            "type": "integer"
                          },
                          "driven": {
                            "type": "integer"
                          }
                        }
                      },
                      "fund_to_shared_cents": {
                        "type": "integer",
                        "description": "What the fund gave to Fundlies shared here, counted once, in the fund part."
                      }
                    }
                  },
                  "gift_count": {
                    "type": "integer",
                    "description": "The gifts Community impact counts (the parts' gift counts added)."
                  },
                  "new_members_month": {
                    "type": "integer"
                  },
                  "team_count": {
                    "type": "integer"
                  }
                },
                "additionalProperties": true
              },
              "team": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "user_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "name": {
                      "type": "string"
                    },
                    "avatar_url": {
                      "type": "string",
                      "nullable": true
                    },
                    "handle": {
                      "type": "string",
                      "nullable": true
                    },
                    "href": {
                      "type": "string",
                      "nullable": true
                    },
                    "role": {
                      "type": "string",
                      "enum": [
                        "owner",
                        "leader",
                        "volunteer",
                        "member"
                      ]
                    },
                    "since": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "added_count": {
                      "type": "integer"
                    }
                  },
                  "additionalProperties": true
                },
                "description": "Owner, leaders and volunteers; empty when show_leaders is off and the viewer is not owner or leader."
              },
              "pinned_post": {
                "type": "object",
                "description": "The pinned post, or null when there is none or when the caller may not read the feed (a non-member of a private community). Its author is null when the post is attributed to the community.",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "body": {
                    "type": "string"
                  },
                  "created_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "author": {
                    "$ref": "#/components/schemas/CommunityPerson"
                  }
                },
                "additionalProperties": true
              },
              "leaderboard_url": {
                "type": "string"
              },
              "viewer": {
                "type": "object",
                "properties": {
                  "can": {
                    "type": "object",
                    "description": "The permissions matrix for this viewer.",
                    "properties": {
                      "view_feed": {
                        "type": "boolean"
                      },
                      "view_members": {
                        "type": "boolean"
                      },
                      "edit_settings": {
                        "type": "boolean"
                      },
                      "manage_members": {
                        "type": "boolean"
                      },
                      "manage_leaders": {
                        "type": "boolean"
                      },
                      "approve_joins": {
                        "type": "boolean"
                      },
                      "approve_fundlies": {
                        "type": "boolean"
                      },
                      "add_people": {
                        "type": "boolean"
                      },
                      "invite_link": {
                        "type": "boolean"
                      },
                      "post": {
                        "type": "boolean"
                      },
                      "pin": {
                        "type": "boolean"
                      },
                      "share_fundly": {
                        "type": "boolean"
                      },
                      "transfer": {
                        "type": "boolean"
                      },
                      "delete": {
                        "type": "boolean"
                      },
                      "manage_payouts": {
                        "type": "boolean"
                      }
                    },
                    "additionalProperties": true
                  },
                  "can_manage": {
                    "type": "boolean"
                  },
                  "can_add": {
                    "type": "boolean"
                  },
                  "can_post": {
                    "type": "boolean"
                  },
                  "alert_level": {
                    "type": "string",
                    "nullable": true
                  },
                  "pinned_home": {
                    "type": "boolean"
                  },
                  "is_paid_member": {
                    "type": "boolean"
                  },
                  "renews_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  },
                  "paid_price_cents": {
                    "type": "integer",
                    "nullable": true
                  }
                },
                "additionalProperties": true
              },
              "invite": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  },
                  "uses": {
                    "type": "integer"
                  },
                  "requires_approval": {
                    "type": "boolean"
                  },
                  "expires_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  }
                },
                "additionalProperties": true
              },
              "setup": {
                "type": "object",
                "properties": {
                  "has_photo": {
                    "type": "boolean"
                  },
                  "member_count": {
                    "type": "integer"
                  },
                  "has_welcome_post": {
                    "type": "boolean"
                  },
                  "has_fundly": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true
              }
            },
            "additionalProperties": true
          }
        ]
      },
      "CommunityFundly": {
        "type": "object",
        "description": "The /fundraisers listing row plus compact figures.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "organizer_name": {
            "type": "string",
            "nullable": true
          },
          "raised_cents": {
            "type": "integer"
          },
          "goal_cents": {
            "type": "integer"
          },
          "percent": {
            "type": "integer"
          },
          "remaining_cents": {
            "type": "integer"
          },
          "fundraising": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "CommunityFeedItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "created",
              "post",
              "fundly_posted",
              "milestone_reached",
              "goal_reached",
              "update_posted",
              "members_joined",
              "fund_allocated",
              "fund_withdrawn",
              "fund_dues"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "actor": {
            "$ref": "#/components/schemas/CommunityPerson"
          },
          "actors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CommunityPerson"
            }
          },
          "count": {
            "type": "integer",
            "nullable": true
          },
          "fundraiser": {
            "$ref": "#/components/schemas/CommunityFundly"
          },
          "body": {
            "type": "string",
            "nullable": true
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "amount_cents": {
            "type": "integer",
            "nullable": true
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "percent": {
            "type": "integer",
            "nullable": true
          },
          "alerted_count": {
            "type": "integer",
            "nullable": true,
            "description": "Owner and leaders only."
          },
          "post_id": {
            "type": "string",
            "nullable": true
          },
          "update_id": {
            "type": "string",
            "nullable": true
          },
          "attributed_to_community": {
            "type": "boolean"
          }
        },
        "additionalProperties": true
      },
      "CommunityMember": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "avatar_url": {
            "type": "string",
            "nullable": true
          },
          "handle": {
            "type": "string",
            "nullable": true
          },
          "href": {
            "type": "string",
            "nullable": true
          },
          "hidden": {
            "type": "boolean"
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "leader",
              "volunteer",
              "member"
            ],
            "nullable": true
          },
          "joined_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "fundly_count": {
            "type": "integer"
          },
          "latest_fundly": {
            "type": "object",
            "additionalProperties": true
          },
          "added_count": {
            "type": "integer"
          },
          "joined_via": {
            "type": "string",
            "nullable": true,
            "description": "Owner, leaders and volunteers only."
          },
          "added_by_name": {
            "type": "string",
            "nullable": true,
            "description": "Owner, leaders and volunteers only."
          },
          "impact_cents": {
            "type": "integer",
            "nullable": true,
            "description": "Member impact here, all time, the same figure as the member's row on this community's leaderboard; owner, leaders and volunteers only."
          }
        },
        "additionalProperties": true
      },
      "CommunityPage": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "has_more": {
            "type": "boolean"
          }
        },
        "additionalProperties": true
      },
      "SponsorUsesError": {
        "type": "object",
        "required": [
          "error"
        ],
        "description": "A refusal from a perk, counter or perks-used route. `code` is the reason a screen branches on (`not_eligible`, `perk_unavailable`, `out_of_codes`, `region`, `already_reported`, `too_late`, `already_back`, `answer_report`, `unknown_pairing_code`, `device_removed`, `signed_out`, `not_on_team`, `cannot_reply`, `rate_limited` with `retryAfterSeconds`, ...); `details` carries what the screen shows with it.",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      },
      "PerkUseAvailability": {
        "type": "object",
        "description": "Whether anyone can use the perk right now, apart from its own terms (`perk.state` says live, scheduled, paused or ended): `available`; `sponsor_paused` (the owner paused every perk, until `until`); `sponsor_unavailable` (the sponsor is suspended, closed or not live yet); `key_paused` (FundlyHub paused the achievement it is for, with the `reason` givers see); `cap_reached` (all `cap` of this month's uses are gone, back at `resetsAt`); `out_of_codes` (an online perk's code list ran out). The same shape the sponsor's page and My perks show.",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "available",
              "sponsor_paused",
              "sponsor_unavailable",
              "key_paused",
              "cap_reached",
              "out_of_codes"
            ]
          },
          "until": {
            "type": "string",
            "format": "date-time"
          },
          "reason": {
            "type": "string"
          },
          "cap": {
            "type": "integer"
          },
          "resetsAt": {
            "type": "string",
            "format": "date-time",
            "description": "The 1st of next month, at midnight in the sponsor's city."
          }
        }
      },
      "PerkUseEligibility": {
        "type": "object",
        "description": "Whether this person may use the perk now: `ready`, `unlocks_on` (the 7-day hold after reaching the tier, with `at`), `needs_tier` (with `heldTier`), `used` (this period), `perks_off` (\"Show sponsor perks\" is off), `team_member` (the business's own team), `account`, or `region` (not available in a sanctioned region).",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ready",
              "unlocks_on",
              "needs_tier",
              "used",
              "perks_off",
              "team_member",
              "account",
              "region"
            ]
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "heldTier": {
            "type": "string",
            "nullable": true,
            "enum": [
              "base",
              "bronze",
              "silver",
              "gold",
              null
            ]
          }
        }
      },
      "PerkUseLocationNow": {
        "type": "object",
        "description": "Whether the location is open now, in its own time zone, by the rule the sponsor's page reads: `open` (with `closesAt`), `closed` (with when it `opens` next), `temporarily_closed` (with `until` and `reason`) or `no_hours`.",
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "open",
              "closed",
              "temporarily_closed",
              "no_hours"
            ]
          },
          "closesAt": {
            "type": "string",
            "description": "Local \"HH:MM\"."
          },
          "opens": {
            "type": "object",
            "nullable": true,
            "properties": {
              "weekday": {
                "type": "integer",
                "description": "ISO weekday, 1 = Monday."
              },
              "time": {
                "type": "string"
              }
            }
          },
          "until": {
            "type": "string",
            "format": "date"
          },
          "reason": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "PerkUseClosure": {
        "type": "object",
        "nullable": true,
        "description": "A closure covering today or starting within 30 days (\"Closed Nov 3 - 9 for a remodel\").",
        "properties": {
          "startsOn": {
            "type": "string",
            "format": "date"
          },
          "endsOn": {
            "type": "string",
            "format": "date"
          },
          "reason": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "PerkUseScreen": {
        "type": "object",
        "description": "Everything the \"Use perk\" screen shows for the signed-in person and one perk. `perk` is the perk as every surface describes it (its terms in force, state, where and when, hours and any change ahead); `achievements` names the achievement it is for, by id, in the reader's language; days, hours and dates are local to `timeZone`, the sponsor's home city. With `near`, the storefronts come nearest first, each with its distance.",
        "properties": {
          "perk": {
            "type": "object",
            "additionalProperties": true
          },
          "sponsor": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "logoUrl": {
                "type": "string",
                "nullable": true
              },
              "status": {
                "type": "string"
              }
            }
          },
          "achievements": {
            "type": "object",
            "description": "The perk's achievement, keyed by its id, including its current canonical artwork.",
            "additionalProperties": {
              "$ref": "#/components/schemas/PerkAchievementRef"
            }
          },
          "timeZone": {
            "type": "string",
            "example": "America/Los_Angeles"
          },
          "availability": {
            "$ref": "#/components/schemas/PerkUseAvailability"
          },
          "eligibility": {
            "$ref": "#/components/schemas/PerkUseEligibility"
          },
          "locations": {
            "type": "array",
            "description": "The locations it works at (in store only). A home-based business's address is never shown.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "label": {
                  "type": "string"
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "premises",
                    "service_area"
                  ]
                },
                "address": {
                  "type": "object",
                  "nullable": true,
                  "properties": {
                    "line1": {
                      "type": "string"
                    },
                    "line2": {
                      "type": "string"
                    },
                    "city": {
                      "type": "string"
                    },
                    "region": {
                      "type": "string"
                    },
                    "postal_code": {
                      "type": "string"
                    },
                    "country": {
                      "type": "string"
                    }
                  }
                },
                "point": {
                  "type": "object",
                  "nullable": true,
                  "description": "A storefront's map point.",
                  "properties": {
                    "lat": {
                      "type": "number"
                    },
                    "lng": {
                      "type": "number"
                    }
                  }
                },
                "city": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "slug": {
                      "type": "string",
                      "nullable": true
                    },
                    "label": {
                      "type": "string"
                    }
                  }
                },
                "timeZone": {
                  "type": "string"
                },
                "now": {
                  "$ref": "#/components/schemas/PerkUseLocationNow"
                },
                "closure": {
                  "$ref": "#/components/schemas/PerkUseClosure"
                },
                "distanceMiles": {
                  "type": "number",
                  "nullable": true,
                  "description": "From `near`, storefronts only."
                }
              }
            }
          },
          "lastUse": {
            "type": "object",
            "nullable": true,
            "description": "The person's use of it in the current period.",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "at": {
                "type": "string",
                "format": "date-time"
              },
              "locationLabel": {
                "type": "string",
                "nullable": true
              },
              "online": {
                "type": "boolean"
              }
            }
          },
          "nextOn": {
            "type": "string",
            "nullable": true,
            "description": "The local date it can be used again after a use this period; null for once ever."
          },
          "online": {
            "type": "object",
            "nullable": true,
            "description": "An online perk's state.",
            "properties": {
              "codesLeft": {
                "type": "boolean"
              },
              "website": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "viewer": {
            "type": "object",
            "description": "The person's own first name and initial, photo, and the tier they hold, for the card the cashier matches.",
            "properties": {
              "displayName": {
                "type": "string",
                "nullable": true
              },
              "avatarUrl": {
                "type": "string",
                "nullable": true
              },
              "heldTier": {
                "type": "string",
                "nullable": true,
                "enum": [
                  "base",
                  "bronze",
                  "silver",
                  "gold",
                  null
                ]
              }
            }
          }
        }
      },
      "PerkUseCodeKey": {
        "type": "object",
        "description": "The key behind the live code, for this person's phone only. The phone makes the codes itself, offline too: RFC 6238 TOTP, HMAC-SHA1 over the 30-second step counted from the Unix epoch, 6 digits. The QR carries `FHP1:<keyId>:<step>:<code>`. Each code works once, for 2 minutes. A person keeps up to three live keys per perk (one per phone): a fourth screen replaces the oldest. The first code given counts; the other phones' codes then answer `used`.",
        "properties": {
          "keyId": {
            "type": "string",
            "format": "uuid"
          },
          "secret": {
            "type": "string",
            "description": "The 20-byte key, base64url."
          },
          "issuedAt": {
            "type": "string",
            "format": "date-time"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "24 hours after it was issued."
          },
          "stepSeconds": {
            "type": "integer",
            "example": 30
          },
          "digits": {
            "type": "integer",
            "example": 6
          },
          "screen": {
            "$ref": "#/components/schemas/PerkUseScreen"
          }
        }
      },
      "PerkUseCodeStatus": {
        "type": "object",
        "properties": {
          "use": {
            "type": "object",
            "nullable": true,
            "description": "The use given with this key, once the cashier gives it (the screen turns green).",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "at": {
                "type": "string",
                "format": "date-time"
              },
              "locationLabel": {
                "type": "string",
                "nullable": true
              },
              "undone": {
                "type": "boolean"
              },
              "undoUntil": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      },
      "PerkUseOnlineCode": {
        "type": "object",
        "properties": {
          "useId": {
            "type": "string",
            "format": "uuid"
          },
          "code": {
            "type": "string",
            "description": "The shop's one-time code."
          },
          "usedAt": {
            "type": "string",
            "format": "date-time"
          },
          "useBy": {
            "type": "string",
            "format": "date-time",
            "description": "7 days after it was handed out."
          },
          "website": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "PerkUseReceipt": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "sponsor": {
            "type": "object",
            "additionalProperties": true
          },
          "perk": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "title": {
                "type": "string"
              },
              "frequency": {
                "type": "string",
                "enum": [
                  "day",
                  "week",
                  "month",
                  "year",
                  "once"
                ]
              },
              "achievementTitle": {
                "type": "string"
              }
            }
          },
          "tier": {
            "type": "string",
            "enum": [
              "base",
              "bronze",
              "silver",
              "gold"
            ]
          },
          "locationLabel": {
            "type": "string",
            "nullable": true
          },
          "online": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "counted",
              "undone",
              "voided"
            ]
          },
          "voidReason": {
            "type": "string",
            "nullable": true,
            "enum": [
              "report",
              "sponsor",
              "staff",
              null
            ]
          },
          "onlineCode": {
            "type": "object",
            "nullable": true,
            "description": "An online use's code, while it can still be used.",
            "properties": {
              "code": {
                "type": "string"
              },
              "useBy": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "report": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "kind": {
                "type": "string",
                "enum": [
                  "not_given",
                  "gave_less",
                  "code_failed",
                  "other"
                ]
              },
              "note": {
                "type": "string",
                "nullable": true
              },
              "status": {
                "type": "string",
                "enum": [
                  "open",
                  "confirmed",
                  "disputed",
                  "no_answer",
                  "upheld",
                  "not_upheld"
                ]
              },
              "createdAt": {
                "type": "string",
                "format": "date-time"
              },
              "answerBy": {
                "type": "string",
                "format": "date-time",
                "description": "The business has 3 days to answer."
              },
              "answer": {
                "type": "string",
                "nullable": true,
                "description": "The business's note to the giver when it confirmed. What it tells FundlyHub in a dispute is not shown here."
              },
              "answeredAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "decidedAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "decideBy": {
                "type": "string",
                "format": "date-time",
                "description": "If the business disagrees, FundlyHub decides within 5 business days of its answer (or of `answerBy`)."
              },
              "reply": {
                "type": "object",
                "nullable": true,
                "description": "The person's one reply to the outcome (\"Not what happened?\").",
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "at": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              },
              "canReply": {
                "type": "boolean",
                "description": "Answered or decided, no reply yet, within 30 days of the outcome."
              }
            }
          },
          "canReport": {
            "type": "boolean",
            "description": "A counted use, not reported yet, within 30 days."
          },
          "nextOn": {
            "type": "string",
            "nullable": true,
            "description": "The local date (the sponsor's home city) it can be used again, while that day is still ahead; null once it has come, or for a once-ever perk."
          }
        }
      },
      "CounterPlace": {
        "type": "object",
        "properties": {
          "device": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "sponsor": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "logoUrl": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "location": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "label": {
                "type": "string"
              },
              "city": {
                "type": "string",
                "nullable": true,
                "description": "The city it is in (\"West Sacramento\")."
              }
            }
          }
        }
      },
      "CounterSession": {
        "type": "object",
        "description": "A paired device (`mode: device`, its sponsor and location with its time zone), or a signed-in team member (`mode: member`) and the places they may pick, with each location's state now and a closure ahead.",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "device",
              "member"
            ]
          },
          "device": {
            "type": "object",
            "additionalProperties": true
          },
          "sponsor": {
            "type": "object",
            "additionalProperties": true
          },
          "location": {
            "type": "object",
            "additionalProperties": true
          },
          "places": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "sponsor": {
                  "type": "object",
                  "additionalProperties": true
                },
                "memberId": {
                  "type": "string",
                  "format": "uuid"
                },
                "role": {
                  "type": "string",
                  "enum": [
                    "owner",
                    "admin",
                    "manager",
                    "cashier"
                  ]
                },
                "locations": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "label": {
                        "type": "string"
                      },
                      "kind": {
                        "type": "string"
                      },
                      "address": {
                        "type": "object",
                        "nullable": true,
                        "description": "A storefront's street, so locations can be told apart; null for a service area.",
                        "properties": {
                          "line1": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      },
                      "timeZone": {
                        "type": "string"
                      },
                      "now": {
                        "$ref": "#/components/schemas/PerkUseLocationNow"
                      },
                      "closure": {
                        "$ref": "#/components/schemas/PerkUseClosure"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "CounterPerk": {
        "type": "object",
        "description": "What the counter shows about the perk: its public terms (the same `perk` every surface shows) and its achievement's title. Never the person.",
        "properties": {
          "perk": {
            "type": "object",
            "additionalProperties": true
          },
          "achievementTitle": {
            "type": "string"
          },
          "achievementArt": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/AchievementArt"
              }
            ],
            "description": "Optional current artwork for the public achievement named above; no giver information."
          }
        }
      },
      "CounterAnswer": {
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/CounterPerk"
          }
        ],
        "description": "What the counter says about a code. `valid` (with `keyId` and `step` to give it, and the tier the person holds); `expired` (older than 2 minutes, replaced, or used); `unknown` (with `triesLeft`); `ambiguous` (two codes match the digits: scan instead); `other_sponsor`; `wait` (five wrong codes in a row, with `retryAfterSeconds`); `no_perks` (the business is paused or not live); and, with the perk: `perk_not_live`, `perk_paused` (`reason`, `until`), `perk_key_paused`, `not_here` (`where` it works), `outside_hours`, `tier` (`heldTier`), `not_yet` (`unlocksAt`, the 7-day hold), `used` (`usedAt`, `usedAtLabel`, `nextOn`; `justNow` when this very code was given already), `cap_reached` (`backOn`), `not_eligible` (the person can't use perks here: the counter never learns why).",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "valid",
              "expired",
              "unknown",
              "ambiguous",
              "other_sponsor",
              "wait",
              "no_perks",
              "perk_not_live",
              "perk_paused",
              "perk_key_paused",
              "not_here",
              "outside_hours",
              "tier",
              "not_yet",
              "used",
              "cap_reached",
              "not_eligible"
            ]
          },
          "justNow": {
            "type": "boolean"
          },
          "heldTier": {
            "type": "string",
            "nullable": true
          },
          "keyId": {
            "type": "string",
            "format": "uuid"
          },
          "step": {
            "type": "integer"
          },
          "triesLeft": {
            "type": "integer"
          },
          "retryAfterSeconds": {
            "type": "integer"
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "until": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "where": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "unlocksAt": {
            "type": "string",
            "format": "date-time"
          },
          "usedAt": {
            "type": "string",
            "format": "date-time"
          },
          "usedAtLabel": {
            "type": "string",
            "nullable": true
          },
          "nextOn": {
            "type": "string",
            "nullable": true
          },
          "backOn": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "CounterGiven": {
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/CounterPerk"
          }
        ],
        "properties": {
          "useId": {
            "type": "string",
            "format": "uuid"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "undoUntil": {
            "type": "string",
            "format": "date-time",
            "description": "15 minutes after it was given."
          },
          "again": {
            "type": "boolean",
            "description": "Give was tapped again for a code already given here: the same use."
          }
        }
      },
      "CounterToday": {
        "type": "object",
        "description": "Today's uses at this location (its local day), newest first, at most 200.",
        "properties": {
          "count": {
            "type": "integer",
            "description": "Perks given today that still count",
            "the whole day.": null
          },
          "timeZone": {
            "type": "string",
            "description": "The location's time zone; the counter shows times in it."
          },
          "uses": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "at": {
                  "type": "string",
                  "format": "date-time"
                },
                "perkTitle": {
                  "type": "string"
                },
                "tier": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "given",
                    "undone",
                    "voided"
                  ]
                },
                "checkedBy": {
                  "type": "string",
                  "nullable": true,
                  "description": "The device or team member that checked it."
                },
                "undoUntil": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true
                }
              }
            }
          }
        }
      },
      "SponsorPeopleCount": {
        "type": "object",
        "description": "A count of people, or `fewerThan` the floor when there are fewer (10 for a breakdown, 5 for the all-time \"givers thanked\").",
        "properties": {
          "count": {
            "type": "integer",
            "nullable": true
          },
          "fewerThan": {
            "type": "integer",
            "nullable": true
          }
        }
      },
      "SponsorUseRow": {
        "type": "object",
        "description": "One perk used. Times, places, perks and tiers; never who.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "day": {
            "type": "string",
            "description": "The local date (YYYY-MM-DD) in the sponsor's home city, for grouping."
          },
          "perk": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "title": {
                "type": "string"
              }
            }
          },
          "location": {
            "type": "object",
            "nullable": true,
            "description": "Null for an online use.",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "label": {
                "type": "string"
              }
            }
          },
          "tier": {
            "type": "string",
            "enum": [
              "base",
              "bronze",
              "silver",
              "gold"
            ]
          },
          "checkedBy": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "device",
                  "member",
                  "online"
                ]
              },
              "name": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "given",
              "undone",
              "voided"
            ]
          },
          "voidReason": {
            "type": "string",
            "nullable": true,
            "enum": [
              "report",
              "sponsor",
              "staff",
              null
            ]
          },
          "voidNote": {
            "type": "string",
            "nullable": true,
            "description": "Why the team gave it back, as they wrote it (`voidReason: sponsor`)."
          },
          "report": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "status": {
                "type": "string"
              }
            }
          }
        }
      },
      "SponsorUsesPage": {
        "type": "object",
        "properties": {
          "summary": {
            "type": "object",
            "description": "Uses that count and the people who used them, today, this week, this month and all time. All time's givers are the headline \"givers thanked\", shown from 5 up: the same number as the sponsor page. Today's, the week's and the month's are breakdowns, shown from 10. A cashier gets `today` alone.",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "uses": {
                  "type": "integer"
                },
                "givers": {
                  "$ref": "#/components/schemas/SponsorPeopleCount"
                }
              }
            }
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SponsorUseRow"
            }
          },
          "next": {
            "type": "string",
            "nullable": true,
            "description": "The cursor for the next page (pass it as `before`)."
          },
          "days": {
            "type": "array",
            "description": "Every day of the range, newest first, with what counted and what was given back (the day rows' counts and \"Show all\").",
            "items": {
              "type": "object",
              "properties": {
                "day": {
                  "type": "string",
                  "format": "date"
                },
                "used": {
                  "type": "integer"
                },
                "back": {
                  "type": "integer"
                }
              }
            }
          },
          "timeZone": {
            "type": "string",
            "nullable": true,
            "description": "The sponsor's home time zone; `day` and the ranges are its local days."
          },
          "filters": {
            "type": "object",
            "properties": {
              "range": {
                "type": "string"
              },
              "perks": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "locations": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "online": {
                "type": "boolean",
                "description": "Whether online uses are in this person's scope."
              }
            }
          }
        }
      },
      "SponsorUseReport": {
        "type": "object",
        "description": "A giver's report about a use. What happened, never who said so.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "not_given",
              "gave_less",
              "code_failed",
              "other"
            ]
          },
          "note": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "confirmed",
              "disputed",
              "no_answer",
              "upheld",
              "not_upheld"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "answerBy": {
            "type": "string",
            "format": "date-time"
          },
          "answer": {
            "type": "string",
            "nullable": true
          },
          "answeredAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "decidedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "decisionNote": {
            "type": "string",
            "nullable": true
          },
          "reply": {
            "type": "object",
            "nullable": true,
            "description": "The giver's reply to the outcome, never who wrote it.",
            "properties": {
              "text": {
                "type": "string"
              },
              "at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "use": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "at": {
                "type": "string",
                "format": "date-time"
              },
              "perkTitle": {
                "type": "string"
              },
              "locationLabel": {
                "type": "string",
                "nullable": true
              },
              "tier": {
                "type": "string"
              },
              "online": {
                "type": "boolean"
              }
            }
          }
        }
      },
      "SponsorOnlineCodeList": {
        "type": "object",
        "description": "An online perk's code list.",
        "properties": {
          "perkId": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "perk": {
            "type": "object",
            "additionalProperties": true,
            "description": "The perk the list is used by, as every surface shows it."
          },
          "achievementTitle": {
            "type": "string"
          },
          "achievementArt": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/AchievementArt"
              }
            ],
            "description": "Optional current artwork for the public achievement named above; no giver information."
          },
          "lowStockAlert": {
            "type": "boolean",
            "description": "Email the owner and admins when 10% of the list is left. Running out is always told."
          },
          "total": {
            "type": "integer"
          },
          "left": {
            "type": "integer"
          },
          "handedOutThisMonth": {
            "type": "integer",
            "description": "Online codes handed out this month."
          },
          "monthlyCap": {
            "type": "integer",
            "nullable": true
          },
          "capLeft": {
            "type": "integer",
            "nullable": true,
            "description": "Left this month under the cap, counting every use: at the counter and online."
          },
          "batches": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "filename": {
                  "type": "string",
                  "nullable": true
                },
                "uploadedAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "uploadedBy": {
                  "type": "string",
                  "nullable": true
                },
                "total": {
                  "type": "integer"
                },
                "handedOut": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "NonprofitGiftQuote": {
        "type": "object",
        "required": [
          "donation_cents",
          "covered_fee_cents",
          "tip_cents",
          "total_cents",
          "processing_fee_cents",
          "nonprofit_net_cents",
          "receipt_amount_cents"
        ],
        "description": "Server-owned integer-cent quote. New nonprofit and church gifts have no FundlyHub tip; processing coverage is unchanged. Monthly quotes reflect the exact Billing fee percentage.",
        "properties": {
          "donation_cents": {
            "type": "integer",
            "minimum": 1
          },
          "covered_fee_cents": {
            "type": "integer",
            "minimum": 0
          },
          "tip_cents": {
            "type": "integer",
            "minimum": 0,
            "maximum": 0,
            "description": "Always zero for new nonprofit and church gifts."
          },
          "total_cents": {
            "type": "integer",
            "minimum": 1
          },
          "processing_fee_cents": {
            "type": "integer",
            "minimum": 0
          },
          "nonprofit_net_cents": {
            "type": "integer",
            "minimum": 0
          },
          "receipt_amount_cents": {
            "type": "integer",
            "minimum": 1
          },
          "application_fee_cents": {
            "type": "integer",
            "minimum": 0
          },
          "application_fee_percent": {
            "type": "number",
            "description": "Present for monthly quotes."
          }
        }
      },
      "NonprofitGeneralGiftInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "checkout_key",
          "amount_cents",
          "donor_name",
          "donor_email"
        ],
        "properties": {
          "checkout_key": {
            "type": "string",
            "format": "uuid",
            "description": "Reuse for retries of this identical request; a changed request requires a new key."
          },
          "amount_cents": {
            "type": "integer",
            "minimum": 1
          },
          "tip_cents": {
            "type": "integer",
            "minimum": 0,
            "maximum": 0,
            "default": 0,
            "description": "FundlyHub tips are not accepted for nonprofit or church donations."
          },
          "cover_fee": {
            "type": "boolean",
            "default": false
          },
          "frequency": {
            "type": "string",
            "enum": [
              "once",
              "monthly"
            ],
            "default": "once"
          },
          "monthly_consent": {
            "type": "boolean",
            "description": "Must be true for monthly gifts; authorizes the displayed total now and monthly until canceled."
          },
          "donor_name": {
            "type": "string",
            "maxLength": 200,
            "description": "Private receipt contact",
            "also required for anonymous gifts.": null
          },
          "donor_email": {
            "type": "string",
            "format": "email",
            "maxLength": 320
          },
          "donor_locale": {
            "type": "string",
            "maxLength": 20
          },
          "is_anonymous": {
            "type": "boolean",
            "default": false
          },
          "note": {
            "type": "string",
            "maxLength": 280
          }
        }
      },
      "NonprofitError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "The machine reason the UI branches on, e.g. `locked`, `already_member`, `email_mismatch`, `ein_taken`."
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "additionalProperties": true,
                "description": "`kind` (VALIDATION_ERROR, NOT_FOUND, FORBIDDEN, CONFLICT, LOCKED, RATE_LIMITED, UNPROCESSABLE) and, for a field, `field` and `reason`; for a list row, `index`."
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ],
        "description": "Every non-profit refusal (#2098)."
      },
      "NonprofitPlaceRef": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "region": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string"
          },
          "label": {
            "type": "string",
            "example": "Sacramento, CA"
          },
          "photo_url": {
            "type": "string",
            "nullable": true
          },
          "has_page": {
            "type": "boolean",
            "description": "The city page exists: link to /cities/{slug} only when true."
          }
        },
        "required": [
          "id",
          "slug",
          "name",
          "region",
          "country",
          "label",
          "photo_url",
          "has_page"
        ]
      },
      "NonprofitCityBlock": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "region": {
            "type": "string",
            "nullable": true
          },
          "label": {
            "type": "string"
          },
          "photo_url": {
            "type": "string",
            "nullable": true
          },
          "fundlies": {
            "type": "integer",
            "description": "Verified Fundlies started in the city."
          },
          "donors": {
            "type": "integer",
            "nullable": true,
            "description": "Donors who live there; null when none."
          },
          "has_page": {
            "type": "boolean"
          }
        },
        "required": [
          "slug",
          "name",
          "label",
          "fundlies",
          "has_page"
        ],
        "description": "The city block every page shares (fundraiser-city.ts fetchPlaceBlock)."
      },
      "NonprofitLink": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string",
            "example": "https://instagram.com/kalyna"
          },
          "host": {
            "type": "string"
          },
          "platform": {
            "type": "string",
            "example": "instagram"
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "position": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "url",
          "host",
          "platform",
          "label",
          "position"
        ]
      },
      "NonprofitEditableLink": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NonprofitLink"
          },
          {
            "type": "object",
            "properties": {
              "safety_status": {
                "type": "string",
                "enum": [
                  "unchecked",
                  "ok",
                  "flagged"
                ]
              },
              "removed_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "removed_reason": {
                "type": "string",
                "nullable": true
              },
              "clicks_30d": {
                "type": "integer"
              }
            },
            "required": [
              "safety_status",
              "removed_at",
              "removed_reason",
              "clicks_30d"
            ]
          }
        ]
      },
      "NonprofitLinkInput": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Keep this row (and its clicks)."
          },
          "url": {
            "type": "string",
            "example": "instagram.com/kalyna"
          },
          "label": {
            "type": "string",
            "nullable": true,
            "maxLength": 40
          }
        },
        "required": [
          "url"
        ]
      },
      "NonprofitProgram": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string",
            "maxLength": 80
          },
          "description": {
            "type": "string",
            "nullable": true,
            "maxLength": 300
          },
          "icon": {
            "type": "string",
            "nullable": true,
            "pattern": "^[a-z0-9_-]{1,32}$"
          },
          "position": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "title",
          "description",
          "icon",
          "position"
        ]
      },
      "NonprofitIrsRecord": {
        "type": "object",
        "properties": {
          "ein": {
            "type": "string",
            "example": "12-3456789"
          },
          "legal_name": {
            "type": "string"
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "state": {
            "type": "string",
            "nullable": true
          },
          "subsection": {
            "type": "string",
            "nullable": true,
            "example": "03"
          },
          "subsection_label": {
            "type": "string",
            "example": "501(c)(3) public charity"
          },
          "private_foundation": {
            "type": "boolean"
          },
          "deductible": {
            "type": "boolean"
          },
          "deductibility_code": {
            "type": "integer",
            "nullable": true
          },
          "foundation_code": {
            "type": "integer",
            "nullable": true
          },
          "ruling_year": {
            "type": "integer",
            "nullable": true
          },
          "ntee_code": {
            "type": "string",
            "nullable": true
          },
          "pub78_listed": {
            "type": "boolean"
          },
          "pub78_deductibility": {
            "type": "string",
            "nullable": true
          },
          "group_exemption": {
            "type": "boolean"
          },
          "revoked_at": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "ca_registry_status": {
            "type": "string",
            "enum": [
              "unknown",
              "current",
              "not_required",
              "delinquent",
              "suspended",
              "revoked"
            ]
          }
        },
        "required": [
          "ein",
          "legal_name",
          "subsection_label",
          "deductible",
          "pub78_listed",
          "group_exemption",
          "ca_registry_status"
        ]
      },
      "NonprofitCard": {
        "type": "object",
        "properties": {
          "is_church": {
            "type": "boolean",
            "description": "Server-derived church discovery classification. Does not change tax eligibility or permissions."
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "logo": {
            "type": "string",
            "nullable": true
          },
          "banner_image": {
            "type": "string",
            "nullable": true
          },
          "cause": {
            "type": "string",
            "enum": [
              "animals",
              "arts_culture",
              "children_youth",
              "community_development",
              "disaster_relief",
              "education",
              "environment",
              "food_security",
              "health",
              "housing_homelessness",
              "human_rights",
              "immigrant_refugee",
              "mental_health",
              "seniors",
              "veterans",
              "women_girls",
              "religious",
              "other"
            ],
            "nullable": true
          },
          "place": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NonprofitPlaceRef"
              }
            ],
            "nullable": true
          },
          "mission": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "under_review",
              "verified",
              "rejected",
              "suspended",
              "paused"
            ]
          },
          "deductible": {
            "type": "boolean"
          },
          "followers": {
            "type": "integer"
          },
          "active_fundlies": {
            "type": "integer",
            "description": "The Fundlies tab's Active count."
          },
          "impact_cents": {
            "type": "integer",
            "description": "Raised on the org's own Fundlies (counted gifts, after the Stripe fee, never the tip)."
          },
          "offers_help": {
            "type": "boolean",
            "description": "It has help in Find help (#2423): help anyone can find, read through its Resources provider. The \"Offers help\" tag. Always false while Resources are switched off."
          },
          "viewer": {
            "$ref": "#/components/schemas/NonprofitCardViewer"
          }
        },
        "required": [
          "id",
          "slug",
          "display_name",
          "status",
          "deductible",
          "followers",
          "active_fundlies",
          "impact_cents",
          "viewer"
        ]
      },
      "NonprofitCardViewer": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "fundraiser",
              "viewer",
              "member"
            ],
            "nullable": true,
            "description": "The caller's team role in this org, or null."
          },
          "following": {
            "type": "boolean"
          }
        },
        "required": [
          "role",
          "following"
        ],
        "description": "Whoever is calling, on every card (the Follow button): a guest's is `{role: null, following: false}`. NonprofitViewer (the page's) carries the same two fields."
      },
      "NonprofitViewer": {
        "type": "object",
        "properties": {
          "signed_in": {
            "type": "boolean"
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "fundraiser",
              "viewer",
              "member"
            ],
            "nullable": true
          },
          "title": {
            "type": "string",
            "nullable": true,
            "description": "The caller's title in this org when on the team (\"You're on the team · Program Director\")."
          },
          "following": {
            "type": "boolean"
          },
          "join_request": {
            "type": "string",
            "enum": [
              "pending"
            ],
            "nullable": true
          },
          "can": {
            "type": "object",
            "properties": {
              "edit_page": {
                "type": "boolean"
              },
              "manage_team": {
                "type": "boolean"
              },
              "start_fundly": {
                "type": "boolean"
              },
              "approve_fundlies": {
                "type": "boolean"
              },
              "read_finance": {
                "type": "boolean"
              },
              "manage_payouts": {
                "type": "boolean"
              },
              "transfer_ownership": {
                "type": "boolean"
              },
              "see_fund": {
                "type": "boolean"
              }
            }
          }
        },
        "required": [
          "signed_in",
          "role",
          "title",
          "following",
          "join_request",
          "can"
        ]
      },
      "NonprofitDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NonprofitCard"
          },
          {
            "type": "object",
            "properties": {
              "legal_name": {
                "type": "string"
              },
              "ein": {
                "type": "string"
              },
              "website": {
                "type": "string",
                "nullable": true
              },
              "contact_email": {
                "type": "string",
                "nullable": true,
                "description": "Only when public, or to the team and staff."
              },
              "address_public": {
                "type": "object",
                "nullable": true,
                "properties": {
                  "city": {
                    "type": "string",
                    "nullable": true
                  },
                  "region": {
                    "type": "string",
                    "nullable": true
                  }
                },
                "description": "City and region only; the full mailing address is the team's."
              },
              "founded_year": {
                "type": "integer",
                "nullable": true
              },
              "ruling_year": {
                "type": "integer",
                "nullable": true
              },
              "links": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/NonprofitLink"
                }
              },
              "programs": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/NonprofitProgram"
                }
              },
              "tax": {
                "type": "object",
                "properties": {
                  "irs_status_label": {
                    "type": "string"
                  },
                  "deductible": {
                    "type": "boolean"
                  },
                  "ruling_year": {
                    "type": "integer",
                    "nullable": true
                  },
                  "ca_registry_status": {
                    "type": "string",
                    "enum": [
                      "unknown",
                      "current",
                      "not_required",
                      "delinquent",
                      "suspended",
                      "revoked"
                    ]
                  },
                  "last_checked_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  },
                  "irs_record_url": {
                    "type": "string"
                  },
                  "form990_url": {
                    "type": "string"
                  },
                  "determination_letter_doc_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true,
                    "description": "determination_letter.id."
                  },
                  "determination_letter": {
                    "type": "object",
                    "nullable": true,
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "url": {
                        "type": "string",
                        "description": "GET /nonprofits/{slug}/documents/{docId} on the API."
                      },
                      "content_type": {
                        "type": "string",
                        "nullable": true
                      }
                    },
                    "required": [
                      "id",
                      "url"
                    ],
                    "description": "The 501(c)(3) determination letter, when staff approved it and the team shows it on About."
                  },
                  "sources": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "pub78",
                        "eo_bmf"
                      ]
                    },
                    "description": "The IRS lists confirming it today (their latest check passed): the card's \"Source: IRS Pub 78 and EO BMF\"."
                  }
                }
              },
              "counts": {
                "type": "object",
                "properties": {
                  "fundlies": {
                    "type": "integer"
                  },
                  "members_on_page": {
                    "type": "integer"
                  },
                  "members_total": {
                    "type": "integer"
                  },
                  "followers": {
                    "type": "integer"
                  }
                }
              },
              "impact": {
                "type": "object",
                "properties": {
                  "raised_cents": {
                    "type": "integer",
                    "description": "Historical Raised after processing fees from own public Fundlies and completed direct general-fund/monthly gifts; excludes tips and duplicate own-fund grants."
                  },
                  "fundly_raised_cents": {
                    "type": "integer",
                    "description": "Own public counted Fundly gifts, excluding completed grants designating this organization's existing money."
                  },
                  "general_fund_raised_cents": {
                    "type": "integer",
                    "description": "Completed direct general-fund and monthly gifts after processing fees. Does not alter City impact attribution."
                  },
                  "fundlies": {
                    "type": "integer"
                  },
                  "donors": {
                    "type": "integer"
                  }
                }
              },
              "city_page": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/NonprofitCityBlock"
                  }
                ],
                "nullable": true
              },
              "general_fund": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  },
                  "visibility": {
                    "type": "string",
                    "enum": [
                      "public",
                      "team",
                      "private"
                    ]
                  },
                  "monthly_gifts_enabled": {
                    "type": "boolean"
                  }
                }
              },
              "donations_paused": {
                "type": "boolean",
                "description": "The public sees \"Donations paused\" with no reason."
              },
              "viewer": {
                "$ref": "#/components/schemas/NonprofitViewer"
              }
            }
          }
        ]
      },
      "NonprofitAddress": {
        "type": "object",
        "properties": {
          "line1": {
            "type": "string",
            "nullable": true
          },
          "line2": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "region": {
            "type": "string",
            "nullable": true
          },
          "postal_code": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "NonprofitPlaceInput": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "place_id": {
                "type": "string",
                "format": "uuid"
              }
            },
            "required": [
              "place_id"
            ]
          },
          {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "region": {
                "type": "string",
                "nullable": true
              },
              "country": {
                "type": "string",
                "example": "US"
              },
              "lat": {
                "type": "number",
                "nullable": true
              },
              "lng": {
                "type": "number",
                "nullable": true
              }
            },
            "required": [
              "name",
              "country"
            ]
          }
        ],
        "description": "A city by id, or by name (found, or created when a city-level point is given)."
      },
      "NonprofitSettings": {
        "type": "object",
        "properties": {
          "display_name": {
            "type": "string"
          },
          "logo": {
            "type": "string",
            "nullable": true
          },
          "place": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NonprofitPlaceRef"
              }
            ],
            "nullable": true
          },
          "cause": {
            "type": "string",
            "nullable": true
          },
          "mission": {
            "type": "string",
            "nullable": true
          },
          "website": {
            "type": "string",
            "nullable": true
          },
          "contact_email": {
            "type": "string",
            "nullable": true
          },
          "contact_email_public": {
            "type": "boolean"
          },
          "address": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NonprofitAddress"
              }
            ],
            "nullable": true
          },
          "ntee_code": {
            "type": "string",
            "nullable": true
          },
          "receipt": {
            "$ref": "#/components/schemas/NonprofitOnboarding/allOf/1/properties/receipt"
          },
          "general_fund": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "visibility": {
                "type": "string",
                "enum": [
                  "public",
                  "team",
                  "private"
                ]
              },
              "monthly_gifts_enabled": {
                "type": "boolean"
              }
            },
            "required": [
              "enabled",
              "visibility",
              "monthly_gifts_enabled"
            ]
          }
        },
        "required": [
          "display_name",
          "logo",
          "place",
          "cause",
          "mission",
          "website",
          "contact_email",
          "contact_email_public",
          "address",
          "ntee_code",
          "receipt",
          "general_fund"
        ]
      },
      "NonprofitSettingsPatch": {
        "type": "object",
        "properties": {
          "display_name": {
            "type": "string",
            "maxLength": 120
          },
          "logo": {
            "type": "string",
            "nullable": true
          },
          "banner_image": {
            "type": "string",
            "nullable": true
          },
          "place": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NonprofitPlaceInput"
              }
            ],
            "nullable": true
          },
          "cause": {
            "type": "string",
            "enum": [
              "animals",
              "arts_culture",
              "children_youth",
              "community_development",
              "disaster_relief",
              "education",
              "environment",
              "food_security",
              "health",
              "housing_homelessness",
              "human_rights",
              "immigrant_refugee",
              "mental_health",
              "seniors",
              "veterans",
              "women_girls",
              "religious",
              "other"
            ],
            "nullable": true
          },
          "mission": {
            "type": "string",
            "nullable": true,
            "maxLength": 280
          },
          "website": {
            "type": "string",
            "nullable": true
          },
          "contact_email": {
            "type": "string",
            "nullable": true
          },
          "contact_email_public": {
            "type": "boolean"
          },
          "address": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NonprofitAddress"
              }
            ],
            "nullable": true
          },
          "founded_year": {
            "type": "integer",
            "nullable": true
          },
          "receipt_signer_name": {
            "type": "string",
            "nullable": true
          },
          "receipt_signer_title": {
            "type": "string",
            "nullable": true
          },
          "receipt_thank_you": {
            "type": "string",
            "nullable": true,
            "maxLength": 600
          },
          "year_end_summary": {
            "type": "boolean"
          },
          "general_fund_enabled": {
            "type": "boolean"
          },
          "general_fund_visibility": {
            "type": "string",
            "enum": [
              "public",
              "team",
              "private"
            ]
          },
          "monthly_gifts_enabled": {
            "type": "boolean"
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NonprofitLinkInput"
            }
          }
        },
        "description": "Every field optional; unknown keys are ignored. legal_name and ein are refused (422 `locked`)."
      },
      "NonprofitTeamMember": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "avatar_url": {
            "type": "string",
            "nullable": true
          },
          "email": {
            "type": "string",
            "nullable": true,
            "description": "Managers (owner, admin, staff) only."
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "fundraiser",
              "viewer",
              "member"
            ]
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "show_on_page": {
            "type": "boolean"
          },
          "joined_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "is_you": {
            "type": "boolean"
          },
          "profile_slug": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "user_id",
          "name",
          "role",
          "title",
          "show_on_page",
          "is_you"
        ]
      },
      "NonprofitPublicMember": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "avatar_url": {
            "type": "string",
            "nullable": true
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "fundraiser",
              "viewer",
              "member"
            ]
          },
          "profile_slug": {
            "type": "string",
            "nullable": true
          },
          "fundlies": {
            "type": "integer",
            "description": "The org's own counted Fundlies this person started (\"started 2 Fundlies\"); never a personal one."
          }
        },
        "required": [
          "user_id",
          "name",
          "role",
          "fundlies"
        ]
      },
      "NonprofitPersonFace": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "avatar_url": {
            "type": "string",
            "nullable": true
          },
          "profile_slug": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "user_id",
          "name"
        ],
        "description": "A person as a public face: never an email, never a private profile."
      },
      "NonprofitInvite": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "email": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "admin",
              "fundraiser",
              "viewer",
              "member"
            ],
            "description": "Never owner: ownership is transferred. The RBAC spelling (org_admin, ...) is accepted too."
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "invited_by": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "nullable": true
              },
              "name": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "sent_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "send_count": {
            "type": "integer",
            "maximum": 5
          }
        },
        "required": [
          "id",
          "email",
          "role",
          "sent_at",
          "expires_at",
          "send_count"
        ]
      },
      "NonprofitInviteView": {
        "description": "One team invite as the person looking at it sees it: the invite page (GET /nonprofits/invite/{token}) and each row of GET /me/nonprofit-invites.",
        "type": "object",
        "properties": {
          "org": {
            "type": "object",
            "properties": {
              "slug": {
                "type": "string"
              },
              "display_name": {
                "type": "string"
              },
              "logo": {
                "type": "string",
                "nullable": true
              },
              "place": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/NonprofitPlaceRef"
                  }
                ],
                "nullable": true
              },
              "status": {
                "type": "string",
                "enum": [
                  "draft",
                  "under_review",
                  "verified",
                  "rejected",
                  "suspended",
                  "paused"
                ]
              }
            }
          },
          "role": {
            "type": "string",
            "enum": [
              "admin",
              "fundraiser",
              "viewer",
              "member"
            ],
            "description": "Never owner: ownership is transferred. The RBAC spelling (org_admin, ...) is accepted too."
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "invited_by": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "email_hint": {
            "type": "string",
            "example": "i***@kalynafamilyaid.org"
          },
          "email": {
            "type": "string",
            "nullable": true,
            "description": "The invited address, only when it is one of the caller's verified emails (\"Sent to ...\"); else null."
          },
          "sent_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the link in hand was sent (a resend moves it): the team view's NonprofitInvite.sent_at."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "The team view's NonprofitInvite.expires_at."
          },
          "show_on_page": {
            "type": "boolean",
            "description": "Whether accepting lists them on the Members tab unless they choose otherwise (the role's default: on for owner/admin/fundraiser/viewer, off for member)."
          },
          "state": {
            "type": "string",
            "enum": [
              "valid",
              "expired",
              "accepted",
              "revoked",
              "declined"
            ]
          },
          "viewer": {
            "type": "object",
            "properties": {
              "signed_in": {
                "type": "boolean"
              },
              "role": {
                "type": "string",
                "enum": [
                  "owner",
                  "admin",
                  "fundraiser",
                  "viewer",
                  "member"
                ],
                "nullable": true,
                "description": "The caller's current team role in this org, or null."
              },
              "email_matches": {
                "type": "boolean",
                "description": "One of the caller's verified emails is the invited one: accepting will work."
              }
            },
            "required": [
              "signed_in",
              "role",
              "email_matches"
            ]
          }
        },
        "required": [
          "org",
          "role",
          "title",
          "invited_by",
          "email_hint",
          "email",
          "sent_at",
          "expires_at",
          "show_on_page",
          "state",
          "viewer"
        ]
      },
      "NonprofitMyInvite": {
        "description": "An invite waiting for the signed-in person (GET /me/nonprofit-invites): the invite page's view with the id they answer it by in the app. Always state valid, email_matches true and viewer.role null.",
        "allOf": [
          {
            "$ref": "#/components/schemas/NonprofitInviteView"
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              }
            },
            "required": [
              "id"
            ]
          }
        ]
      },
      "NonprofitJoinRequest": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "user": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "avatar_url": {
                "type": "string",
                "nullable": true
              },
              "profile_slug": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "note": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "user",
          "created_at"
        ]
      },
      "NonprofitTeam": {
        "type": "object",
        "properties": {
          "members": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NonprofitTeamMember"
            }
          },
          "invites": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NonprofitInvite"
            },
            "description": "Managers only (else empty)."
          },
          "join_requests": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NonprofitJoinRequest"
            },
            "description": "Managers only (else empty)."
          },
          "roles_help": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "role": {
                  "type": "string",
                  "enum": [
                    "owner",
                    "admin",
                    "fundraiser",
                    "viewer",
                    "member"
                  ]
                },
                "grantable": {
                  "type": "boolean"
                },
                "can": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "required": [
          "members",
          "invites",
          "join_requests",
          "roles_help"
        ]
      },
      "NonprofitCheck": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "pub78",
              "eo_bmf",
              "revocation",
              "ca_registry",
              "stripe",
              "authority"
            ]
          },
          "result": {
            "type": "string",
            "enum": [
              "pass",
              "fail",
              "warn",
              "skipped"
            ]
          },
          "detail": {
            "type": "object",
            "additionalProperties": true
          },
          "checked_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "source",
          "result",
          "detail",
          "checked_at"
        ]
      },
      "NonprofitDocRef": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "doc_type": {
            "type": "string"
          },
          "original_filename": {
            "type": "string",
            "nullable": true
          },
          "content_type": {
            "type": "string",
            "nullable": true
          },
          "verification_status": {
            "type": "string"
          },
          "is_publicly_visible": {
            "type": "boolean"
          },
          "uploaded_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "NonprofitAuthority": {
        "type": "object",
        "properties": {
          "method": {
            "type": "string",
            "enum": [
              "email",
              "form990",
              "letter",
              "volunteer",
              "staff"
            ],
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "verified",
              "rejected"
            ],
            "nullable": true
          },
          "email": {
            "type": "string",
            "description": "Where the authority code went: the owner and staff only (also left out of `detail` for anyone else)."
          },
          "detail": {
            "type": "object",
            "additionalProperties": true,
            "description": "The method's facts; the attestation keeps its text, version and time, never the attesting IP or user agent."
          },
          "domain": {
            "type": "string",
            "nullable": true,
            "description": "Onboarding only: the first domain a work email may be at (the website's registrable domain, else one staff verified); null while the organization has no website, so the work-email code needs one sent with it."
          }
        },
        "required": [
          "method",
          "status",
          "detail"
        ]
      },
      "NonprofitVerification": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "under_review",
              "verified",
              "rejected",
              "suspended",
              "paused"
            ]
          },
          "since": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "last_checked_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "next_check_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "checks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NonprofitCheck"
            },
            "description": "The latest per source."
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NonprofitDocRef"
            }
          },
          "irs": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NonprofitIrsRecord"
              }
            ],
            "description": "The IRS datasets' record first, the copy stored on the org when they hold none (as onboarding and staff read it)."
          },
          "authority": {
            "$ref": "#/components/schemas/NonprofitAuthority"
          }
        },
        "required": [
          "status",
          "checks",
          "documents",
          "irs",
          "authority"
        ]
      },
      "NonprofitExisting": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "logo": {
            "type": "string",
            "nullable": true
          },
          "place": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NonprofitPlaceRef"
              }
            ],
            "nullable": true
          },
          "owner_initials": {
            "type": "string",
            "nullable": true
          },
          "team_size": {
            "type": "integer"
          },
          "viewer": {
            "type": "object",
            "properties": {
              "role": {
                "type": "string",
                "enum": [
                  "owner",
                  "admin",
                  "fundraiser",
                  "viewer",
                  "member"
                ],
                "nullable": true
              },
              "join_request": {
                "type": "string",
                "enum": [
                  "pending"
                ],
                "nullable": true
              }
            },
            "required": [
              "role",
              "join_request"
            ],
            "description": "The person who looked the EIN up: already on its team (their role), or asked to join."
          }
        }
      },
      "NonprofitLookupResult": {
        "type": "object",
        "properties": {
          "outcome": {
            "type": "string",
            "enum": [
              "verified",
              "existing",
              "manual_review",
              "revoked",
              "not_eligible",
              "not_found"
            ]
          },
          "ein": {
            "type": "string"
          },
          "irs": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NonprofitIrsRecord"
              }
            ],
            "nullable": true
          },
          "reason": {
            "type": "string",
            "enum": [
              "church",
              "group",
              "private_foundation"
            ]
          },
          "existing": {
            "$ref": "#/components/schemas/NonprofitExisting"
          }
        },
        "required": [
          "outcome",
          "ein",
          "irs"
        ]
      },
      "NonprofitOnboarding": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NonprofitDetail"
          },
          {
            "type": "object",
            "properties": {
              "step": {
                "type": "integer"
              },
              "review_route": {
                "type": "string",
                "enum": [
                  "auto",
                  "manual"
                ],
                "nullable": true
              },
              "review_reason": {
                "type": "string",
                "nullable": true
              },
              "irs": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/NonprofitIrsRecord"
                  }
                ],
                "nullable": true
              },
              "authority": {
                "$ref": "#/components/schemas/NonprofitAuthority"
              },
              "address": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/NonprofitAddress"
                  }
                ],
                "nullable": true
              },
              "receipt": {
                "type": "object",
                "properties": {
                  "signer_name": {
                    "type": "string",
                    "nullable": true
                  },
                  "signer_title": {
                    "type": "string",
                    "nullable": true
                  },
                  "thank_you": {
                    "type": "string",
                    "nullable": true
                  },
                  "year_end_summary": {
                    "type": "boolean"
                  }
                }
              },
              "stripe": {
                "type": "object",
                "properties": {
                  "flag_on": {
                    "type": "boolean"
                  },
                  "connected": {
                    "type": "boolean"
                  },
                  "charges_enabled": {
                    "type": "boolean"
                  },
                  "payouts_enabled": {
                    "type": "boolean"
                  },
                  "details_submitted": {
                    "type": "boolean"
                  },
                  "requirements_due": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              },
              "documents": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/NonprofitDocRef"
                }
              },
              "checks": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/NonprofitCheck"
                }
              },
              "attestation_text": {
                "type": "string",
                "description": "Step 2's attestation sentence for this organization's legal name (English legal copy in every locale), exactly the text stored with the acceptance."
              },
              "attestation_version": {
                "type": "string",
                "description": "The version stored with an acceptance now. An acceptance counts only with this version and the current `attestation_text`; any other (one from before the sentence was shown, or of a renamed organization) is missing at submit and has to be confirmed again."
              }
            }
          }
        ]
      },
      "NonprofitActivityItem": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "update",
              "fundly_launched",
              "fundly_progress",
              "fundly_goal"
            ]
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "id": {
            "type": "string",
            "description": "update"
          },
          "title": {
            "type": "string",
            "description": "update"
          },
          "body": {
            "type": "string",
            "description": "update"
          },
          "cover_image": {
            "type": "string",
            "nullable": true,
            "description": "update"
          },
          "author": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "nullable": true
              }
            },
            "description": "update"
          },
          "fundly": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "slug": {
                "type": "string"
              },
              "title": {
                "type": "string"
              }
            },
            "description": "fundly_*"
          },
          "by": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "nullable": true
              }
            },
            "description": "fundly_launched"
          },
          "pct": {
            "type": "integer",
            "enum": [
              25,
              50,
              75
            ],
            "description": "fundly_progress"
          },
          "remaining_cents": {
            "type": "integer",
            "description": "fundly_progress"
          },
          "goal_cents": {
            "type": "integer",
            "description": "fundly_goal"
          },
          "donors": {
            "type": "integer",
            "description": "fundly_goal"
          }
        },
        "required": [
          "kind",
          "at"
        ]
      },
      "SponsorManageError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "The machine reason the UI branches on, e.g. `incomplete`, `code_required`, `too_many_perks`, or the name of the database rule that refused it."
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "additionalProperties": true,
                "description": "`kind` (VALIDATION_ERROR, NOT_FOUND, FORBIDDEN, CONFLICT, RATE_LIMITED, UNPROCESSABLE) and, for a field, `field`; `missing` for an incomplete application, `attempts_left` for a wrong code."
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ],
        "description": "Every refusal of the business side of sponsors (#2319)."
      },
      "SponsorJoinOptions": {
        "type": "object",
        "properties": {
          "categories": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "policy": {
                  "type": "string",
                  "enum": [
                    "allowed",
                    "limited",
                    "not_allowed"
                  ]
                },
                "display_order": {
                  "type": "integer"
                }
              }
            }
          },
          "terms_version": {
            "type": "string"
          },
          "max_drafts": {
            "type": "integer"
          }
        },
        "description": "What the Become a sponsor forms need."
      },
      "SponsorManageLocation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "kind": {
            "type": "string",
            "enum": [
              "premises",
              "service_area",
              "online"
            ]
          },
          "is_primary": {
            "type": "boolean"
          },
          "closed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "dba_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "apple_place_id": {
            "type": "string",
            "nullable": true
          },
          "address": {
            "type": "object",
            "properties": {
              "line1": {
                "type": "string"
              },
              "line2": {
                "type": "string",
                "nullable": true
              },
              "city": {
                "type": "string"
              },
              "region": {
                "type": "string",
                "description": "The state, as its code or name."
              },
              "postal_code": {
                "type": "string",
                "description": "A US ZIP or ZIP+4."
              },
              "country": {
                "type": "string",
                "description": "US only at launch; leave it out."
              }
            },
            "required": [
              "line1",
              "city",
              "region",
              "postal_code"
            ]
          },
          "point": {
            "allOf": [
              {
                "type": "object",
                "properties": {
                  "lat": {
                    "type": "number"
                  },
                  "lng": {
                    "type": "number"
                  }
                },
                "required": [
                  "lat",
                  "lng"
                ],
                "description": "The street-level point of the Apple Maps place. Required for a place customers visit."
              }
            ],
            "nullable": true
          },
          "city": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "region": {
                "type": "string",
                "nullable": true
              },
              "slug": {
                "type": "string",
                "nullable": true
              },
              "timezone": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "hours": {
            "type": "array",
            "maxItems": 21,
            "items": {
              "type": "object",
              "properties": {
                "weekday": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 7,
                  "description": "ISO weekday, 1 = Monday."
                },
                "opens_at": {
                  "type": "string",
                  "example": "06:30"
                },
                "closes_at": {
                  "type": "string",
                  "example": "18:00",
                  "description": "At or before opens_at runs past midnight; equal = open 24 hours."
                }
              },
              "required": [
                "weekday",
                "opens_at",
                "closes_at"
              ]
            }
          },
          "exceptions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "starts_on": {
                  "type": "string"
                },
                "ends_on": {
                  "type": "string"
                },
                "opens_at": {
                  "type": "string",
                  "nullable": true
                },
                "closes_at": {
                  "type": "string",
                  "nullable": true
                },
                "reason": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "zips": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "place_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "code": {
                  "type": "string"
                }
              }
            }
          },
          "confirmed": {
            "type": "object",
            "properties": {
              "at": {
                "type": "string",
                "format": "date-time"
              },
              "method": {
                "type": "string",
                "enum": [
                  "sticker",
                  "staff"
                ]
              }
            },
            "description": "Null until someone on the team scans one of its stickers, or staff confirm it."
          },
          "address_changed_at": {
            "type": "string",
            "format": "date-time"
          },
          "kit_ship_to_location_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Another of the sponsor's locations its sticker kit is mailed to (Become a sponsor's \"Send to a different address\"); null when it is mailed here."
          },
          "pickup_only": {
            "type": "boolean",
            "description": "A storefront where customers only pick up orders; its weekly hours are pickup hours (\"Weekly hours · pickup\")."
          }
        },
        "description": "A location as the forms show it. The address, city and time zone are read from places; a service area's ZIPs are listed instead of a pin."
      },
      "SponsorJoinDraft": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "self",
              "staff"
            ]
          },
          "is_sponsor": {
            "type": "boolean",
            "description": "False for a business that only lists help in Resources (#2422); `missing` never asks it for a perk."
          },
          "onboarding_step": {
            "type": "integer",
            "nullable": true
          },
          "legal": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
          },
          "category_id": {
            "type": "string",
            "nullable": true
          },
          "about": {
            "type": "string",
            "nullable": true
          },
          "logo_url": {
            "type": "string",
            "nullable": true
          },
          "contact_email": {
            "type": "string",
            "nullable": true
          },
          "phone": {
            "type": "string",
            "nullable": true
          },
          "services": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "label": {
                  "type": "string"
                },
                "description": {
                  "type": "string",
                  "nullable": true,
                  "description": "The line under the item (\"A line about it\"), up to 120 characters."
                },
                "position": {
                  "type": "integer"
                }
              }
            }
          },
          "links": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "url": {
                  "type": "string"
                },
                "host": {
                  "type": "string",
                  "nullable": true
                },
                "platform": {
                  "type": "string"
                },
                "label": {
                  "type": "string",
                  "nullable": true
                },
                "position": {
                  "type": "integer"
                },
                "safety_status": {
                  "type": "string"
                }
              }
            }
          },
          "names": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string"
                }
              }
            }
          },
          "locations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SponsorManageLocation"
            }
          },
          "owners": {
            "type": "object",
            "properties": {
              "declared_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "list": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "full_name": {
                      "type": "string"
                    },
                    "is_me": {
                      "type": "boolean"
                    },
                    "has_date_of_birth": {
                      "type": "boolean",
                      "description": "Whether another owner's date of birth is on file. The date itself is never sent back."
                    }
                  }
                }
              }
            }
          },
          "authority": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "none",
                  "pending",
                  "verified",
                  "failed"
                ]
              },
              "method": {
                "type": "string",
                "enum": [
                  "work_email",
                  "document",
                  "staff_evidence"
                ],
                "nullable": true
              },
              "email": {
                "type": "string",
                "nullable": true
              },
              "documents": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": true
                }
              }
            }
          },
          "me": {
            "type": "object",
            "properties": {
              "member_id": {
                "type": "string",
                "nullable": true
              },
              "role": {
                "type": "string",
                "nullable": true
              },
              "title": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "terms": {
            "type": "object",
            "properties": {
              "version": {
                "type": "string"
              },
              "accepted_version": {
                "type": "string",
                "nullable": true
              },
              "accepted_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "statement": {
                "type": "string",
                "description": "The authority statement the person confirms, word for word."
              },
              "statement_confirmed": {
                "type": "boolean",
                "description": "The person confirmed the statement on step 2, in its current wording and for the name it says now (a new legal name asks again)."
              }
            }
          },
          "checks": {
            "type": "object",
            "description": "The automatic checks as they stand (POST /sponsors/{key}/onboarding/checks runs them before submitting; submitting runs them again).",
            "properties": {
              "registry": {
                "type": "object",
                "properties": {
                  "state": {
                    "$ref": "#/components/schemas/SponsorCheckState"
                  },
                  "checked_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  },
                  "entity_type": {
                    "type": "string",
                    "nullable": true,
                    "description": "The kind of entity the state's record says."
                  },
                  "status": {
                    "type": "string",
                    "nullable": true,
                    "description": "The state's own word for its standing (\"Active\")."
                  },
                  "matched_name": {
                    "type": "string",
                    "nullable": true
                  }
                }
              },
              "sanctions": {
                "type": "object",
                "properties": {
                  "state": {
                    "$ref": "#/components/schemas/SponsorCheckState"
                  }
                }
              },
              "recheck_due": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "A year after the last registry pass."
              }
            }
          },
          "first_perk": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "The shared perk view (lib/sponsors/perk-view.ts)."
          },
          "perks": {
            "type": "integer"
          },
          "achievements": {
            "type": "object",
            "description": "The achievements the perks are for, by id, titled in the reader's language (`?lang=`, the language cookie, Accept-Language), with optional current canonical artwork.",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "art": {
                  "nullable": true,
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/AchievementArt"
                    }
                  ]
                }
              }
            }
          },
          "review": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "The latest application decision: outcome, reason_code, note, decided_at, and reviewer ({first_name, initials}, the staff member who decided, or null)."
          },
          "missing": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "category",
                "category_not_allowed",
                "location",
                "authority",
                "perk",
                "owners",
                "statement"
              ]
            }
          }
        },
        "description": "A sponsor being added, as the five steps read it. `missing` is what still blocks submitting."
      },
      "SponsorOwnerInput": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "An owner already on file; sent without a date of birth, the one on file stays."
          },
          "full_name": {
            "type": "string"
          },
          "me": {
            "type": "boolean"
          },
          "date_of_birth": {
            "type": "string",
            "format": "date",
            "description": "Another owner's date of birth (YYYY-MM-DD), for sanctions screening. Stored sealed and never sent back."
          }
        },
        "required": [
          "full_name"
        ]
      },
      "SponsorCheckState": {
        "type": "string",
        "enum": [
          "pass",
          "fail",
          "needs_review",
          "pending",
          "not_needed",
          "after_approval"
        ],
        "description": "Where an automatic check stands. needs_review is a person reading it; pending is not run yet."
      },
      "SponsorManagePage": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "legal": {
            "type": "object",
            "properties": {
              "legal_name": {
                "type": "string",
                "nullable": true
              },
              "entity_type": {
                "type": "string",
                "nullable": true
              },
              "registration_state": {
                "type": "string",
                "nullable": true
              },
              "registration_number": {
                "type": "string",
                "nullable": true
              },
              "ein_last4": {
                "type": "string",
                "nullable": true
              },
              "locked": {
                "type": "boolean",
                "description": "True once the state's record was matched: only staff change it then."
              }
            }
          },
          "category_id": {
            "type": "string",
            "nullable": true
          },
          "about": {
            "type": "string",
            "nullable": true
          },
          "logo_url": {
            "type": "string",
            "nullable": true
          },
          "contact_email": {
            "type": "string",
            "nullable": true
          },
          "phone": {
            "type": "string",
            "nullable": true
          },
          "services": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {},
              "additionalProperties": true
            }
          },
          "links": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {},
              "additionalProperties": true
            }
          },
          "names": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {},
              "additionalProperties": true
            }
          }
        }
      },
      "SponsorManagePageInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 80
          },
          "legal_name": {
            "type": "string",
            "nullable": true
          },
          "entity_type": {
            "type": "string",
            "nullable": true
          },
          "registration_state": {
            "type": "string",
            "nullable": true
          },
          "registration_number": {
            "type": "string",
            "nullable": true
          },
          "ein": {
            "type": "string",
            "nullable": true,
            "description": "Nine digits; never shown back."
          },
          "category_id": {
            "type": "string",
            "nullable": true
          },
          "about": {
            "type": "string",
            "maxLength": 280,
            "nullable": true
          },
          "logo_url": {
            "type": "string",
            "nullable": true,
            "description": "An upload into the sponsor-logos bucket through the crop dialog."
          },
          "contact_email": {
            "type": "string",
            "nullable": true
          },
          "phone": {
            "type": "string",
            "nullable": true,
            "description": "A US number; stored as +1XXXXXXXXXX."
          },
          "services": {
            "type": "array",
            "maxItems": 6,
            "description": "What you offer, whole. Each item is its label, or an object with the label and the line about it.",
            "items": {
              "oneOf": [
                {
                  "type": "string",
                  "maxLength": 60
                },
                {
                  "type": "object",
                  "properties": {
                    "label": {
                      "type": "string",
                      "maxLength": 60
                    },
                    "description": {
                      "type": "string",
                      "nullable": true,
                      "maxLength": 120
                    }
                  },
                  "required": [
                    "label"
                  ]
                }
              ]
            }
          },
          "website": {
            "type": "string",
            "nullable": true,
            "description": "The business's own website; a work email proves it at this domain."
          },
          "links": {
            "type": "array",
            "maxItems": 8,
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string"
                },
                "label": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "names": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string"
                }
              }
            },
            "description": "The other names it trades under (DBAs)."
          }
        },
        "description": "Any of the page fields; the ones left out stay as they are. Links are checked with Google Web Risk."
      },
      "SponsorManagePerkTerms": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "maxLength": 60
          },
          "description": {
            "type": "string",
            "maxLength": 140,
            "nullable": true
          },
          "value_kind": {
            "type": "string",
            "enum": [
              "percent_off",
              "amount_off",
              "free_item",
              "bogo",
              "upgrade",
              "other"
            ]
          },
          "percent_off": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "nullable": true
          },
          "max_discount_cents": {
            "type": "integer",
            "nullable": true
          },
          "amount_off_cents": {
            "type": "integer",
            "nullable": true
          },
          "min_purchase_cents": {
            "type": "integer",
            "nullable": true
          },
          "worth_cents": {
            "type": "integer",
            "nullable": true,
            "description": "\"About how much is it worth?\" for a free item, BOGO, upgrade or something else."
          },
          "achievement_id": {
            "type": "string",
            "format": "uuid"
          },
          "achievement_tier_id": {
            "type": "string",
            "format": "uuid",
            "description": "Holders of this tier or higher."
          },
          "in_store": {
            "type": "boolean"
          },
          "all_locations": {
            "type": "boolean",
            "nullable": true
          },
          "location_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "online": {
            "type": "boolean"
          },
          "frequency": {
            "type": "string",
            "enum": [
              "day",
              "week",
              "month",
              "year",
              "once"
            ]
          },
          "monthly_cap": {
            "type": "integer",
            "nullable": true
          },
          "hours": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "weekday": {
                  "type": "integer"
                },
                "starts_at": {
                  "type": "string"
                },
                "ends_at": {
                  "type": "string"
                }
              }
            }
          },
          "starts_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ends_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "fine_print": {
            "type": "string",
            "maxLength": 300,
            "nullable": true
          }
        },
        "required": [
          "title",
          "value_kind",
          "achievement_id",
          "achievement_tier_id",
          "frequency"
        ],
        "description": "A perk's terms, as the builder writes them."
      },
      "SponsorManagePerk": {
        "type": "object",
        "properties": {
          "perk": {
            "type": "object",
            "additionalProperties": true,
            "description": "The shared perk view (lib/sponsors/perk-view.ts): the terms in force, or the newest version before it goes live, and its state."
          },
          "draft": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "The version being edited: id, version_no, status, created_at, terms, and created_by ({name, staff}: a team member's name, or staff: true for FundlyHub)."
          },
          "in_review": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "The version with a reviewer, its review id and flags."
          },
          "scheduled": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "An approved change taking effect later (a smaller perk or an ending, 14 days out)."
          },
          "decision": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "The latest decision on the perk: outcome, reason_code, note, decided_at."
          },
          "uses": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "this_month": {
                "type": "integer"
              }
            }
          },
          "live_since": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the perk first went live; null before it has."
          }
        }
      },
      "SponsorManageTeam": {
        "type": "object",
        "properties": {
          "members": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string",
                  "nullable": true
                },
                "email": {
                  "type": "string",
                  "nullable": true
                },
                "avatar": {
                  "type": "string",
                  "nullable": true
                },
                "role": {
                  "type": "string",
                  "enum": [
                    "owner",
                    "admin",
                    "manager",
                    "cashier"
                  ]
                },
                "title": {
                  "type": "string",
                  "nullable": true
                },
                "show_on_page": {
                  "type": "boolean"
                },
                "location_ids": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "joined_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "last_active_at": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true
                },
                "is_me": {
                  "type": "boolean"
                }
              }
            }
          },
          "invites": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SponsorManageInvite"
            }
          },
          "requests": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string",
                  "nullable": true
                },
                "avatar": {
                  "type": "string",
                  "nullable": true
                },
                "email_hint": {
                  "type": "string",
                  "nullable": true
                },
                "message": {
                  "type": "string",
                  "nullable": true
                },
                "created_at": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "transfer": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "An offer of ownership waiting for the admin it was made to."
          },
          "invite_days": {
            "type": "integer"
          }
        }
      },
      "SponsorManageInvite": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "email": {
            "type": "string",
            "nullable": true
          },
          "role": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "location_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "invited_as": {
            "type": "string",
            "enum": [
              "team",
              "staff"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_sent_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "send_count": {
            "type": "integer"
          },
          "expired": {
            "type": "boolean"
          }
        }
      },
      "SponsorInviteView": {
        "type": "object",
        "properties": {
          "sponsor": {
            "type": "object",
            "properties": {
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "logo_url": {
                "type": "string",
                "nullable": true
              },
              "status": {
                "type": "string"
              },
              "city": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "role": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "locations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "label": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "invited_as": {
            "type": "string"
          },
          "invited_by": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "email_hint": {
            "type": "string",
            "nullable": true
          },
          "email": {
            "type": "string",
            "nullable": true,
            "description": "In full only for the person it was sent to."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "state": {
            "type": "string",
            "enum": [
              "valid",
              "accepted",
              "declined",
              "revoked",
              "expired"
            ]
          },
          "viewer": {
            "type": "object",
            "properties": {
              "signed_in": {
                "type": "boolean"
              },
              "email_matches": {
                "type": "boolean"
              },
              "role": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "takeover": {
            "type": "boolean",
            "description": "An owner invite to a live sponsor, after two staff members approved an owner change: accepting asks for nothing and makes this person the owner at once."
          },
          "owner": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "A first owner invite only (null when takeover is true): the terms version and the statement accepting it asks for."
          }
        }
      },
      "SponsorMyInvites": {
        "type": "object",
        "description": "The business invites waiting for the signed-in person, on their profile.",
        "properties": {
          "invites": {
            "type": "array",
            "description": "Invites to their account or one of their verified emails, newest first. One to a team they are on is left out; an owner invite shows only while its sponsor waits for its owner.",
            "items": {
              "allOf": [
                {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                },
                {
                  "$ref": "#/components/schemas/SponsorInviteView"
                }
              ]
            }
          },
          "unconfirmed": {
            "type": "array",
            "description": "Their sign-in email when it is not confirmed and an invitation waits for it. Only the address, never the business.",
            "items": {
              "type": "object",
              "properties": {
                "email": {
                  "type": "string",
                  "format": "email"
                }
              }
            }
          }
        }
      },
      "SponsorFinishJoining": {
        "type": "object",
        "description": "Whether the owner a super admin seated still has to give the owner's answers, and what the form asks.",
        "properties": {
          "pending": {
            "type": "boolean"
          },
          "name": {
            "type": "string",
            "description": "Only when pending."
          },
          "terms_version": {
            "type": "string",
            "description": "Only when pending."
          },
          "statement": {
            "type": "string",
            "description": "The authority statement, only when pending."
          }
        }
      },
      "SponsorCodeSent": {
        "type": "object",
        "properties": {
          "sent_to": {
            "type": "string",
            "example": "m***@fastcatcoffee.com"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SponsorManageDevice": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "location": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "label": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "paired_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "last_seen_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "code_expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "code_expired": {
            "type": "boolean"
          }
        }
      },
      "SponsorManagePairing": {
        "type": "object",
        "properties": {
          "device": {
            "$ref": "#/components/schemas/SponsorManageDevice"
          },
          "pairing": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Shown once; type it at fundlyhub.org/counter within 10 minutes."
              },
              "expires_at": {
                "type": "string",
                "format": "date-time"
              },
              "url": {
                "type": "string",
                "description": "What the QR opens on the device."
              }
            }
          }
        }
      },
      "SponsorManageStickers": {
        "type": "object",
        "properties": {
          "formats": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {},
              "additionalProperties": true
            }
          },
          "kits_per_30_days": {
            "type": "integer"
          },
          "locations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {},
              "additionalProperties": true
            },
            "description": "Each location's kits, its stickers (format, code, replaced or not) and whether its address is confirmed."
          },
          "badge": {
            "type": "object",
            "properties": {
              "page_url": {
                "type": "string"
              },
              "light": {
                "type": "object",
                "properties": {
                  "image_url": {
                    "type": "string"
                  },
                  "html": {
                    "type": "string"
                  }
                }
              },
              "dark": {
                "type": "object",
                "properties": {
                  "image_url": {
                    "type": "string"
                  },
                  "html": {
                    "type": "string"
                  }
                }
              }
            },
            "description": "The web badge: the code a business pastes into its website."
          }
        }
      },
      "SponsorManagePosts": {
        "type": "object",
        "properties": {
          "posts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "bells": {
                  "type": "integer",
                  "nullable": true,
                  "description": "The followers' bells it reached; null when it took no bell."
                },
                "bell_at": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true,
                  "description": "It waits for the next bell, which goes then."
                }
              },
              "additionalProperties": true
            },
            "description": "Newest first. Each has its kind, body (the first sentence is the headline), photo, who posted it, its locations, notified_at, bells, bell_at and removed."
          },
          "next_bell_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the week's bell is free again; null = now."
          },
          "bell": {
            "type": "object",
            "description": "One update a week reaches followers' bells. Posted inside the week, the first update since the last bell waits for the next one (the hourly sponsor run sends it); others show on the page only.",
            "properties": {
              "last": {
                "type": "object",
                "nullable": true,
                "properties": {
                  "post_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "created_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "When it reached the bells."
                  }
                }
              },
              "next_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "When the next bell is free; null = now."
              },
              "waiting": {
                "type": "object",
                "nullable": true,
                "properties": {
                  "post_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "created_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "When it reaches the bells."
                  }
                }
              }
            }
          },
          "followers": {
            "type": "integer"
          },
          "max_chars": {
            "type": "integer"
          }
        }
      },
      "SponsorManageSettings": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "paused_until": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "pause_message": {
            "type": "string",
            "nullable": true,
            "description": "While paused, the business's words givers see after the date (up to max_pause_message characters); null otherwise."
          },
          "pause_planned": {
            "type": "object",
            "nullable": true,
            "description": "A pause planned ahead (WsSettings \"From\"); the hourly sponsor run starts it on `from`, until `until`.",
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time"
              },
              "until": {
                "type": "string",
                "format": "date-time"
              },
              "message": {
                "type": "string",
                "nullable": true,
                "description": "What givers see after the date (\"back after the holidays\"), up to 80 characters."
              }
            }
          },
          "max_pause_message": {
            "type": "integer",
            "description": "The longest \"What givers see\" line, in characters."
          },
          "team_emails": {
            "type": "object",
            "nullable": true,
            "description": "The viewer's own team-email switches (WsSettings \"Team emails\"); null for staff off the team. Off stops the email; the bell still comes.",
            "properties": {
              "weekly_summary": {
                "type": "boolean"
              },
              "reports": {
                "type": "boolean"
              },
              "low_codes": {
                "type": "boolean"
              }
            }
          },
          "closes_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "contact_email": {
            "type": "string",
            "nullable": true
          },
          "phone": {
            "type": "string",
            "nullable": true
          },
          "legal": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
          },
          "admins": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "followers": {
            "type": "integer"
          },
          "sponsor_since": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When it became a sponsor (\"Was a FundlyHub sponsor from July 2026 to …\")."
          },
          "recent_givers_days": {
            "type": "integer",
            "description": "A leaving reaches the followers and anyone who used a perk in these many days."
          },
          "open_locations": {
            "type": "integer"
          },
          "max_pause_days": {
            "type": "integer"
          },
          "leave_notice_days": {
            "type": "integer"
          }
        }
      },
      "SponsorManageOverview": {
        "type": "object",
        "properties": {
          "sponsor": {
            "type": "object",
            "properties": {
              "is_sponsor": {
                "type": "boolean",
                "description": "False for a business that only lists help in Resources (#2422); its workspace has no perks or stickers."
              }
            },
            "additionalProperties": true
          },
          "viewer": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "nullable": true,
                "description": "The person's own name, for the greeting (\"Good morning, Maya\")."
              },
              "member_id": {
                "type": "string",
                "nullable": true
              },
              "role": {
                "type": "string",
                "nullable": true
              },
              "staff": {
                "type": "object",
                "properties": {
                  "manage": {
                    "type": "boolean"
                  },
                  "review": {
                    "type": "boolean"
                  }
                }
              },
              "acting_as_staff": {
                "type": "boolean"
              },
              "can": {
                "type": "object",
                "additionalProperties": {
                  "type": "string",
                  "enum": [
                    "all",
                    "locations"
                  ],
                  "nullable": true
                },
                "description": "What each action reaches for this person: 'all', 'locations' (their own) or false."
              }
            }
          },
          "numbers": {
            "type": "object",
            "properties": {},
            "description": "perks_used, today, this_week, this_month, givers_thanked, givers_fewer_than, followers, sponsor_since, 30 days of uses (per_day) and today's uses by place (today_by_location: location_id, null for online codes, and uses): a manager sees their locations. givers_thanked is the whole sponsor's total from 5 up, or, for a manager, their locations' count, a breakdown shown from 10 up; under its floor it is null and givers_fewer_than names the floor (5 or 10).",
            "additionalProperties": true
          },
          "perks": {
            "type": "array",
            "description": "Each perk as its card reads it (id, title, state, who, where, frequency, monthly_cap, hours, upcoming, effective_at), its achievement's track (donor, creator, ...) and its counted uses in the person's reach: all time and this month in the home city's calendar.",
            "items": {
              "type": "object",
              "properties": {},
              "additionalProperties": true
            }
          },
          "achievements": {
            "type": "object",
            "description": "The achievements the perks are for, by id, titled in the reader's language (`?lang=`, the language cookie, Accept-Language), with optional current canonical artwork.",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "art": {
                  "nullable": true,
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/AchievementArt"
                    }
                  ]
                }
              }
            }
          },
          "locations": {
            "type": "array",
            "description": "The person's locations, each with whether it is open now in its own time zone and the closure ahead, as the sponsor page reads them.",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/SponsorManageLocation"
                },
                {
                  "type": "object",
                  "properties": {
                    "time_zone": {
                      "type": "string"
                    },
                    "now": {
                      "type": "object",
                      "description": "state: open (closesAt), closed (opens: weekday, time; or null), temporarily_closed (until, reason) or no_hours.",
                      "additionalProperties": true
                    },
                    "closure": {
                      "type": "object",
                      "nullable": true,
                      "description": "The closure covering today, or the next within 30 days.",
                      "properties": {
                        "startsOn": {
                          "type": "string",
                          "format": "date"
                        },
                        "endsOn": {
                          "type": "string",
                          "format": "date"
                        },
                        "reason": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              ]
            }
          },
          "recent_uses": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {},
              "additionalProperties": true
            },
            "description": "Times, places, perks and who checked them; never who used one."
          },
          "attention": {
            "type": "object",
            "description": "join_requests, invites_waiting (each with its role, its locations and when it was first and last sent), ownership_offer, perk_decisions and addresses_to_confirm.",
            "properties": {},
            "additionalProperties": true
          },
          "recheck_due": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "counts": {
            "type": "object",
            "properties": {
              "team": {
                "type": "integer",
                "description": "The team's size, for the workspace nav."
              }
            }
          }
        }
      },
      "CreatorHubTemplateV1": {
        "type": "object",
        "properties": {
          "schemaVersion": {
            "type": "number",
            "enum": [
              1
            ]
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "topic": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "description": {
            "type": "string",
            "maxLength": 500,
            "default": ""
          },
          "campaignReady": {
            "type": "boolean",
            "default": false
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "pattern": "^[a-z][a-zA-Z0-9_]{0,39}$"
                },
                "label": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 80
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "text",
                    "image"
                  ]
                },
                "default": {
                  "type": "string",
                  "maxLength": 2000,
                  "default": ""
                }
              },
              "required": [
                "key",
                "label",
                "type"
              ],
              "additionalProperties": false
            },
            "maxItems": 24
          },
          "carouselSlides": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": {
                "type": "string",
                "maxLength": 2000
              }
            },
            "minItems": 1,
            "maxItems": 20
          },
          "scenes": {
            "type": "object",
            "properties": {
              "post": {
                "type": "object",
                "properties": {
                  "background": {
                    "type": "string",
                    "pattern": "^#[0-9a-f]{6}$"
                  },
                  "nodes": {
                    "type": "array",
                    "items": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "x": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1000
                            },
                            "y": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1778
                            },
                            "width": {
                              "type": "number",
                              "minimum": 1,
                              "maximum": 1000
                            },
                            "height": {
                              "type": "number",
                              "minimum": 1,
                              "maximum": 1778
                            },
                            "visibleWhen": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/fields/items/properties/key"
                            },
                            "hiddenWhen": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/fields/items/properties/key"
                            },
                            "opacity": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1
                            },
                            "rotation": {
                              "type": "number",
                              "minimum": -180,
                              "maximum": 180
                            },
                            "borderColour": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/background"
                            },
                            "borderWidth": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 20
                            },
                            "colourRole": {
                              "type": "string",
                              "enum": [
                                "foreground",
                                "accent",
                                "brand",
                                "fixed"
                              ]
                            },
                            "type": {
                              "type": "string",
                              "enum": [
                                "text"
                              ]
                            },
                            "field": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/fields/items/properties/key"
                            },
                            "text": {
                              "type": "string",
                              "maxLength": 2000
                            },
                            "prefix": {
                              "type": "string",
                              "maxLength": 80
                            },
                            "size": {
                              "type": "number",
                              "minimum": 12,
                              "maximum": 300
                            },
                            "colour": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/background"
                            },
                            "bold": {
                              "type": "boolean"
                            },
                            "weight": {
                              "type": "string",
                              "enum": [
                                "400",
                                "700",
                                "900"
                              ]
                            },
                            "lineHeight": {
                              "type": "number",
                              "minimum": 1,
                              "maximum": 2
                            },
                            "tracking": {
                              "type": "number",
                              "minimum": -10,
                              "maximum": 10
                            },
                            "align": {
                              "type": "string",
                              "enum": [
                                "left",
                                "center",
                                "right"
                              ]
                            }
                          },
                          "required": [
                            "x",
                            "y",
                            "width",
                            "height",
                            "type",
                            "size",
                            "colour"
                          ],
                          "additionalProperties": false
                        },
                        {
                          "type": "object",
                          "properties": {
                            "x": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/x"
                            },
                            "y": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/y"
                            },
                            "width": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/width"
                            },
                            "height": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/height"
                            },
                            "visibleWhen": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/visibleWhen"
                            },
                            "hiddenWhen": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/hiddenWhen"
                            },
                            "opacity": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/opacity"
                            },
                            "rotation": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/rotation"
                            },
                            "borderColour": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/borderColour"
                            },
                            "borderWidth": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/borderWidth"
                            },
                            "colourRole": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/colourRole"
                            },
                            "type": {
                              "type": "string",
                              "enum": [
                                "rect"
                              ]
                            },
                            "colour": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/background"
                            },
                            "radius": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 500
                            }
                          },
                          "required": [
                            "x",
                            "y",
                            "width",
                            "height",
                            "type",
                            "colour"
                          ],
                          "additionalProperties": false
                        },
                        {
                          "type": "object",
                          "properties": {
                            "x": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/x"
                            },
                            "y": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/y"
                            },
                            "width": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/width"
                            },
                            "height": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/height"
                            },
                            "visibleWhen": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/visibleWhen"
                            },
                            "hiddenWhen": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/hiddenWhen"
                            },
                            "opacity": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/opacity"
                            },
                            "rotation": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/rotation"
                            },
                            "borderColour": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/borderColour"
                            },
                            "borderWidth": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/borderWidth"
                            },
                            "colourRole": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/colourRole"
                            },
                            "type": {
                              "type": "string",
                              "enum": [
                                "image"
                              ]
                            },
                            "field": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/fields/items/properties/key"
                            },
                            "radius": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 500
                            },
                            "fit": {
                              "type": "string",
                              "enum": [
                                "cover",
                                "contain"
                              ],
                              "default": "cover"
                            },
                            "positionX": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 100
                            },
                            "positionY": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 100
                            },
                            "zoom": {
                              "type": "number",
                              "minimum": 1,
                              "maximum": 2
                            },
                            "stock": {
                              "type": "string",
                              "enum": [
                                "photo-0",
                                "photo-1",
                                "photo-2",
                                "photo-3",
                                "photo-4",
                                "photo-5"
                              ]
                            }
                          },
                          "required": [
                            "x",
                            "y",
                            "width",
                            "height",
                            "type",
                            "field"
                          ],
                          "additionalProperties": false
                        },
                        {
                          "type": "object",
                          "properties": {
                            "x": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/x"
                            },
                            "y": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/y"
                            },
                            "width": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/width"
                            },
                            "height": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/height"
                            },
                            "visibleWhen": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/visibleWhen"
                            },
                            "hiddenWhen": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/hiddenWhen"
                            },
                            "opacity": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/opacity"
                            },
                            "rotation": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/rotation"
                            },
                            "borderColour": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/borderColour"
                            },
                            "borderWidth": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/borderWidth"
                            },
                            "colourRole": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/colourRole"
                            },
                            "type": {
                              "type": "string",
                              "enum": [
                                "campaignStats"
                              ]
                            },
                            "colour": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/background"
                            },
                            "accent": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/background"
                            },
                            "size": {
                              "type": "number",
                              "minimum": 12,
                              "maximum": 50
                            }
                          },
                          "required": [
                            "x",
                            "y",
                            "width",
                            "height",
                            "type",
                            "colour",
                            "accent",
                            "size"
                          ],
                          "additionalProperties": false
                        },
                        {
                          "type": "object",
                          "properties": {
                            "x": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/x"
                            },
                            "y": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/y"
                            },
                            "width": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/width"
                            },
                            "height": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/height"
                            },
                            "visibleWhen": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/visibleWhen"
                            },
                            "hiddenWhen": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/hiddenWhen"
                            },
                            "opacity": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/opacity"
                            },
                            "rotation": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/rotation"
                            },
                            "borderColour": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/borderColour"
                            },
                            "borderWidth": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/borderWidth"
                            },
                            "colourRole": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/colourRole"
                            },
                            "type": {
                              "type": "string",
                              "enum": [
                                "achievement"
                              ]
                            },
                            "placeholder": {
                              "type": "string",
                              "enum": [
                                "wellness-hippo"
                              ]
                            }
                          },
                          "required": [
                            "x",
                            "y",
                            "width",
                            "height",
                            "type"
                          ],
                          "additionalProperties": false
                        },
                        {
                          "type": "object",
                          "properties": {
                            "x": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/x"
                            },
                            "y": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/y"
                            },
                            "width": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/width"
                            },
                            "height": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/height"
                            },
                            "visibleWhen": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/visibleWhen"
                            },
                            "hiddenWhen": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/hiddenWhen"
                            },
                            "opacity": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/opacity"
                            },
                            "rotation": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/rotation"
                            },
                            "borderColour": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/borderColour"
                            },
                            "borderWidth": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/borderWidth"
                            },
                            "colourRole": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/colourRole"
                            },
                            "type": {
                              "type": "string",
                              "enum": [
                                "brand"
                              ]
                            },
                            "colour": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/background"
                            },
                            "markOnly": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "x",
                            "y",
                            "width",
                            "height",
                            "type",
                            "colour"
                          ],
                          "additionalProperties": false
                        },
                        {
                          "type": "object",
                          "properties": {
                            "x": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/x"
                            },
                            "y": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/y"
                            },
                            "width": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/width"
                            },
                            "height": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/height"
                            },
                            "visibleWhen": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/visibleWhen"
                            },
                            "hiddenWhen": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/hiddenWhen"
                            },
                            "opacity": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/opacity"
                            },
                            "rotation": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/rotation"
                            },
                            "borderColour": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/borderColour"
                            },
                            "borderWidth": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/borderWidth"
                            },
                            "colourRole": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/colourRole"
                            },
                            "type": {
                              "type": "string",
                              "enum": [
                                "campaignValue"
                              ]
                            },
                            "fact": {
                              "type": "string",
                              "enum": [
                                "raised",
                                "goal",
                                "progress",
                                "percentage",
                                "donors",
                                "highestGift",
                                "highestDonor",
                                "endorsements",
                                "beneficiary",
                                "organizer",
                                "city"
                              ]
                            },
                            "colour": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/background"
                            },
                            "size": {
                              "type": "number",
                              "minimum": 12,
                              "maximum": 300
                            },
                            "bold": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "x",
                            "y",
                            "width",
                            "height",
                            "type",
                            "fact",
                            "colour",
                            "size"
                          ],
                          "additionalProperties": false
                        },
                        {
                          "type": "object",
                          "properties": {
                            "x": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/x"
                            },
                            "y": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/y"
                            },
                            "width": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/width"
                            },
                            "height": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/height"
                            },
                            "visibleWhen": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/visibleWhen"
                            },
                            "hiddenWhen": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/hiddenWhen"
                            },
                            "opacity": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/opacity"
                            },
                            "rotation": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/rotation"
                            },
                            "borderColour": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/borderColour"
                            },
                            "borderWidth": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/borderWidth"
                            },
                            "colourRole": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/nodes/items/anyOf/0/properties/colourRole"
                            },
                            "type": {
                              "type": "string",
                              "enum": [
                                "decoration"
                              ]
                            },
                            "motif": {
                              "type": "string",
                              "enum": [
                                "hearts",
                                "heart",
                                "spark",
                                "arrow",
                                "confetti",
                                "map",
                                "orbit"
                              ]
                            },
                            "colour": {
                              "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post/properties/background"
                            }
                          },
                          "required": [
                            "x",
                            "y",
                            "width",
                            "height",
                            "type",
                            "motif",
                            "colour"
                          ],
                          "additionalProperties": false
                        }
                      ]
                    },
                    "minItems": 1,
                    "maxItems": 60
                  }
                },
                "required": [
                  "background",
                  "nodes"
                ],
                "additionalProperties": false
              },
              "carousel": {
                "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post"
              },
              "story": {
                "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post"
              },
              "reel": {
                "$ref": "#/components/schemas/CreatorHubTemplateV1/properties/scenes/properties/post"
              }
            },
            "additionalProperties": false
          }
        },
        "required": [
          "schemaVersion",
          "name",
          "topic",
          "fields",
          "scenes"
        ],
        "additionalProperties": false
      },
      "CreatorHubProjectV1": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "templateId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "templateVersion": {
            "type": "integer",
            "exclusiveMinimum": true,
            "minimum": 0
          },
          "partnerOrganizationId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "default": null
          },
          "achievementSlug": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]{0,99}$",
            "nullable": true,
            "default": null
          },
          "format": {
            "type": "string",
            "enum": [
              "post",
              "carousel",
              "story",
              "reel"
            ]
          },
          "campaignId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "default": null
          },
          "sourceRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "nullable": true,
            "default": null
          },
          "slides": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "inputs": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string",
                    "maxLength": 2000
                  }
                },
                "enabledFacts": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "raised",
                      "goal",
                      "progress",
                      "percentage",
                      "donors",
                      "highestGift",
                      "highestDonor",
                      "endorsements",
                      "beneficiary",
                      "organizer",
                      "city"
                    ]
                  },
                  "maxItems": 11,
                  "default": []
                },
                "style": {
                  "type": "object",
                  "properties": {
                    "palette": {
                      "type": "string",
                      "enum": [
                        "purple",
                        "white",
                        "coral"
                      ]
                    },
                    "imageFit": {
                      "type": "string",
                      "enum": [
                        "cover",
                        "contain"
                      ]
                    },
                    "imageX": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    },
                    "imageY": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    },
                    "imageZoom": {
                      "type": "number",
                      "minimum": 1,
                      "maximum": 2
                    }
                  },
                  "additionalProperties": false
                }
              },
              "required": [
                "inputs"
              ],
              "additionalProperties": false
            },
            "minItems": 1,
            "maxItems": 20
          },
          "caption": {
            "type": "string",
            "maxLength": 2200,
            "default": ""
          }
        },
        "required": [
          "name",
          "templateId",
          "templateVersion",
          "format",
          "slides"
        ],
        "additionalProperties": false
      },
      "FreeStuffError": {
        "type": "object",
        "description": "Every free stuff refusal (#2425). `code` is the reason to branch on, e.g. `not_found`, `no_longer_available`, `validation_error`, `not_allowed` (the checks blocked the post; `details.reasons` says why), `daily_post_limit`, `open_ask_limit`, `already_asked`, `went_to_first`, `not_available`, `asking_paused`, `giving_paused`, `own_item`, `already_chosen`, `promised`, `invalid_state`, `not_in_thread`, `cannot_message`, `message_limit`, `cannot_post_as_provider`, `cannot_report_self`, `unknown_city`.",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "additionalProperties": true
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "FreeItemDistance": {
        "type": "object",
        "nullable": true,
        "description": "A distance band from the viewer's point (the browser's position sent as `near`, else the city browsed, else the person's own place), worked out on the server from a point rounded to about 1 km. Never finer than a mile. `about` 1, 2, 3, 5, 10, 15, 25 or 50 miles, or `over` 50. Null without a point.",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "about",
              "over"
            ]
          },
          "mi": {
            "type": "integer"
          }
        }
      },
      "FreeItemCard": {
        "type": "object",
        "description": "An item in a list. The area (the city of the pickup address) and a distance band; never the address.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string",
            "maxLength": 70
          },
          "category": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string",
                "nullable": true,
                "description": "In the reader's language."
              }
            }
          },
          "condition": {
            "type": "string",
            "enum": [
              "new",
              "like_new",
              "good",
              "fair",
              "for_parts"
            ]
          },
          "photo": {
            "type": "object",
            "nullable": true,
            "properties": {
              "url": {
                "type": "string"
              },
              "width": {
                "type": "integer",
                "nullable": true
              },
              "height": {
                "type": "integer",
                "nullable": true
              }
            }
          },
          "area": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "nullable": true
              },
              "region": {
                "type": "string",
                "nullable": true
              },
              "slug": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "distance": {
            "$ref": "#/components/schemas/FreeItemDistance"
          },
          "pickupMethods": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "porch",
                "public_place",
                "delivery"
              ]
            }
          },
          "availableUntil": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "postedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "held",
              "available",
              "promised",
              "given",
              "expired",
              "removed",
              "taken_down"
            ]
          },
          "selectionMode": {
            "type": "string",
            "enum": [
              "choose",
              "first"
            ]
          },
          "postedAs": {
            "type": "object",
            "nullable": true,
            "description": "Posted as a provider the giver manages; the card shows its name and kind instead of the person.",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "nonprofit",
                  "church",
                  "business",
                  "community",
                  "program"
                ]
              },
              "name": {
                "type": "string",
                "nullable": true
              },
              "slug": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "mine": {
            "type": "boolean",
            "description": "The viewer posted it."
          },
          "saved": {
            "type": "boolean",
            "description": "The viewer saved it."
          }
        }
      },
      "FreeItemPickup": {
        "type": "object",
        "nullable": true,
        "description": "The pickup address and note. Only in the giver's own view and in the view of the person chosen while their ask is chosen; null for everyone else, always.",
        "properties": {
          "address": {
            "type": "object",
            "properties": {
              "line1": {
                "type": "string"
              },
              "unit": {
                "type": "string",
                "nullable": true
              },
              "city": {
                "type": "string",
                "nullable": true
              },
              "region": {
                "type": "string",
                "nullable": true
              },
              "postalCode": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "note": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "FreeItemGiverAsk": {
        "type": "object",
        "description": "An ask as the giver sees it. No ranking by need; asks come in the order they were made.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "asked",
              "chosen",
              "picked_up",
              "not_chosen",
              "no_show"
            ]
          },
          "firstName": {
            "type": "string",
            "nullable": true
          },
          "note": {
            "type": "string",
            "nullable": true,
            "maxLength": 280
          },
          "pickupPref": {
            "type": "string",
            "nullable": true,
            "enum": [
              "porch",
              "public_place",
              "delivery"
            ]
          },
          "askedAt": {
            "type": "string",
            "format": "date-time"
          },
          "gotThisMonth": {
            "type": "integer",
            "description": "Items the person picked up this month (\"Got 2 items this month\")."
          },
          "pickedUp": {
            "type": "integer",
            "description": "\"Picked up 4 of 4\": the 4 picked up."
          },
          "chosenTotal": {
            "type": "integer",
            "description": "\"Picked up 4 of 4\": the times they were chosen and the pickup closed (picked up or no-show)."
          }
        }
      },
      "FreeItemOwnAsk": {
        "type": "object",
        "nullable": true,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "asked",
              "chosen",
              "picked_up",
              "not_chosen",
              "withdrawn",
              "no_show",
              "cancelled"
            ],
            "description": "`chosen` is \"It's yours\"; `not_chosen` \"Went to someone else\"; `cancelled` \"No longer available\"."
          },
          "note": {
            "type": "string",
            "nullable": true
          },
          "pickupPref": {
            "type": "string",
            "nullable": true
          },
          "askedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "chosenAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "FreeItemPage": {
        "description": "An item for one viewer.",
        "allOf": [
          {
            "$ref": "#/components/schemas/FreeItemCard"
          },
          {
            "type": "object",
            "properties": {
              "description": {
                "type": "string",
                "maxLength": 800
              },
              "photos": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    },
                    "width": {
                      "type": "integer",
                      "nullable": true
                    },
                    "height": {
                      "type": "integer",
                      "nullable": true
                    }
                  }
                }
              },
              "giver": {
                "type": "object",
                "nullable": true,
                "description": "A person's post shows their first name and how many things they gave (\"Gave 6 things\"); null when posted as a provider.",
                "properties": {
                  "firstName": {
                    "type": "string",
                    "nullable": true
                  },
                  "gaveCount": {
                    "type": "integer"
                  }
                }
              },
              "pickup": {
                "$ref": "#/components/schemas/FreeItemPickup"
              },
              "viewer": {
                "type": "object",
                "properties": {
                  "signedIn": {
                    "type": "boolean"
                  },
                  "isGiver": {
                    "type": "boolean"
                  },
                  "ask": {
                    "$ref": "#/components/schemas/FreeItemOwnAsk"
                  },
                  "canAsk": {
                    "type": "boolean"
                  },
                  "cannotAsk": {
                    "type": "string",
                    "nullable": true,
                    "description": "Why the viewer can't ask now: `sign_in`, `verify_email`, `verify_phone`, `own_item`, `already_asked`, `not_available`, `went_to_first`, `asking_paused`, `open_ask_limit`."
                  },
                  "openAsks": {
                    "type": "integer",
                    "nullable": true,
                    "description": "Their open asks, for \"You have 5 open asks\"."
                  },
                  "askingPausedUntil": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  }
                }
              },
              "asks": {
                "type": "array",
                "nullable": true,
                "description": "The giver's own view only.",
                "items": {
                  "$ref": "#/components/schemas/FreeItemGiverAsk"
                }
              },
              "review": {
                "type": "object",
                "nullable": true,
                "description": "The giver's own view only.",
                "properties": {
                  "heldReason": {
                    "type": "string",
                    "nullable": true,
                    "enum": [
                      "first_post",
                      "auto_check",
                      "reported",
                      "staff"
                    ]
                  },
                  "decision": {
                    "type": "string",
                    "nullable": true,
                    "enum": [
                      "approved",
                      "taken_down"
                    ]
                  },
                  "decisionReason": {
                    "type": "string",
                    "nullable": true,
                    "enum": [
                      "not_free",
                      "not_allowed",
                      "unsafe_item",
                      "reselling",
                      "harassment",
                      "misleading",
                      "duplicate",
                      "other"
                    ]
                  },
                  "decisionNote": {
                    "type": "string",
                    "nullable": true
                  }
                }
              },
              "nudge": {
                "type": "object",
                "nullable": true,
                "description": "On the giver's own post as a provider, after 3 posts as that provider in 30 days: list it as a resource instead. A prompt, never a block.",
                "properties": {
                  "listAsResource": {
                    "type": "boolean"
                  },
                  "providerId": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        ]
      },
      "FreeItemAddress": {
        "type": "object",
        "required": [
          "line1",
          "city",
          "region",
          "postal_code"
        ],
        "description": "The pickup street address, private. The public area is its city.",
        "properties": {
          "line1": {
            "type": "string",
            "maxLength": 120
          },
          "line2": {
            "type": "string",
            "nullable": true,
            "maxLength": 60
          },
          "city": {
            "type": "string",
            "maxLength": 80
          },
          "region": {
            "type": "string",
            "description": "The state."
          },
          "postal_code": {
            "type": "string"
          },
          "country": {
            "type": "string",
            "nullable": true,
            "description": "Defaults to US."
          }
        }
      },
      "FreeItemPhotoInput": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "A photo uploaded with `POST /storage/upload` to the `free-stuff-photos` bucket under your own id."
          },
          "width": {
            "type": "integer",
            "nullable": true
          },
          "height": {
            "type": "integer",
            "nullable": true
          }
        }
      },
      "FreeItemInput": {
        "type": "object",
        "required": [
          "title",
          "categoryId",
          "condition",
          "pickup",
          "pickupMethods",
          "photos"
        ],
        "properties": {
          "title": {
            "type": "string",
            "minLength": 3,
            "maxLength": 70
          },
          "description": {
            "type": "string",
            "maxLength": 800
          },
          "categoryId": {
            "type": "string",
            "description": "From `GET /free-stuff/categories`."
          },
          "condition": {
            "type": "string",
            "enum": [
              "new",
              "like_new",
              "good",
              "fair",
              "for_parts"
            ]
          },
          "pickup": {
            "type": "object",
            "required": [
              "address"
            ],
            "properties": {
              "address": {
                "$ref": "#/components/schemas/FreeItemAddress"
              },
              "point": {
                "type": "object",
                "nullable": true,
                "properties": {
                  "lat": {
                    "type": "number"
                  },
                  "lng": {
                    "type": "number"
                  }
                },
                "description": "A street-level map point for the address, stored on the private address only."
              },
              "note": {
                "type": "string",
                "nullable": true,
                "maxLength": 280,
                "description": "Pickup details for the person chosen (\"Porch, side door, after 5\")."
              }
            }
          },
          "pickupMethods": {
            "type": "array",
            "minItems": 1,
            "maxItems": 3,
            "items": {
              "type": "string",
              "enum": [
                "porch",
                "public_place",
                "delivery"
              ]
            }
          },
          "availableUntil": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Up to 14 days from posting, 2 for food; that limit by default."
          },
          "selectionMode": {
            "type": "string",
            "enum": [
              "choose",
              "first"
            ],
            "default": "choose"
          },
          "photos": {
            "type": "array",
            "minItems": 1,
            "maxItems": 6,
            "items": {
              "$ref": "#/components/schemas/FreeItemPhotoInput"
            }
          },
          "postedAsProviderId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "A provider you can manage (a non-profit or church, a business, a community)."
          }
        }
      },
      "ResourceError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "additionalProperties": true,
                "description": "`field` names the field to show the message beside; `constraint` the schema rule."
              }
            },
            "required": [
              "code",
              "message",
              "details"
            ]
          }
        },
        "description": "Every refusal in Resources. A rule the schema keeps answers with its constraint as `code`: 422 for one a person fixes by changing what they typed (`resources_members_only`, `resources_community_cost`, `resources_fee_shape`, `resource_locations_owner`, `resource_hours_no_overlap`, ...), 409 for a clash (`stale_version`, `uq_resource_revisions_one_pending`, `resources_transfer_locations`, ...)."
      },
      "FreeStuffBlock": {
        "type": "object",
        "properties": {
          "blocked": {
            "type": "boolean"
          },
          "side": {
            "type": "string",
            "enum": [
              "giver",
              "asker"
            ],
            "description": "Which side of the ask the caller is on."
          }
        }
      },
      "PhoneVerificationStatus": {
        "type": "object",
        "properties": {
          "available": {
            "type": "boolean",
            "description": "Texted codes can be sent here now. False: \"Phone verification isn't available yet\"."
          },
          "phoneVerified": {
            "type": "boolean"
          },
          "phone": {
            "type": "string",
            "nullable": true,
            "description": "The last four digits of the number on file, \"•••• 0108\"."
          }
        }
      },
      "PhoneVerificationError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "sign_in_again",
                  "phone_invalid",
                  "phone_in_use",
                  "code_wrong",
                  "code_expired",
                  "not_verified",
                  "too_many_codes",
                  "too_many_tries",
                  "phone_verification_unavailable",
                  "not_found",
                  "internal"
                ]
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      },
      "FundraiserResourceNudge": {
        "type": "object",
        "description": "\"Send a reminder\", organizer only, on a requested link: once every 3 days.",
        "properties": {
          "canSend": {
            "type": "boolean"
          },
          "lastAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "nextAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the next one can go",
            "while it can't now.": null
          }
        }
      },
      "FundraiserResourcePayout": {
        "type": "object",
        "description": "The organizer's \"Send gifts straight to <name>\" for one link.",
        "properties": {
          "on": {
            "type": "boolean",
            "description": "Gifts go straight to this link's provider now (read from the fundraiser's beneficiary)."
          },
          "offered": {
            "type": "boolean",
            "description": "It can be turned on: a confirmed link to an active non-profit or church, on a fundraiser not already raising for a non-profit, with no money activity. The money checks run again on PUT."
          },
          "canTurnOff": {
            "type": "boolean",
            "description": "This link can turn it off (it made the move",
            "or is a link to the same non-profit) and nothing is locked.": null
          },
          "locked": {
            "type": "boolean",
            "description": "The fundraiser has money activity (a gift, a payment intent, a payout, a ledger entry, a transfer): where its gifts go can no longer change."
          },
          "refusal": {
            "type": "string",
            "nullable": true,
            "description": "Why it can't be turned on, when it isn't on.",
            "enum": [
              "payout_not_offered",
              "link_not_confirmed",
              "provider_not_active",
              "already_nonprofit",
              "beneficiary_invitation_pending",
              "beneficiary_person_required",
              "payout_locked"
            ]
          }
        }
      },
      "FundraiserResourceLink": {
        "type": "object",
        "description": "One help a fundraiser names. A visitor gets the first eleven properties; the organizer all of them. No decline reason is ever included, and the provider's note only in the organizer's view.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "requested",
              "needs_confirmation",
              "confirmed",
              "declined"
            ]
          },
          "resource": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "title": {
                "type": "string"
              },
              "listing": {
                "type": "string",
                "enum": [
                  "live",
                  "paused",
                  "no_longer_listed"
                ],
                "description": "\"Not taking new people\" (paused) or \"No longer listed\". The link stays either way."
              }
            }
          },
          "provider": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResourceProviderCard"
              }
            ],
            "nullable": true,
            "description": "The provider that confirmed or declined it, or that is asked to (after a transfer, the new provider)."
          },
          "estimateCents": {
            "type": "integer",
            "nullable": true
          },
          "confirmedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "\"Confirmed by <provider> · <date>\"."
          },
          "confirmedBy": {
            "type": "string",
            "nullable": true,
            "description": "The confirming provider's name."
          },
          "confirmedFeeCents": {
            "type": "integer",
            "nullable": true,
            "description": "The fee the provider confirmed, which donors see as the fee; null: the estimate stands."
          },
          "ended": {
            "type": "object",
            "nullable": true,
            "description": "A confirmed link whose help stopped matching (board FrEdge): `help_ended` (archived, with its date, or no longer listed) or `provider_removed` (the provider is no longer active on FundlyHub). A paused help is not an end.",
            "properties": {
              "reason": {
                "type": "string",
                "enum": [
                  "help_ended",
                  "provider_removed"
                ]
              },
              "at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              }
            }
          },
          "giftsGoTo": {
            "type": "string",
            "enum": [
              "provider",
              "organizer",
              "person",
              "another_nonprofit"
            ],
            "description": "Where this link's gifts go, from the fundraiser's beneficiary: straight to the provider, or to the organizer (who pays the provider, \"The organizer pays the business\"), the person raised for, or another non-profit."
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time"
          },
          "remindedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "The provider was reminded (7 days)."
          },
          "decidedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "clientConsent": {
            "type": "boolean",
            "description": "The organizer agreed the provider may confirm they are its client."
          },
          "previousProvider": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResourceProviderCard"
              }
            ],
            "nullable": true,
            "description": "needs_confirmation after a transfer: the provider that confirmed it before. Direct payout stays with it."
          },
          "removable": {
            "type": "boolean",
            "description": "False while this link holds \"Send gifts straight to\" (DELETE answers 409 `payout_on`)."
          },
          "payout": {
            "$ref": "#/components/schemas/FundraiserResourcePayout"
          },
          "providerNote": {
            "type": "string",
            "nullable": true,
            "maxLength": 280,
            "description": "Organizer only: the provider's note when it confirmed."
          },
          "nudge": {
            "allOf": [
              {
                "$ref": "#/components/schemas/FundraiserResourceNudge"
              }
            ],
            "nullable": true,
            "description": "Organizer only, and only on a requested link."
          }
        }
      },
      "FundraiserResourceGifts": {
        "type": "object",
        "description": "Who receives the fundraiser's gifts, from its beneficiary (the source of truth checkout reads).",
        "properties": {
          "to": {
            "type": "string",
            "enum": [
              "organizer",
              "person",
              "nonprofit"
            ]
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "The public name of the person or non-profit; null for the organizer."
          },
          "orgId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "providerId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "That non-profit's Resources provider",
            "when it has one.": null
          },
          "directPayout": {
            "type": "object",
            "nullable": true,
            "description": "Organizer only: the link whose \"Send gifts straight to\" made this so, while that move holds (it survives a transfer, merge or decline).",
            "properties": {
              "linkId": {
                "type": "string",
                "format": "uuid"
              },
              "since": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "locked": {
            "type": "boolean",
            "description": "Organizer only: money activity, so where gifts go can no longer change."
          }
        }
      },
      "FundraiserResources": {
        "type": "object",
        "properties": {
          "fundraiserId": {
            "type": "string",
            "format": "uuid"
          },
          "viewer": {
            "type": "string",
            "enum": [
              "public",
              "organizer"
            ]
          },
          "fundraiser": {
            "type": "object",
            "description": "The fundraiser's state, for \"ended short of the fee\", and whether it is a project (/p/<slug>) or a fundraiser (/f/<slug>).",
            "properties": {
              "status": {
                "type": "string"
              },
              "isProject": {
                "type": "boolean"
              }
            }
          },
          "gifts": {
            "$ref": "#/components/schemas/FundraiserResourceGifts"
          },
          "links": {
            "type": "array",
            "description": "Confirmed first, then waiting (needs_confirmation, requested), then declined.",
            "items": {
              "$ref": "#/components/schemas/FundraiserResourceLink"
            }
          }
        }
      },
      "MyHelp": {
        "type": "object",
        "properties": {
          "saved": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "items": {
                "type": "array",
                "maxItems": 50,
                "items": {
                  "type": "object",
                  "properties": {
                    "provider": {
                      "$ref": "#/components/schemas/ResourceProviderCard"
                    },
                    "savedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "listed": {
                      "type": "boolean",
                      "description": "It still has help the person can find."
                    }
                  }
                }
              }
            }
          },
          "fundraisers": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "items": {
                "type": "array",
                "maxItems": 20,
                "items": {
                  "type": "object",
                  "properties": {
                    "fundraiser": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "title": {
                          "type": "string"
                        },
                        "slug": {
                          "type": "string",
                          "nullable": true
                        },
                        "status": {
                          "type": "string"
                        },
                        "isProject": {
                          "type": "boolean",
                          "description": "A project: its page is /p/<slug>; a fundraiser: /f/<slug>."
                        }
                      }
                    },
                    "gifts": {
                      "$ref": "#/components/schemas/FundraiserResourceGifts"
                    },
                    "links": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FundraiserResourceLink"
                      }
                    }
                  }
                }
              }
            }
          },
          "freeStuff": {
            "type": "object",
            "nullable": true,
            "description": "Up to 3 open free stuff items (theirs to pick up first); null when free stuff is off for the person.",
            "properties": {
              "total": {
                "type": "integer"
              },
              "items": {
                "type": "array",
                "maxItems": 3,
                "items": {
                  "type": "object",
                  "properties": {
                    "side": {
                      "type": "string",
                      "enum": [
                        "giving",
                        "getting"
                      ]
                    },
                    "askStatus": {
                      "type": "string",
                      "nullable": true
                    },
                    "item": {
                      "$ref": "#/components/schemas/FreeItemCard"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ResourceFields": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "minLength": 3,
            "maxLength": 80
          },
          "summary": {
            "type": "string",
            "maxLength": 280
          },
          "details": {
            "type": "string",
            "maxLength": 2000,
            "nullable": true
          },
          "topic_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "maxItems": 5,
            "description": "Material."
          },
          "primary_topic_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "need_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Types of help under the topics picked."
          },
          "cost_model": {
            "type": "string",
            "enum": [
              "free",
              "free_if_qualify",
              "sliding_scale",
              "flat_fee",
              "free_consult_then_fee",
              "suggested_donation"
            ],
            "description": "`suggested_donation` is for communities only; a community offers only `free` and `suggested_donation`."
          },
          "fee_min_cents": {
            "type": "integer",
            "nullable": true
          },
          "fee_max_cents": {
            "type": "integer",
            "nullable": true
          },
          "audience": {
            "type": "string",
            "enum": [
              "everyone",
              "members",
              "members_approved"
            ],
            "description": "Members-only help is for communities and churches."
          },
          "faith_participation": {
            "type": "boolean",
            "description": "Churches only (CH-01)."
          },
          "faith_note": {
            "type": "string",
            "maxLength": 140,
            "nullable": true,
            "description": "What a church's help asks people to join (\"A short prayer before the pantry opens\"), shown on the card as written. Only with `faith_participation` (turning that off clears it), and needed before the help goes to review. Material: on live help a change waits for review."
          },
          "eligibility": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "income_limit_pct_fpl": {
            "type": "integer",
            "minimum": 50,
            "maximum": 600,
            "nullable": true
          },
          "how_to_start": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "walk_in",
                "appointment",
                "phone",
                "online",
                "home_visit"
              ]
            }
          },
          "apply_url": {
            "type": "string",
            "description": "https:// only.",
            "nullable": true
          },
          "phone": {
            "type": "string",
            "description": "Any US format in; stored as +1NXXNXXXXXX.",
            "nullable": true
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "referral_required": {
            "type": "boolean"
          },
          "referral_note": {
            "type": "string",
            "nullable": true
          },
          "delivery": {
            "type": "string",
            "enum": [
              "none",
              "available",
              "required"
            ]
          },
          "stock_note": {
            "type": "string",
            "maxLength": 140,
            "nullable": true
          },
          "capacity": {
            "type": "string",
            "enum": [
              "taking",
              "waitlist",
              "paused"
            ]
          },
          "capacity_note": {
            "type": "string",
            "maxLength": 140,
            "nullable": true
          },
          "paused_until": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "online": {
            "type": "boolean"
          },
          "confidential_address": {
            "type": "boolean",
            "description": "Turning it on applies at once; turning it off goes to review."
          },
          "hours_source": {
            "type": "string",
            "enum": [
              "location",
              "own"
            ]
          },
          "hours": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "weekday": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 7
                },
                "opens_at": {
                  "type": "string",
                  "example": "09:00"
                },
                "closes_at": {
                  "type": "string",
                  "example": "17:00"
                }
              }
            }
          },
          "hours_exceptions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "starts_on": {
                  "type": "string",
                  "format": "date"
                },
                "ends_on": {
                  "type": "string",
                  "format": "date"
                },
                "opens_at": {
                  "type": "string",
                  "nullable": true
                },
                "closes_at": {
                  "type": "string",
                  "nullable": true
                },
                "reason": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "location_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The provider's own locations. A business manager may name only their own."
          },
          "service_areas": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "place_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "state_code": {
                  "type": "string",
                  "pattern": "^[A-Z]{2}$"
                },
                "nationwide": {
                  "type": "boolean"
                },
                "country": {
                  "type": "string"
                }
              }
            },
            "description": "Each one a city or ZIP (place_id), a state, or nationwide. At least one to go to review or live."
          },
          "license_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The provider's licenses this help relies on."
          }
        },
        "description": "The fields the shared editor writes. On help that has been published, phone, languages, capacity, the stock note, delivery, how to start and the hours are small (live at once); the rest open or replace the one pending revision (NP-08)."
      },
      "Resource": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ResourceFields"
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "provider_id": {
                "type": "string",
                "format": "uuid"
              },
              "status": {
                "type": "string",
                "enum": [
                  "draft",
                  "in_review",
                  "changes_requested",
                  "live",
                  "paused",
                  "rejected",
                  "archived"
                ]
              },
              "hold": {
                "type": "string",
                "enum": [
                  "stale",
                  "license",
                  "provider_suspended",
                  "taken_down"
                ],
                "nullable": true
              },
              "paused_by": {
                "type": "string",
                "enum": [
                  "provider",
                  "staff"
                ],
                "nullable": true
              },
              "staff_reason": {
                "type": "string",
                "nullable": true
              },
              "version": {
                "type": "integer",
                "description": "Send it back as If-Match (or `version`) on the next edit."
              },
              "created_via": {
                "type": "string",
                "enum": [
                  "provider",
                  "staff"
                ]
              },
              "added_by_fundlyhub": {
                "type": "boolean"
              },
              "published_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "archived_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "merged_into": {
                "type": "string",
                "format": "uuid",
                "nullable": true
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              },
              "updated_at": {
                "type": "string",
                "format": "date-time"
              },
              "freshness": {
                "type": "object",
                "properties": {
                  "state": {
                    "type": "string",
                    "enum": [
                      "ok",
                      "due_soon",
                      "due",
                      "out_of_date",
                      "hidden"
                    ]
                  },
                  "last_confirmed_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  },
                  "days_since": {
                    "type": "integer",
                    "nullable": true
                  },
                  "next_check_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  }
                },
                "nullable": true
              },
              "changes_in_review": {
                "type": "boolean",
                "description": "\"Changes in review\": a revision waits while the live version stays up."
              },
              "pending_revision": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "base_version": {
                    "type": "integer"
                  },
                  "fields": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "submitted_at": {
                    "type": "string",
                    "format": "date-time"
                  }
                },
                "nullable": true
              },
              "decisions": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "outcome": {
                      "type": "string",
                      "enum": [
                        "approved",
                        "changes_requested",
                        "rejected"
                      ]
                    },
                    "submitted_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "decided_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "notes": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      },
                      "description": "Per field, and `general`.",
                      "nullable": true
                    },
                    "reason_code": {
                      "type": "string",
                      "nullable": true
                    },
                    "reason": {
                      "type": "string",
                      "nullable": true
                    },
                    "reason_copy": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              },
              "place_labels": {
                "type": "object",
                "description": "The cities and ZIP codes the service areas (and the pending change's) name, by place id, as the editor shows them: \"Folsom, CA\", \"95630 · Folsom, CA\".",
                "additionalProperties": {
                  "type": "object",
                  "properties": {
                    "label": {
                      "type": "string"
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "city",
                        "postal_code"
                      ]
                    }
                  }
                }
              },
              "viewer_can": {
                "type": "object",
                "properties": {
                  "manage": {
                    "type": "boolean"
                  },
                  "capacity": {
                    "type": "boolean"
                  },
                  "confirm": {
                    "type": "boolean"
                  }
                },
                "nullable": true
              }
            }
          }
        ]
      },
      "ResourceEditorLocation": {
        "type": "object",
        "description": "A place of the provider's entity, as step 4 of the editor picks it.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "kind": {
            "type": "string",
            "enum": [
              "premises",
              "service_area",
              "online"
            ]
          },
          "is_primary": {
            "type": "boolean"
          },
          "public": {
            "type": "boolean",
            "description": "Find help may show its street address and pin: open, a storefront, public and resolved. Otherwise people see only its city (and a confidential listing never shows it)."
          },
          "address": {
            "type": "object",
            "nullable": true,
            "additionalProperties": {
              "type": "string"
            },
            "description": "{line1, line2, city, region, postal_code, country}."
          },
          "city": {
            "type": "string",
            "nullable": true,
            "description": "\"Folsom, CA\"."
          },
          "hours": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "weekday": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 7
                },
                "opens_at": {
                  "type": "string",
                  "example": "09:00"
                },
                "closes_at": {
                  "type": "string",
                  "example": "17:00"
                }
              }
            }
          },
          "mine": {
            "type": "boolean",
            "description": "For a business manager, one of their own locations; true for everyone else."
          }
        }
      },
      "ResourceListItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "provider_id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "in_review",
              "changes_requested",
              "live",
              "paused",
              "rejected",
              "archived"
            ]
          },
          "hold": {
            "type": "string",
            "enum": [
              "stale",
              "license",
              "provider_suspended",
              "taken_down"
            ],
            "nullable": true
          },
          "paused_by": {
            "type": "string",
            "enum": [
              "provider",
              "staff"
            ],
            "nullable": true
          },
          "capacity": {
            "type": "string"
          },
          "stock_note": {
            "type": "string",
            "nullable": true
          },
          "version": {
            "type": "integer"
          },
          "added_by_fundlyhub": {
            "type": "boolean"
          },
          "primary_topic_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "location_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "changes_in_review": {
            "type": "boolean"
          },
          "published_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "archived_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "freshness": {
            "type": "object",
            "properties": {
              "state": {
                "type": "string",
                "enum": [
                  "ok",
                  "due_soon",
                  "due",
                  "out_of_date",
                  "hidden"
                ]
              },
              "last_confirmed_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "days_since": {
                "type": "integer",
                "nullable": true
              },
              "next_check_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              }
            },
            "nullable": true
          },
          "viewer_can": {
            "type": "object",
            "properties": {
              "manage": {
                "type": "boolean"
              },
              "capacity": {
                "type": "boolean"
              },
              "confirm": {
                "type": "boolean"
              }
            },
            "nullable": true
          }
        }
      },
      "ResourceProvider": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "nonprofit",
              "business",
              "community",
              "program",
              "person"
            ]
          },
          "slug": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "suspended",
              "taken_down"
            ]
          },
          "status_reason": {
            "type": "string",
            "nullable": true
          },
          "name": {
            "type": "string"
          },
          "is_church": {
            "type": "boolean"
          },
          "entity": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string"
              },
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "slug": {
                "type": "string"
              }
            },
            "nullable": true
          },
          "program": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "website": {
                "type": "string",
                "nullable": true
              },
              "phone": {
                "type": "string",
                "nullable": true
              },
              "place_id": {
                "type": "string",
                "format": "uuid"
              }
            },
            "nullable": true
          },
          "person": {
            "type": "object",
            "nullable": true,
            "description": "A person's own provider (#2436): whose profile it is (also `entity.id`, with `entity.kind` person) and where that account stands. `listable` is the public rule: the account is active (or its suspension ran out) and not waiting to be deleted. Never the email or phone.",
            "properties": {
              "profile_id": {
                "type": "string",
                "format": "uuid"
              },
              "email_verified": {
                "type": "boolean"
              },
              "account_status": {
                "type": "string"
              },
              "listable": {
                "type": "boolean"
              }
            }
          },
          "city_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "part_of_provider_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "city_name": {
            "type": "string",
            "nullable": true
          },
          "city_region": {
            "type": "string",
            "nullable": true
          },
          "part_of": {
            "type": "object",
            "nullable": true,
            "description": "The non-profit or church a community is part of (CM-12).",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "kind": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "is_church": {
                "type": "boolean"
              },
              "entity_slug": {
                "type": "string",
                "nullable": true
              },
              "status": {
                "type": "string"
              }
            }
          },
          "parts": {
            "type": "array",
            "description": "The communities that are part of this non-profit or church.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "kind": {
                  "type": "string"
                },
                "slug": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "is_church": {
                  "type": "boolean"
                },
                "entity_slug": {
                  "type": "string",
                  "nullable": true
                },
                "status": {
                  "type": "string"
                }
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MyResourceProvider": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "nonprofit",
              "business",
              "community"
            ]
          },
          "entity": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "provider": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "slug": {
                "type": "string"
              },
              "status": {
                "type": "string"
              }
            },
            "nullable": true
          },
          "role": {
            "type": "string"
          },
          "can_manage": {
            "type": "boolean"
          },
          "is_church": {
            "type": "boolean"
          }
        }
      },
      "ProfessionalLicense": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "provider_id": {
            "type": "string",
            "format": "uuid"
          },
          "holder_name": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "attorney",
              "physician",
              "nurse",
              "mental_health",
              "tax_preparer",
              "other"
            ]
          },
          "license_number": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "verified",
              "mismatch",
              "not_found",
              "expired"
            ]
          },
          "checked_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "source_url": {
            "type": "string",
            "nullable": true
          },
          "next_check_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "resources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "title": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "EventError": {
        "type": "object",
        "description": "An Events refusal. `validation_error` carries the fields in `details`; `not_allowed` (409) carries `details.action` and `details.reason`, the same i18n key the viewer block shows.",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      },
      "EventViewer": {
        "type": "object",
        "description": "What the viewer may do with the event. The page shows actions from here and never re-derives the rules.",
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "guest",
              "host",
              "staff"
            ]
          },
          "actions": {
            "type": "object",
            "properties": {
              "edit": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "delete": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "submit": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "duplicate": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "postpone": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "cancel": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "manage_hosts": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "manage_tickets": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "manage_volunteers": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "manage_sponsors": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "manage_photos": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "edit_recap": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "publish_recap": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "register": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "volunteer_signup": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "sponsor_request": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "report": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "approve": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "request_changes": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "reject": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "feature": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "pause_sales": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "suspend": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "check_in": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "refund": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "join_waitlist": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              },
              "refund_all": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows (events.viewer.reasons.*), when not allowed."
                  }
                }
              }
            }
          },
          "submit_problems": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Hosts and staff: the i18n keys of what is missing before submitting (events.submit.problems.*)."
          },
          "order": {
            "nullable": true,
            "description": "The signed-in viewer's own live order for the event, with its tickets and what they may do with it (#2487).",
            "allOf": [
              {
                "$ref": "#/components/schemas/EventOrder"
              }
            ]
          },
          "waitlist": {
            "nullable": true,
            "description": "The signed-in viewer's open waitlist place.",
            "allOf": [
              {
                "$ref": "#/components/schemas/EventWaitlistEntry"
              }
            ]
          },
          "sale_alert": {
            "type": "boolean",
            "description": "Tickets not on sale yet: the signed-in viewer asked to be told when they are (POST /events/{id}/sale-alert, #2499). False signed out."
          }
        }
      },
      "EventSaleStatus": {
        "type": "string",
        "enum": [
          "not_published",
          "cancelled",
          "suspended",
          "ended",
          "paused",
          "not_on_sale_yet",
          "sales_closed",
          "sold_out",
          "on_sale"
        ],
        "description": "Computed from dates and counts, never stored."
      },
      "EventDay": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "starts_at": {
            "type": "string",
            "format": "date-time"
          },
          "ends_at": {
            "type": "string",
            "format": "date-time"
          },
          "position": {
            "type": "integer"
          }
        }
      },
      "EventHost": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "platform",
              "member",
              "organization",
              "community",
              "sponsor"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "invited",
              "accepted",
              "declined"
            ],
            "description": "Guests see accepted hosts only."
          },
          "position": {
            "type": "integer"
          },
          "target_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "slug": {
            "type": "string",
            "nullable": true
          },
          "image_url": {
            "type": "string",
            "nullable": true
          },
          "organization_kind": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "EventTicketType": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "price_cents": {
            "type": "integer"
          },
          "goods_value_cents": {
            "type": "integer",
            "description": "The value of the dinner (not tax-deductible)."
          },
          "seats_per_ticket": {
            "type": "integer"
          },
          "quantity": {
            "type": "integer",
            "nullable": true
          },
          "sales_start": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "sales_end": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "min_per_order": {
            "type": "integer"
          },
          "max_per_order": {
            "type": "integer",
            "nullable": true
          },
          "access": {
            "type": "string",
            "enum": [
              "public",
              "code",
              "community_members"
            ]
          },
          "hidden": {
            "type": "boolean"
          },
          "event_day_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "stopped_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "position": {
            "type": "integer"
          },
          "availability": {
            "type": "object",
            "properties": {
              "state": {
                "type": "string",
                "enum": [
                  "stopped",
                  "not_on_sale_yet",
                  "sales_closed",
                  "sold_out",
                  "on_sale"
                ]
              },
              "remaining": {
                "type": "integer",
                "nullable": true
              }
            }
          },
          "sold": {
            "type": "integer",
            "description": "Hosts and staff only (#2494): tickets of this type held or active now."
          },
          "has_sales": {
            "type": "boolean",
            "description": "Hosts and staff only (#2494): a ticket of this type was ever sold. Such a type can be stopped, not changed or deleted (`ticket_type_has_sales`)."
          }
        }
      },
      "EventTicketTypeInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 80
          },
          "description": {
            "type": "string",
            "maxLength": 500,
            "nullable": true
          },
          "price_cents": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000,
            "description": "0 on a free event."
          },
          "goods_value_cents": {
            "type": "integer",
            "minimum": 0,
            "description": "At most the price."
          },
          "seats_per_ticket": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "nullable": true
          },
          "sales_start": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "sales_end": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "min_per_order": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          },
          "max_per_order": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "nullable": true
          },
          "access": {
            "type": "string",
            "enum": [
              "public",
              "code",
              "community_members"
            ]
          },
          "access_code": {
            "type": "string",
            "minLength": 3,
            "maxLength": 40,
            "description": "For \"only with a code\"; stored as a hash, never returned."
          },
          "hidden": {
            "type": "boolean"
          },
          "event_day_id": {
            "type": "string",
            "format": "uuid",
            "description": "Required on a \"one day each\" event, not allowed otherwise.",
            "nullable": true
          }
        }
      },
      "EventFundraiser": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "cover_image": {
            "type": "string",
            "nullable": true
          },
          "is_project": {
            "type": "boolean"
          },
          "status": {
            "type": "string"
          },
          "goal_amount_cents": {
            "type": "integer"
          },
          "raised_cents": {
            "type": "integer"
          },
          "share_percent": {
            "type": "integer"
          },
          "position": {
            "type": "integer"
          },
          "deleted": {
            "type": "boolean"
          },
          "owner_name": {
            "type": "string",
            "nullable": true,
            "description": "The organizer's public name."
          },
          "owner_avatar": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "EventFundraiserShare": {
        "type": "object",
        "properties": {
          "fundraiser_id": {
            "type": "string",
            "format": "uuid"
          },
          "share_percent": {
            "type": "integer"
          },
          "position": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          }
        }
      },
      "EventSponsor": {
        "type": "object",
        "description": "Guests see shown sponsors with a logo, without amount, payment status or in-kind note.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "sponsor_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "name": {
            "type": "string"
          },
          "logo_url": {
            "type": "string",
            "nullable": true
          },
          "sponsor_slug": {
            "type": "string",
            "nullable": true
          },
          "website": {
            "type": "string",
            "nullable": true
          },
          "tier": {
            "type": "string",
            "enum": [
              "presenting",
              "table",
              "in_kind"
            ]
          },
          "amount_cents": {
            "type": "integer"
          },
          "payment_status": {
            "type": "string",
            "enum": [
              "pledged",
              "invoiced",
              "received"
            ]
          },
          "in_kind_note": {
            "type": "string",
            "nullable": true
          },
          "show_on_page": {
            "type": "boolean"
          },
          "thank_in_recap": {
            "type": "boolean"
          },
          "position": {
            "type": "integer"
          }
        }
      },
      "EventSponsorInput": {
        "type": "object",
        "additionalProperties": false,
        "description": "A FundlyHub sponsor (`sponsor_id`, which brings its own name, logo and page) or another business (`business_name`, `website`, an uploaded `logo_url`). PATCH takes every field but `sponsor_id`.",
        "properties": {
          "sponsor_id": {
            "type": "string",
            "format": "uuid"
          },
          "business_name": {
            "type": "string",
            "maxLength": 120
          },
          "website": {
            "type": "string",
            "nullable": true
          },
          "logo_url": {
            "type": "string",
            "nullable": true
          },
          "tier": {
            "type": "string",
            "enum": [
              "presenting",
              "table",
              "in_kind"
            ]
          },
          "amount_cents": {
            "type": "integer",
            "minimum": 0
          },
          "payment_status": {
            "type": "string",
            "enum": [
              "pledged",
              "invoiced",
              "received"
            ]
          },
          "in_kind_note": {
            "type": "string",
            "nullable": true
          },
          "show_on_page": {
            "type": "boolean"
          },
          "thank_in_recap": {
            "type": "boolean"
          }
        }
      },
      "EventSponsorRequest": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "business_name": {
            "type": "string"
          },
          "contact_name": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "message": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "new",
              "replied",
              "added",
              "dismissed"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "EventVolunteerRole": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "starts_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ends_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "slots": {
            "type": "integer"
          },
          "signup": {
            "type": "string",
            "enum": [
              "open",
              "assigned"
            ]
          },
          "can_check_in": {
            "type": "boolean"
          },
          "can_upload_photos": {
            "type": "boolean"
          },
          "free_seat": {
            "type": "boolean",
            "description": "Each confirmed volunteer gets one comp ticket, emailed to them (once per person per event). It goes back if they are removed, or the role loses its free seat, before the event ends, unless it was checked in."
          },
          "position": {
            "type": "integer"
          },
          "filled": {
            "type": "integer"
          },
          "open_slots": {
            "type": "integer"
          }
        }
      },
      "EventVolunteerRoleInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 80
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "starts_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ends_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "slots": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500
          },
          "signup": {
            "type": "string",
            "enum": [
              "open",
              "assigned"
            ]
          },
          "can_check_in": {
            "type": "boolean"
          },
          "can_upload_photos": {
            "type": "boolean"
          },
          "free_seat": {
            "type": "boolean"
          }
        }
      },
      "EventVolunteer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "role_id": {
            "type": "string",
            "format": "uuid"
          },
          "profile_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "email": {
            "type": "string",
            "nullable": true
          },
          "phone": {
            "type": "string",
            "nullable": true
          },
          "note": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "requested",
              "invited",
              "confirmed",
              "declined"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "has_free_seat": {
            "type": "boolean",
            "description": "The volunteer holds the comp ticket of a free-seat role (its order is confirmed)."
          }
        }
      },
      "EventPersonInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "profile_id": {
            "type": "string",
            "format": "uuid",
            "description": "A member (adding only)."
          },
          "name": {
            "type": "string",
            "maxLength": 120
          },
          "email": {
            "type": "string"
          },
          "phone": {
            "type": "string",
            "nullable": true
          },
          "note": {
            "type": "string",
            "maxLength": 500,
            "nullable": true
          }
        }
      },
      "EventPhoto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "to_review",
              "shown",
              "hidden"
            ]
          },
          "hidden_reason": {
            "type": "string",
            "nullable": true
          },
          "is_cover": {
            "type": "boolean"
          },
          "focal_x": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "nullable": true,
            "description": "Where the photo is cropped around, from the left (#2499); null is the centre."
          },
          "focal_y": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "nullable": true
          },
          "position": {
            "type": "integer"
          },
          "uploaded_by": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "EventRecapInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "recap_line": {
            "type": "string",
            "maxLength": 200,
            "nullable": true
          },
          "recap_html": {
            "type": "string",
            "description": "Sanitized when written.",
            "nullable": true
          },
          "recap_numbers": {
            "type": "object",
            "additionalProperties": {
              "type": "boolean"
            },
            "description": "Which numbers to show, at most 12."
          },
          "recap_show_sponsors": {
            "type": "boolean"
          },
          "recap_thank_volunteers": {
            "type": "boolean"
          },
          "recap_keep_give": {
            "type": "boolean"
          }
        }
      },
      "EventHostSelection": {
        "description": "Explicit host selection. Only super administrators may use accept_without_invitation. Platform hosting requires an active global super_admin or ambassador role.",
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "kind",
              "id"
            ],
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "member",
                  "organization",
                  "community",
                  "sponsor"
                ]
              },
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "accept_without_invitation": {
                "type": "boolean",
                "default": false,
                "description": "Explicit super-admin consent override, applied only when the host list is saved; also accepts an existing pending invitation."
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "kind",
              "id"
            ],
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "platform"
                ]
              },
              "id": {
                "type": "string",
                "nullable": true,
                "enum": [
                  null
                ]
              }
            }
          }
        ]
      },
      "EventInput": {
        "type": "object",
        "additionalProperties": false,
        "description": "The fields a host edits; every one is optional on PATCH. Unknown fields are refused (422).",
        "properties": {
          "slug": {
            "type": "string",
            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
            "minLength": 3,
            "maxLength": 80
          },
          "title": {
            "type": "string",
            "maxLength": 120
          },
          "subtitle": {
            "type": "string",
            "maxLength": 200,
            "nullable": true
          },
          "about_html": {
            "type": "string",
            "description": "Sanitized when written.",
            "nullable": true
          },
          "program": {
            "type": "array",
            "maxItems": 40,
            "items": {
              "type": "object",
              "properties": {
                "time": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                }
              }
            }
          },
          "category": {
            "type": "string",
            "nullable": true
          },
          "cover_image": {
            "type": "string",
            "description": "Uploaded with POST /storage/upload.",
            "nullable": true
          },
          "cover_image_focal_x": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "nullable": true,
            "description": "The crop tool's focal point, from the left (#2499). Left out with a new cover, the server works one out from the photo; null is the centre."
          },
          "cover_image_focal_y": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "nullable": true,
            "description": "The focal point from the top."
          },
          "cover_video_url": {
            "type": "string",
            "nullable": true,
            "description": "A YouTube or Vimeo link that plays first in the event page's gallery; the cover photo stays the image cards and share images draw."
          },
          "page_theme": {
            "type": "string",
            "enum": [
              "violet",
              "white",
              "coral",
              "emerald",
              "ocean",
              "marigold",
              "graphite"
            ]
          },
          "attendance": {
            "type": "string",
            "enum": [
              "in_person",
              "online"
            ]
          },
          "online_url": {
            "type": "string",
            "description": "https; never public.",
            "nullable": true
          },
          "venue_place_id": {
            "type": "string",
            "format": "uuid",
            "description": "An address place, e.g. a saved venue from GET /me/event-venues.",
            "nullable": true
          },
          "venue_address": {
            "type": "object",
            "description": "An address as typed, resolved into an address place (422 `venue_address_unresolved` when it does not resolve).",
            "properties": {
              "line1": {
                "type": "string"
              },
              "line2": {
                "type": "string",
                "nullable": true
              },
              "city": {
                "type": "string"
              },
              "region": {
                "type": "string",
                "nullable": true
              },
              "postal_code": {
                "type": "string",
                "nullable": true
              },
              "country": {
                "type": "string",
                "nullable": true
              },
              "lat": {
                "type": "number"
              },
              "lng": {
                "type": "number"
              }
            }
          },
          "venue_name": {
            "type": "string",
            "nullable": true
          },
          "venue_details": {
            "type": "string",
            "nullable": true
          },
          "venue_tba": {
            "type": "boolean"
          },
          "city_place_id": {
            "type": "string",
            "format": "uuid",
            "description": "A city place, for an online or TBA event; a venue sets it to the venue's city.",
            "nullable": true
          },
          "address_visibility": {
            "type": "string",
            "enum": [
              "everyone",
              "ticket_holders"
            ]
          },
          "time_zone": {
            "type": "string",
            "example": "America/Los_Angeles"
          },
          "registration": {
            "type": "string",
            "enum": [
              "free",
              "paid"
            ]
          },
          "capacity": {
            "type": "integer",
            "minimum": 1,
            "nullable": true
          },
          "plus_ones": {
            "type": "integer",
            "minimum": 0,
            "maximum": 3
          },
          "ticket_scope": {
            "type": "string",
            "enum": [
              "every_day",
              "one_day_each"
            ]
          },
          "approval_required": {
            "type": "boolean"
          },
          "waitlist_enabled": {
            "type": "boolean"
          },
          "guests_without_account": {
            "type": "boolean"
          },
          "ask_guest_details": {
            "type": "boolean"
          },
          "show_attendees": {
            "type": "boolean"
          },
          "gift_prompt": {
            "type": "boolean"
          },
          "count_ticket_money": {
            "type": "boolean"
          },
          "free_cancellation_until": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "listed": {
            "type": "boolean"
          },
          "members_only_community_id": {
            "type": "string",
            "format": "uuid",
            "description": "One of the accepted community hosts.",
            "nullable": true
          }
        }
      },
      "EventPage": {
        "type": "object",
        "description": "The event page. Hosts and staff also get the online link, the staff note, hidden and stopped ticket types, invited and declined hosts, every sponsor and photo, and `viewer.submit_problems`. A hidden address (ticket holders only) is left out for everyone else.",
        "properties": {
          "event": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "slug": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "cover_image_focal_x": {
                "type": "number",
                "nullable": true,
                "description": "The cover's focal point, 0..1 from the left (#2499); null is the centre."
              },
              "cover_image_focal_y": {
                "type": "number",
                "nullable": true
              },
              "cover_video_url": {
                "type": "string",
                "nullable": true,
                "description": "The cover video, played first in the gallery (#2499)."
              },
              "status": {
                "type": "string",
                "enum": [
                  "draft",
                  "in_review",
                  "changes_requested",
                  "rejected",
                  "published"
                ]
              },
              "starts_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "ends_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "time_zone": {
                "type": "string"
              },
              "city": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "slug": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "region": {
                    "type": "string",
                    "nullable": true
                  },
                  "country": {
                    "type": "string"
                  }
                },
                "nullable": true
              },
              "page_theme": {
                "type": "string"
              },
              "registration": {
                "type": "string"
              },
              "venue": {
                "type": "object",
                "properties": {
                  "place_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "line1": {
                    "type": "string"
                  },
                  "unit": {
                    "type": "string",
                    "nullable": true
                  },
                  "postal_code": {
                    "type": "string",
                    "nullable": true
                  },
                  "city": {
                    "type": "string"
                  },
                  "region": {
                    "type": "string",
                    "nullable": true
                  },
                  "country": {
                    "type": "string"
                  },
                  "lat": {
                    "type": "number",
                    "nullable": true
                  },
                  "lng": {
                    "type": "number",
                    "nullable": true
                  }
                },
                "nullable": true
              },
              "recap": {
                "type": "object",
                "additionalProperties": true,
                "nullable": true
              }
            }
          },
          "days": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventDay"
            }
          },
          "hosts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventHost"
            }
          },
          "ticket_types": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventTicketType"
            }
          },
          "sponsors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventSponsor"
            }
          },
          "volunteer_roles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventVolunteerRole"
            }
          },
          "fundraisers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventFundraiser"
            }
          },
          "photos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventPhoto"
            }
          },
          "going": {
            "type": "object",
            "description": "The seats of people going, and (when the event shows who is going) the faces of buyers who agreed to be shown, at most 8.",
            "properties": {
              "count": {
                "type": "integer"
              },
              "faces": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "profile_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "name": {
                      "type": "string",
                      "nullable": true
                    },
                    "avatar_url": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "seats_left": {
            "type": "object",
            "description": "Seats left in all (every day), or per day (\"one day each\"); null for no limit.",
            "properties": {
              "total": {
                "type": "integer",
                "nullable": true
              },
              "by_day": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer",
                  "nullable": true
                }
              }
            }
          },
          "sale_status": {
            "$ref": "#/components/schemas/EventSaleStatus"
          },
          "viewer": {
            "$ref": "#/components/schemas/EventViewer"
          },
          "host_stats": {
            "type": "object",
            "description": "Hosts and staff only (#2494): the host panel's numbers.",
            "properties": {
              "tickets_sold": {
                "type": "integer",
                "description": "Tickets held or active now."
              },
              "requests": {
                "type": "integer",
                "description": "Orders waiting for the host's approval."
              },
              "raised_cents": {
                "type": "integer",
                "description": "Ticket money and gifts of paid and confirmed orders, less refunds."
              }
            }
          }
        }
      },
      "EventCandidate": {
        "type": "object",
        "required": [
          "kind",
          "id",
          "name",
          "image_url",
          "subtitle"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "member",
              "organization",
              "community",
              "sponsor"
            ]
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "image_url": {
            "type": "string",
            "nullable": true
          },
          "subtitle": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "EventListRow": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "subtitle": {
            "type": "string",
            "nullable": true
          },
          "cover_image": {
            "type": "string",
            "nullable": true
          },
          "cover_image_focal_x": {
            "type": "number",
            "nullable": true,
            "description": "Where the cover is cropped around, 0..1 from the left (#2499); null is the centre."
          },
          "cover_image_focal_y": {
            "type": "number",
            "nullable": true
          },
          "page_theme": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "attendance": {
            "type": "string"
          },
          "venue_tba": {
            "type": "boolean"
          },
          "venue_name": {
            "type": "string",
            "nullable": true
          },
          "time_zone": {
            "type": "string"
          },
          "registration": {
            "type": "string",
            "enum": [
              "free",
              "paid"
            ]
          },
          "starts_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ends_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "day_count": {
            "type": "integer"
          },
          "city": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "region": {
                "type": "string",
                "nullable": true
              },
              "country": {
                "type": "string"
              }
            },
            "nullable": true
          },
          "main_host": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string"
              },
              "name": {
                "type": "string",
                "nullable": true
              }
            },
            "nullable": true
          },
          "accepted_hosts": {
            "type": "array",
            "description": "Confirmed hosts in saved host order, with public entity names and pictures for event cards. Invited and declined hosts are excluded. FundlyHub appears only when it is an accepted host. Empty when there are no accepted hosts; the legacy main_host field is retained.",
            "items": {
              "type": "object",
              "required": [
                "id",
                "kind",
                "name",
                "image_url",
                "status",
                "position"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "platform",
                    "member",
                    "organization",
                    "community",
                    "sponsor"
                  ]
                },
                "name": {
                  "type": "string",
                  "nullable": true
                },
                "image_url": {
                  "type": "string",
                  "nullable": true
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "accepted"
                  ]
                },
                "position": {
                  "type": "integer"
                }
              }
            }
          },
          "min_price_cents": {
            "type": "integer",
            "nullable": true
          },
          "featured": {
            "type": "boolean"
          },
          "members_only": {
            "type": "boolean"
          },
          "cancelled": {
            "type": "boolean"
          },
          "postponed": {
            "type": "boolean"
          },
          "sale_status": {
            "$ref": "#/components/schemas/EventSaleStatus"
          },
          "venue_point": {
            "type": "object",
            "nullable": true,
            "description": "Where the venue is, for a map pin (#2495). Null for an online event, a venue to be announced, or an address shown to ticket holders only.",
            "properties": {
              "lat": {
                "type": "number"
              },
              "lng": {
                "type": "number"
              }
            }
          }
        }
      },
      "EventList": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventListRow"
            }
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          },
          "total": {
            "type": "integer",
            "nullable": true,
            "description": "How many rows the filters match in all, on the first page (#2495); null on the pages after."
          }
        }
      },
      "EventOrderTicket": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "code": {
            "type": "string",
            "description": "The ticket (QR payload). Only to the buyer and the hosts."
          },
          "ticket_type": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "event_day_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "group_id": {
            "type": "string",
            "format": "uuid",
            "description": "Seats of one table share it."
          },
          "price_cents": {
            "type": "integer"
          },
          "goods_value_cents": {
            "type": "integer"
          },
          "guest_name": {
            "type": "string",
            "nullable": true
          },
          "guest_email": {
            "type": "string",
            "nullable": true
          },
          "is_buyer": {
            "type": "boolean"
          },
          "dietary": {
            "type": "string",
            "nullable": true
          },
          "dietary_note": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "held",
              "active",
              "cancelled",
              "refunded"
            ]
          },
          "check_ins": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "event_day_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "checked_in_at": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          }
        }
      },
      "EventOrder": {
        "type": "object",
        "description": "An order: its seats, its money (recomputed on the server every time), the shares it is split by, and what the buyer may do with it.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "number": {
            "type": "integer",
            "description": "Shown as #1042."
          },
          "status": {
            "type": "string",
            "enum": [
              "held",
              "requested",
              "paid",
              "confirmed",
              "expired",
              "declined",
              "cancelled",
              "refunded",
              "partially_refunded",
              "disputed"
            ]
          },
          "event": {
            "type": "object",
            "additionalProperties": true
          },
          "event_day_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "buyer": {
            "type": "object",
            "properties": {
              "profile_id": {
                "type": "string",
                "nullable": true
              },
              "name": {
                "type": "string",
                "nullable": true
              },
              "email": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "language": {
            "type": "string"
          },
          "hold_expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "approval_required": {
            "type": "boolean"
          },
          "show_attending": {
            "type": "boolean"
          },
          "added_by": {
            "type": "string",
            "nullable": true,
            "enum": [
              "comp",
              "paid_outside",
              "payment_link",
              null
            ]
          },
          "totals": {
            "type": "object",
            "properties": {
              "tickets_cents": {
                "type": "integer"
              },
              "goods_value_cents": {
                "type": "integer"
              },
              "gift_cents": {
                "type": "integer"
              },
              "fee_cents": {
                "type": "integer"
              },
              "total_cents": {
                "type": "integer"
              },
              "refunded_cents": {
                "type": "integer"
              },
              "cover_fee": {
                "type": "boolean"
              }
            }
          },
          "tickets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventOrderTicket"
            }
          },
          "fundraisers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "title": {
                  "type": "string"
                },
                "slug": {
                  "type": "string"
                },
                "share_percent": {
                  "type": "integer"
                }
              }
            }
          },
          "refund_request": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true
          },
          "actions": {
            "type": "object",
            "properties": {
              "pay": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows, when not allowed."
                  }
                }
              },
              "cancel": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows, when not allowed."
                  }
                }
              },
              "withdraw_request": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows, when not allowed."
                  }
                }
              },
              "request_refund": {
                "type": "object",
                "required": [
                  "allowed"
                ],
                "properties": {
                  "allowed": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string",
                    "description": "The i18n key the page shows, when not allowed."
                  }
                }
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "paid_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "cancelled_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "EventReceipt": {
        "type": "object",
        "description": "One receipt per order: each Fundly and its amount, the value of the dinner, the deductible amount (price minus value, plus the whole gift) and whether the IRS quid pro quo disclosure applies (over $75 with goods). A personal Fundly's gift is not tax-deductible; a non-profit's or church's carries its tax details.",
        "properties": {
          "order_id": {
            "type": "string",
            "format": "uuid"
          },
          "order_number": {
            "type": "integer"
          },
          "paid_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "lines": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "ticket_type": {
                  "type": "string"
                },
                "seats": {
                  "type": "integer"
                },
                "amount_cents": {
                  "type": "integer"
                }
              }
            }
          },
          "tickets_cents": {
            "type": "integer"
          },
          "gift_cents": {
            "type": "integer"
          },
          "covered_fee_cents": {
            "type": "integer"
          },
          "total_cents": {
            "type": "integer"
          },
          "refunded_cents": {
            "type": "integer"
          },
          "goods_value_cents": {
            "type": "integer"
          },
          "deductible_cents": {
            "type": "integer"
          },
          "disclosure": {
            "type": "boolean"
          },
          "fundraisers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "title": {
                  "type": "string"
                },
                "amount_cents": {
                  "type": "integer"
                },
                "goods_value_cents": {
                  "type": "integer"
                },
                "deductible_cents": {
                  "type": "integer"
                },
                "tax_deductible": {
                  "type": "boolean"
                },
                "organization": {
                  "type": "object",
                  "nullable": true,
                  "properties": {
                    "legal_name": {
                      "type": "string"
                    },
                    "ein": {
                      "type": "string"
                    },
                    "tax_status": {
                      "type": "string",
                      "nullable": true
                    },
                    "address": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "EventTicketPage": {
        "type": "object",
        "description": "A ticket, for whoever holds its code: the event (with the full address and an online link, which only ticket holders get), the other seats of the order (their codes only on the buyer's own ticket), and Wallet, calendar, directions and \"Bring a friend\" links.",
        "properties": {
          "ticket": {
            "type": "object",
            "additionalProperties": true
          },
          "event": {
            "type": "object",
            "additionalProperties": true
          },
          "order": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "number": {
                "type": "integer"
              },
              "status": {
                "type": "string"
              },
              "buyer_name": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "others": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "links": {
            "type": "object",
            "properties": {
              "wallet": {
                "type": "string",
                "nullable": true
              },
              "calendar": {
                "type": "string",
                "nullable": true
              },
              "directions": {
                "type": "string",
                "nullable": true
              },
              "bring_a_friend": {
                "type": "string",
                "nullable": true
              },
              "ticket": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "actions": {
            "type": "object",
            "description": "On the buyer's own ticket: what they may do with the order.",
            "additionalProperties": {
              "type": "object",
              "required": [
                "allowed"
              ],
              "properties": {
                "allowed": {
                  "type": "boolean"
                },
                "reason": {
                  "type": "string",
                  "description": "The i18n key the page shows, when not allowed."
                }
              }
            }
          }
        }
      },
      "EventWaitlistEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "ticket_type_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "event_day_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "quantity": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "waiting",
              "offered",
              "claimed",
              "expired",
              "removed"
            ]
          },
          "offer_expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "claimed_order_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "EventPeople": {
        "type": "object",
        "properties": {
          "counts": {
            "type": "object",
            "properties": {
              "going": {
                "type": "integer"
              },
              "members": {
                "type": "integer"
              },
              "guests": {
                "type": "integer"
              },
              "checked_in": {
                "type": "integer"
              },
              "requests": {
                "type": "integer"
              },
              "refund_requests": {
                "type": "integer"
              },
              "waitlist": {
                "type": "integer"
              },
              "revenue_cents": {
                "type": "integer"
              }
            }
          },
          "orders": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "waitlist": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "EventCheckInList": {
        "type": "object",
        "description": "The day's guest list with codes, for the door phone to keep and scan offline.",
        "properties": {
          "event": {
            "type": "object",
            "additionalProperties": true
          },
          "day": {
            "type": "object",
            "additionalProperties": true
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "valid_until": {
            "type": "string",
            "format": "date-time"
          },
          "counts": {
            "type": "object",
            "properties": {
              "tickets": {
                "type": "integer"
              },
              "checked_in": {
                "type": "integer"
              }
            }
          },
          "tickets": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "EventCheckInResults": {
        "type": "object",
        "properties": {
          "day_id": {
            "type": "string",
            "format": "uuid"
          },
          "checked_in": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string"
                },
                "ticket_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "result": {
                  "type": "string",
                  "enum": [
                    "checked_in",
                    "already_checked_in",
                    "undone",
                    "not_checked_in",
                    "not_found",
                    "not_valid",
                    "wrong_day"
                  ]
                },
                "checked_in_at": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Authentication required",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Permission denied",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "SessionCredentialRequired": {
        "description": "The request was authenticated with an API key, or made while an administrator is viewing the account as its owner. Managing API keys requires the owner's own signed-in session.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                },
                "code": {
                  "type": "string",
                  "enum": [
                    "SESSION_CREDENTIAL_REQUIRED",
                    "IMPERSONATION_RESTRICTED_ACTION"
                  ]
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded. Which bucket applies depends on the endpoint — see **Rate limits** in the API description.",
        "headers": {
          "RateLimit-Limit": {
            "description": "Requests allowed in the current window.",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Remaining": {
            "description": "Requests left in the current window.",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Reset": {
            "description": "Seconds until the window resets.",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Policy": {
            "description": "The policy in force, e.g. `300;w=60`.",
            "schema": {
              "type": "string"
            }
          },
          "Retry-After": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                },
                "retryAfter": {
                  "type": "integer",
                  "description": "Seconds until the window resets. Present on the shared limiters."
                }
              }
            }
          }
        }
      },
      "BadRequest": {
        "description": "Invalid or missing request parameters",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "WalletUnavailable": {
        "description": "Apple Wallet passes are not configured on this server (`code: wallet_unavailable`). `GET /wallet/status` says the same as `available: false`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WalletError"
            }
          }
        }
      }
    },
    "parameters": {
      "PassKitDeviceLibraryIdentifier": {
        "name": "deviceLibraryIdentifier",
        "in": "path",
        "required": true,
        "description": "Wallet's identifier for the device.",
        "schema": {
          "type": "string"
        }
      },
      "PassKitPassTypeIdentifier": {
        "name": "passTypeIdentifier",
        "in": "path",
        "required": true,
        "description": "The pass's Pass Type ID.",
        "schema": {
          "type": "string"
        }
      },
      "PassKitSerialNumber": {
        "name": "serialNumber",
        "in": "path",
        "required": true,
        "description": "The pass's serial number.",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "EventHostAs": {
        "name": "as",
        "in": "query",
        "required": false,
        "description": "One identity the caller acts for, as `<kind>:<uuid>` (kind `member`, `organization`, `community` or `sponsor`), to list only what that identity hosts or is invited to (#2494). One the caller does not act for lists nothing.",
        "schema": {
          "type": "string",
          "pattern": "^(member|organization|community|sponsor):[0-9a-fA-F-]{36}$",
          "example": "organization:44444444-4444-4444-8444-444444444444"
        }
      }
    }
  },
  "paths": {
    "/me/sponsor-menu": {
      "get": {
        "tags": [
          "Sponsors"
        ],
        "operationId": "getSponsorMenu",
        "summary": "The menus' sponsor entries",
        "description": "What the header, the account menu and the footer show about sponsors. `403` means sponsors are switched off and the menus show no sponsor entries. For a signed-in person: the businesses they are on the team of (each linked to its workspace) and whether they use the counter. Answers a visitor who is not signed in too, with both empty, so the Community menu and the footer know sponsors are on. Never cached (`Cache-Control: private, no-store`).",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorMenu"
                },
                "example": {
                  "businesses": [
                    {
                      "id": "6a1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
                      "slug": "fast-cat-coffee-bar",
                      "name": "Fast Cat Coffee Bar",
                      "role": "owner",
                      "status": "live",
                      "logo_url": null
                    }
                  ],
                  "counter": true
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/sponsors/{key}/badge": {
      "get": {
        "tags": [
          "Sponsors"
        ],
        "operationId": "getSponsorBadge",
        "summary": "What the web badge shows",
        "description": "The answer the Proud Sponsor web badge is drawn from. The badge itself is the image at `https://fundlyhub.org/badge/sponsor/{slug}.svg` (`?theme=dark` for the white version on a dark page, `?size=small` for 160 by 38, `?size=round` for the 48 by 48 round mark), which always shows the sponsor's live status. `{key}` takes the current slug, an old one or the id, so a badge keeps working after a rename. Cacheable for 5 minutes. `403` while sponsors are switched off.",
        "security": [],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "fast-cat-coffee-bar"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorBadge"
                },
                "examples": {
                  "live": {
                    "value": {
                      "badge": "proud_sponsor",
                      "slug": "fast-cat-coffee-bar",
                      "name": "Fast Cat Coffee Bar"
                    }
                  },
                  "ended": {
                    "value": {
                      "badge": "plain"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/me/person-beneficiaries": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Find a FundlyHub person beneficiary",
        "operationId": "searchPersonBeneficiaries",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Search active public profiles by name or handle, or use a complete exact email address. Only public profiles are ever returned, and an email matches only a public profile's verified login email; private profiles, private contact emails, unverified addresses and partial emails return no results, so the caller invites the address instead. Returns only public identity fields, never email/contact data. Private no-store response; the authenticated rate limiter applies, and a complete-email query also spends the per-account email-lookup budget (30 a minute, shared with the organization member lookup).",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 254
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Up to ten matching public identities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "avatar": {
                            "type": "string",
                            "nullable": true
                          },
                          "profile_slug": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/me/beneficiary-invitations": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "List beneficiary invitations for the signed-in recipient",
        "operationId": "listPersonBeneficiaryInvitations",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Returns at most 100 pending invitations matching this active account's verified primary or private contact email, excluding deleted campaigns and accounts pending deletion. Includes the shared public campaign-card projection (cover, organizer identity and fundraising state), and paid held gift net after fees, refunds and chargebacks; never includes the invited email. No-store response. Acceptance remains explicit, including for an already registered account.",
        "responses": {
          "200": {
            "description": "Pending invitations and their held amounts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "fundraiser_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "slug": {
                            "type": "string"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "held_cents": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "campaign": {
                            "type": "object",
                            "description": "Shared public campaign-card fields, including cover_image, profiles and fundraising; no private beneficiary contacts or organizer email.",
                            "additionalProperties": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/beneficiary-invitations/{id}/accept": {
      "post": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Accept a verified-email beneficiary invitation",
        "operationId": "acceptPersonBeneficiaryInvitation",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "The invitation ID is a routing identifier, never a credential. The authenticated active account must verify its matching email. Atomically resolves the campaign, donation recipient snapshots and held ledger entries to this same person, retaining refund history. Idempotent for the same claimant. Does not transfer money to Stripe or a bank; the existing Connect onboarding and settlement checks still apply. Strict rate limiter and no-store response.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Accepted, or already accepted by this recipient",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "fundraiser_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "accepted": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Wrong",
            "unverified or inactive account": null
          },
          "404": {
            "description": "Unknown invitation"
          },
          "409": {
            "description": "Revoked or conflicting campaign recipient"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/beneficiaries/{invitationId}": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Get the public page of a beneficiary who has not joined",
        "operationId": "getBeneficiaryPage",
        "description": "Public, no session (#2485). For a pending person beneficiary invitation: the invited name and the public card of the Fundly raising for them, while that Fundly can be opened by its link. The answer is the same whether or not an account holds the invited address, and never carries the email. Once the invitation is accepted it answers `200` with `redirect_to`, the beneficiary's profile path, which the web page serves as a permanent redirect. A revoked or unknown invitation, one whose account is gone, and a pending one on a draft, private or deleted Fundly answer `404`.",
        "security": [],
        "parameters": [
          {
            "name": "invitationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The page, or where it moved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "oneOf": [
                        {
                          "type": "object",
                          "required": [
                            "name",
                            "fundlies"
                          ],
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "fundlies": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "description": "Shared public campaign-card fields (the listing's projection).",
                                "additionalProperties": true
                              }
                            }
                          }
                        },
                        {
                          "type": "object",
                          "required": [
                            "redirect_to"
                          ],
                          "properties": {
                            "redirect_to": {
                              "type": "string",
                              "description": "The profile path, `/@{handle}` (or `/@{id}` without one).",
                              "example": "/@ann-lee"
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{id}/beneficiary-invitation/resend": {
      "post": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Resend a pending beneficiary invitation",
        "operationId": "resendPersonBeneficiaryInvitation",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Organizer-only, with verified sender email. Queues the same invitation through the email service; no identity change. At most once per minute per invitation, with the strict request limiter. Suppressed delivery returns sent false.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Queue result and masked recipient hint",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "email_hint": {
                          "type": "string"
                        },
                        "sent": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Organizer-only or sender email unverified"
          },
          "404": {
            "description": "No pending invitation"
          },
          "409": {
            "description": "Wait one minute before resending"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/cognito/signup": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Register a new user",
        "operationId": "registerUser",
        "description": "Create a new account via AWS Cognito. The account is confirmed immediately and a verification link is mailed to the address; the email stays unverified until that link is followed (see `GET /cognito/verify-email`), and several write endpoints refuse an unverified account. Gated by the `features.user_registration` flag — when the flag is off the endpoint answers `403`. Rate limited to 10 requests per minute per IP. When the risk engine flags the caller (repeated sign-ups from one IP), a reCAPTCHA token must be sent as `captchaToken`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "user@example.com"
                  },
                  "password": {
                    "type": "string",
                    "format": "password",
                    "example": "SecureP@ssw0rd!"
                  },
                  "name": {
                    "type": "string",
                    "description": "Display name. Optional; when it is omitted or blank the account has no name until the person sets one (`name` is then `null`).",
                    "example": "John Doe"
                  },
                  "captchaToken": {
                    "type": "string",
                    "description": "reCAPTCHA v3 token. Required only after a `429` with `requiresCaptcha`."
                  },
                  "ambassadorInviteToken": {
                    "type": "string",
                    "description": "An ambassador invitation token. Redeemed against the address the account is created with; a token that does not match is ignored and never fails the sign-up."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Account created; verification email sent.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "userSub": {
                      "type": "string",
                      "description": "The Cognito user id."
                    },
                    "userConfirmed": {
                      "type": "boolean",
                      "description": "False only if the automatic Cognito confirmation failed; the account then needs `POST /cognito/confirm`."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing email or password, a disposable or malformed address, or a password that fails the policy.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Registration is disabled (`features.user_registration` is off), or the reCAPTCHA token failed (`captchaFailed: true`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "An account with this email already exists (`code: EMAIL_ALREADY_REGISTERED`). Existing users sign in or reset their password instead.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited, or the risk engine wants a CAPTCHA first — the body then carries `requiresCaptcha: true`; retry with `captchaToken`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "requiresCaptcha": {
                      "type": "boolean"
                    },
                    "reason": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/cognito/confirm": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Confirm registration",
        "operationId": "confirmRegistration",
        "description": "Confirm a Cognito account with a verification code. Sign-up already confirms the account itself, so this is needed only when `POST /cognito/signup` answered `userConfirmed: false`. It does not mark the email verified — that is the link sent by sign-up.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "code"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "code": {
                    "type": "string",
                    "example": "123456"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account confirmed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing fields, or an invalid or expired code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/cognito/signin": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Sign in",
        "operationId": "signIn",
        "description": "Authenticate with email and password. **Tokens are not returned in the body**: the session is set as httpOnly cookies (`access_token`, `id_token`, `refresh_token`) that the browser sends on every later request. Scripts and server-to-server integrations should use an API key instead (see **Authentication**). When the risk engine flags repeated failures, a reCAPTCHA token must be sent as `captchaToken`. If Cognito asks for a further challenge, the body carries `challengeRequired: true`, `challengeName` and `session` and no cookies are set.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "user@example.com"
                  },
                  "password": {
                    "type": "string",
                    "format": "password"
                  },
                  "captchaToken": {
                    "type": "string",
                    "description": "reCAPTCHA v3 token. Required only after a `429` with `requiresCaptcha`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authentication successful; session cookies set.",
            "headers": {
              "Set-Cookie": {
                "description": "`access_token`, `id_token` and `refresh_token`, all httpOnly.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Signin successful"
                    },
                    "user": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "email": {
                          "type": "string",
                          "format": "email"
                        },
                        "name": {
                          "type": "string",
                          "nullable": true
                        },
                        "avatar": {
                          "type": "string",
                          "nullable": true
                        },
                        "role": {
                          "type": "string",
                          "nullable": true
                        },
                        "email_verified": {
                          "type": "boolean"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "profile_slug": {
                          "type": "string",
                          "nullable": true
                        },
                        "deletion_scheduled_for": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true,
                          "description": "When the account is scheduled to be deleted, while a deletion is pending; `null` otherwise."
                        }
                      }
                    },
                    "expiresIn": {
                      "type": "integer",
                      "description": "Access-token lifetime in seconds."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Email or password missing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The Cognito account is not confirmed, a password reset is required, or the reCAPTCHA token failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited, or the risk engine wants a CAPTCHA first — the body then carries `requiresCaptcha: true`; retry with `captchaToken`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "requiresCaptcha": {
                      "type": "boolean"
                    },
                    "reason": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/cognito/refresh": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Refresh tokens",
        "operationId": "refreshTokens",
        "description": "Exchange the `refresh_token` **cookie** for new access and ID token cookies. There is no request body — a refresh token sent in JSON is ignored.",
        "responses": {
          "200": {
            "description": "Tokens refreshed; new `access_token` and `id_token` cookies set.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "expiresIn": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No refresh-token cookie, or Cognito rejected it (the session cookies are cleared).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Cognito was unreachable; the cookies are kept so the client can retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/cognito/logout": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Sign out",
        "operationId": "signOut",
        "description": "Revoke the session's Cognito tokens (global sign-out) and clear the session cookies. Always answers `200`, even without a session.",
        "responses": {
          "200": {
            "description": "Logged out",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/cognito/me": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Get current user",
        "operationId": "getCurrentUser",
        "description": "The signed-in user's profile. **Cookie session only** — this endpoint does not accept an `Authorization` header or an API key. When the short-lived session has expired but the refresh cookie is still valid, it renews the session transparently and sets new cookies. While FundlyHub support is viewing the account on the user's behalf it returns that user with `is_impersonating: true` and `impersonated_by`.",
        "responses": {
          "200": {
            "description": "Current user info",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "email": {
                          "type": "string",
                          "format": "email"
                        },
                        "name": {
                          "type": "string",
                          "nullable": true
                        },
                        "avatar": {
                          "type": "string",
                          "nullable": true
                        },
                        "role": {
                          "type": "string",
                          "nullable": true
                        },
                        "email_verified": {
                          "type": "boolean"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "profile_slug": {
                          "type": "string",
                          "nullable": true
                        },
                        "auth_provider": {
                          "type": "string",
                          "description": "How the account signs in, e.g. `email`, `google`, `apple`."
                        },
                        "needs_name_update": {
                          "type": "boolean",
                          "description": "True when the account has no name of its own yet: `name` is `null`, or still an automatic placeholder such as `Apple User 1234`."
                        },
                        "deletion_scheduled_for": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true,
                          "description": "When the account is scheduled to be deleted, while a deletion requested with `POST /users/me/deletion-request` is pending; `null` otherwise. Show it with a way to cancel."
                        },
                        "is_impersonating": {
                          "type": "boolean",
                          "description": "Present only while FundlyHub support is viewing the account."
                        },
                        "impersonated_by": {
                          "type": "string",
                          "format": "uuid",
                          "description": "The support agent's profile id. Present only with `is_impersonating`."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/cognito/forgot-password": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Request password reset",
        "operationId": "forgotPassword",
        "description": "Send a password reset code, preferring the account's verified private contact email. The verified contact or sign-in email can identify the account. With no verified private contact, or where that path cannot serve the account (no usable sign-in identity yet, or an address shared by two accounts), existing Cognito recovery sends the code instead. Answers `200` whether or not an account or deliverable destination exists; it reveals neither account existence nor a private address.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reset code sent, if the account exists",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Email missing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/cognito/reset-password": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Reset password",
        "operationId": "resetPassword",
        "description": "Set a new password using a reset code. Account-bound application codes contain eight digits, expire after 10 minutes and allow five attempts; they are consumed once, before changing the same Cognito identity's password. Existing Cognito codes remain supported. Recovery never changes email addresses or their verified flags. A federated account retains Apple/Google sign-in when it gains a password option.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "code",
                  "newPassword"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "code": {
                    "type": "string"
                  },
                  "newPassword": {
                    "type": "string",
                    "format": "password"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Password reset",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing fields, an invalid or expired code, or a password that fails the policy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/cognito/oauth/{provider}": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Initiate OAuth login",
        "operationId": "initiateOAuth",
        "description": "Redirect to the Cognito Hosted UI for a third-party provider. After the provider signs the user in, `GET /cognito/oauth/callback` sets the session cookies and redirects to `redirect` on the FundlyHub site.\n\nOpen this URL in the browser that will be signed in, by navigating to it rather than fetching it. The response sets a short-lived httpOnly cookie that the callback requires. A sign-in completed in a different browser, after about ten minutes, or after a newer sign-in was started in the same browser is refused, and the browser is sent to `/auth?error=state_mismatch` with no session set; starting again fixes it.",
        "parameters": [
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "google",
                "apple"
              ]
            }
          },
          {
            "name": "redirect",
            "in": "query",
            "required": false,
            "description": "The path on the FundlyHub site to send the browser to after sign-in, such as `/campaigns/help-food-bank?tab=updates`. It must start with a single `/`; a full URL on the FundlyHub site is reduced to its path. Any other value, such as a URL on another host or a protocol-relative `//host`, is replaced by `/`. Defaults to `/`.",
            "schema": {
              "type": "string",
              "maxLength": 2048,
              "example": "/campaigns/help-food-bank"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to the OAuth provider. Sets the short-lived sign-in cookie that the callback checks.",
            "headers": {
              "Location": {
                "description": "The Cognito Hosted UI's `/oauth2/authorize` URL for this provider, which sends the browser on to Google or Apple.",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "Set-Cookie": {
                "description": "`oauth_flow` (httpOnly, ten minutes), which the callback reads once and clears.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Unsupported provider",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The sign-in could not be started (`error: Failed to initiate OAuth`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "List fundraisers",
        "operationId": "listFundraisers",
        "description": "A paginated list of public campaigns, newest first. No authentication; the result is the same whoever asks. Only published campaigns (`active` or `ended`) with `visibility: public` are listed — drafts, campaigns awaiting review, `paused`, `rejected`, `unlisted` and `private` campaigns never appear here, whatever is asked for — and deleted campaigns are excluded. Each item is a campaign card (`FundraiserCard`); fetch the detail read for the full campaign. Card text is translated into the reader's language (`lang`, then the language cookie, then `Accept-Language`) where a translation exists.\n\n**Near a point.** With `near=<lat>,<lng>` the list holds only the campaigns whose city is within `radius_mi` miles (default 20) of that point, nearest first and then most raised, and each item carries `distance_mi`. Every other filter still applies, and so do the public-only rules above. A campaign's point is its CITY's centroid, geocoded on the server from the free-text `location`; a campaign whose location has no city-level point yet is not in a `near` list. For the cities to offer a picker, read `GET /fundraisers/cities`.\n\nOnly the parameters below are accepted. Any other query parameter is ignored.",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "description": "`active`: live campaigns only, active and not past their end date (#2061). `closed`: ended campaigns plus live ones past their end date, whether or not they still take donations. `ended`: the same as `closed`. `all`: both (the default). `active` and `closed` never overlap. Any other value answers `400` with `{ \"error\": \"Invalid status\", \"allowed\": [...] }`.",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "closed",
                "ended",
                "all"
              ],
              "default": "all"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by category — its id, slug or name all match."
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Free-text search over title, summary, story, category and location — the same match `GET /search?scope=campaigns` uses. Matches are ranked first."
          },
          {
            "name": "is_project",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "`true` for projects only, `false` for fundraisers only; omit for both."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "raised"
              ]
            },
            "description": "`raised` sorts by most raised first. Omit for newest first."
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            },
            "description": "Language to translate card text into."
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size, 1–100. A larger value is treated as `100`; a missing, zero, negative or non-numeric value as `20`.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of campaigns to skip, `0` or more. A negative or non-numeric value is treated as `0`.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "near",
            "in": "query",
            "description": "`<lat>,<lng>` in decimal degrees, e.g. `38.5816,-121.4944`: latitude −90..90, longitude −180..180. Lists only the campaigns whose city is within `radius_mi` of the point (a campaign's point is its city's centroid; one in no city is never listed), nearest first, then most raised (this order replaces `sort` and the search rank), each with `distance_mi`. Anything that is not two numbers in range — including an empty value or the parameter sent twice — answers `400 { \"error\": \"invalid_near\" }`.",
            "schema": {
              "type": "string",
              "pattern": "^\\s*[+-]?(\\d+(\\.\\d*)?|\\.\\d+)\\s*,\\s*[+-]?(\\d+(\\.\\d*)?|\\.\\d+)\\s*$"
            },
            "example": "38.5816,-121.4944"
          },
          {
            "name": "radius_mi",
            "in": "query",
            "description": "Radius in miles around `near`, 1–100, default 20. A larger value is treated as `100`, a smaller one as `1`, and a non-numeric one as `20`. Ignored without `near`.",
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of campaign cards",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FundraiserCard"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "description": "The page size applied."
                        },
                        "offset": {
                          "type": "integer",
                          "description": "The offset applied."
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`status` is not one of `active`, `closed`, `ended` or `all` (`{ \"error\": \"Invalid status\", \"allowed\": [...] }`), or `near` is not a point (`{ \"error\": \"invalid_near\" }`).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "required": [
                        "error",
                        "allowed"
                      ],
                      "properties": {
                        "error": {
                          "type": "string",
                          "example": "Invalid status"
                        },
                        "allowed": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "example": [
                            "active",
                            "closed",
                            "ended",
                            "all"
                          ]
                        }
                      }
                    },
                    {
                      "type": "object",
                      "required": [
                        "error"
                      ],
                      "properties": {
                        "error": {
                          "type": "string",
                          "enum": [
                            "invalid_near"
                          ]
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "invalidStatus": {
                    "value": {
                      "error": "Invalid status",
                      "allowed": [
                        "active",
                        "closed",
                        "ended",
                        "all"
                      ]
                    }
                  },
                  "invalidNear": {
                    "value": {
                      "error": "invalid_near"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Create fundraiser",
        "operationId": "createFundraiser",
        "description": "Create a new fundraising campaign.\nSend `status: \"draft\"` to save a draft, which skips the publish gate. Any other status, **including an omitted one**, runs the publish gate (profile readiness, an image, reasonability and AI review), and a flagged campaign lands `pending` for review. Note that an omitted status that passes the gate is stored as `draft`, not `active`. Send `status: \"active\"` to publish.\nRequires a bearer session and is gated by the `features.fundraiser_creation` flag. Publishing requires a **verified email address**. A caller whose email is not yet verified may still create a **draft** (`status: \"draft\"` sent explicitly) and may hold at most 5 drafts. Past that the answer is `403` with code `UNVERIFIED_DRAFT_LIMIT`. Any other status from an unverified caller answers `403` with code `EMAIL_NOT_VERIFIED`. A failing gate answers `403`, not `401`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FundraiserCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Fundraiser created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Fundraiser"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Email not verified and the request is not a draft (`EMAIL_NOT_VERIFIED`), an unverified caller already holds 5 drafts (`UNVERIFIED_DRAFT_LIMIT`), campaign creation disabled, a publish blocker, or the caller is not a member of the organization named in the payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "A fundraiser with that slug already exists, or the organization named in `org_id` was approved with conditions this campaign breaks.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/featured": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "The home page's featured fundraisers",
        "operationId": "listFeaturedFundraisers",
        "description": "Eight live public campaigns for the home page, as two rows of four. Row one: the four that raised the most (more than nothing). Row two: the four approved in the last 7 days, newest first; with none that new, the newest launch. A row short of four is filled with the campaigns with the most recent activity: an update posted, a comment, a photo or video added, a gift, or a visit through an ambassador's referral link (not a bot's). A campaign appears once. Live means what `GET /fundraisers?status=active` lists. No authentication. The picks are cached for up to a minute.\n\nEach row is a campaign card as `GET /fundraisers` returns it, in pick order, in the reader's language (`lang`, then the language cookie, then `Accept-Language`), with three more fields.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Category slug, id or display name. Applied before selecting the eight featured campaigns.",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Up to eight campaigns, in pick order",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "maxItems": 8,
                      "items": {
                        "type": "object",
                        "description": "A campaign card, as in `GET /fundraisers`, and why it is featured.",
                        "properties": {
                          "featured_reason": {
                            "type": "string",
                            "enum": [
                              "top_raised",
                              "just_launched",
                              "recent_activity"
                            ]
                          },
                          "featured_activity": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "update",
                              "comment",
                              "photo",
                              "donation",
                              "referral_visit"
                            ],
                            "description": "The campaign's latest visible activity, whatever the reason; null when it has none."
                          },
                          "featured_activity_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "The picks could not be read."
          }
        }
      }
    },
    "/fundraisers/cities": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "List cities with active fundraisers",
        "operationId": "listFundraiserCities",
        "description": "Every city that has at least one active public campaign, for a \"near\" city picker: one row per city, with how many active public campaigns it has and a representative point to pass to `GET /fundraisers?near=<lat>,<lng>`. No authentication.\n\nActive means what `GET /fundraisers?status=active` lists: status `active`, end date not passed, `visibility: public`, not deleted. Each campaign counts in the city it is in (the US city its free-text `location` names, else the city a server-side geocode of it finds); campaigns in no city (not yet geocoded, not a place, or a whole state or country) are not counted, and neither are cities FundlyHub hid. `lat`/`lng` is the city's centroid, to 2 decimals: the point `near` measures every campaign in the city from. Sorted by `count`, most first, then by `label`. `label` is `\"City, REGION\"` in the US and `\"City, Country\"` elsewhere. Cached for up to 5 minutes.",
        "responses": {
          "200": {
            "description": "Cities with active public campaigns",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "label",
                          "city",
                          "region",
                          "country",
                          "lat",
                          "lng",
                          "count"
                        ],
                        "properties": {
                          "label": {
                            "type": "string",
                            "description": "`\"City, REGION\"` in the US, `\"City, Country\"` elsewhere.",
                            "example": "Sacramento, CA"
                          },
                          "city": {
                            "type": "string",
                            "example": "Sacramento"
                          },
                          "region": {
                            "type": "string",
                            "nullable": true,
                            "description": "State/province code where there is one, else its name.",
                            "example": "CA"
                          },
                          "country": {
                            "type": "string",
                            "nullable": true,
                            "description": "ISO 3166-1 alpha-2.",
                            "example": "US"
                          },
                          "lat": {
                            "type": "number",
                            "format": "double",
                            "example": 38.58
                          },
                          "lng": {
                            "type": "number",
                            "format": "double",
                            "example": -121.49
                          },
                          "count": {
                            "type": "integer",
                            "description": "Active public campaigns in this city.",
                            "example": 12
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "label": "Sacramento, CA",
                      "city": "Sacramento",
                      "region": "CA",
                      "country": "US",
                      "lat": 38.58,
                      "lng": -121.49,
                      "count": 12
                    },
                    {
                      "label": "Kyiv, Ukraine",
                      "city": "Kyiv",
                      "region": "Kyiv",
                      "country": "UA",
                      "lat": 50.45,
                      "lng": 30.52,
                      "count": 3
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{id}": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Get fundraiser",
        "operationId": "getFundraiser",
        "description": "Retrieve a single fundraiser by UUID — the stored row, without the joined owner and raised figures the slug read adds. Authentication is optional and widens what you can see: a campaign that is not `active`, `paused` or `ended`, is `private`, or has been deleted, is returned to its owner and answers `404` to everyone else. An `unlisted` campaign is readable with its link. The owner also gets `trustStatus` and the private fields they entered, such as `beneficiary_contact`; every other caller, signed in or not, gets the campaign without them.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Overlay the stored translation for this language, when one exists.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Fundraiser details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Fundraiser"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Update fundraiser",
        "operationId": "updateFundraiser",
        "description": "Update fundraiser details. Only the owner can update. Setting `status` is how a draft is published (`active`) or sent for review (`pending`). Publishing runs the same gate as creation — profile readiness, at least one image, reasonability and AI review — and a flagged campaign lands `pending`. A first publish (a draft that was never approved, #2488) follows create's rule: a reasonability or AI reject sends it to review rather than answering `403`. A campaign that has collected money cannot go back to `draft`. The owner may end only a live campaign (`status: ended`), and may not move an ended campaign to any other status: reopening is staff only (`409` with code `NOT_REOPENABLE`).\nThe caller's email must be verified, with one exception: an unverified caller may edit a campaign that is currently `draft`, as long as the body sends no `status` or sends `status: \"draft\"`. Moving a draft to any other status, or editing a campaign that is not a draft, answers `403` with code `EMAIL_NOT_VERIFIED`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FundraiserUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Fundraiser updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Fundraiser"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error (`details` lists the fields), no fields to update, or an attempt to unpublish (`status: draft`) a campaign that has collected money.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not the owner, `EMAIL_NOT_VERIFIED`, or a publish blocker — the body then carries `blockers`, e.g. `fundraiser_image_required`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "A status change the campaign cannot take: `NOT_ACTIVE` or `PAUSED` (only a live campaign can be ended), `NOT_REOPENABLE` (an ended campaign cannot be moved to another status by its owner); or `SLUG_TAKEN`, a `slug` another campaign holds or once held.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Delete fundraiser",
        "operationId": "deleteFundraiser",
        "description": "Soft-deletes a fundraiser (sets `deleted_at`). Only the owner may delete. A campaign that has collected funds cannot be deleted and answers `400`. Once deleted, `GET /fundraisers/{id}` and `GET /fundraisers/slug/{slug}` answer `404` to everyone but its owner.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Fundraiser soft-deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "campaignId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "slug": {
                      "type": "string",
                      "nullable": true
                    },
                    "deletedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The campaign has received donations and cannot be deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/fundraisers/slug/{slug}": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Get fundraiser by slug",
        "operationId": "getFundraiserBySlug",
        "description": "Retrieve a fundraiser using its URL-friendly slug, with the owner, category name, raised figures and share count joined in. An earlier slug of a published campaign (#2488) answers with the campaign under its current `slug`, which then differs from the one asked for. Authentication is optional and widens what you can see, exactly as on `GET /fundraisers/{id}`: unpublished, private and deleted campaigns, the private fields such as `beneficiary_contact`, and `trustStatus` are for the owner only.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Overlay the stored translation for this language, when one exists.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Fundraiser details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Fundraiser"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/check-slug/{slug}": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Check slug availability",
        "operationId": "checkSlugAvailability",
        "description": "Check if a fundraiser slug is available. Every campaign counts, including drafts and soft-deleted ones.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "exclude",
            "in": "query",
            "required": false,
            "description": "A campaign id to ignore — pass the campaign being edited so its own slug reads as available.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Availability status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "available": {
                      "type": "boolean"
                    },
                    "suggestion": {
                      "type": "string",
                      "description": "An unused variant of the slug (`<slug>-2`, `-3`, …). Only present when `available` is false."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Slug is shorter than 3 characters or contains anything other than lowercase alphanumerics and hyphens.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{id}/stats": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Get fundraiser statistics",
        "operationId": "getFundraiserStats",
        "description": "Aggregate totals for one campaign. Readable exactly when `GET /fundraisers/{id}` is: a campaign that is not `active`, `paused` or `ended`, is `private`, or has been deleted answers `404` to everyone but its owner. Authentication is optional.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Campaign statistics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "fundraiser_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "title": {
                          "type": "string"
                        },
                        "goal_amount_cents": {
                          "type": "integer",
                          "description": "Goal in cents."
                        },
                        "total_raised_cents": {
                          "type": "integer",
                          "description": "Net raised in cents."
                        },
                        "total_tips_cents": {
                          "type": "integer",
                          "description": "Tips in cents."
                        },
                        "donation_count": {
                          "type": "integer"
                        },
                        "donor_count": {
                          "type": "integer",
                          "description": "Unique donors."
                        },
                        "percentage_funded": {
                          "type": "number"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{id}/owner-stats": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Get the organizer's figures for a fundraiser",
        "operationId": "getFundraiserOwnerStats",
        "description": "The organizer panel's figures (#2485): raised (net of the card fee, as on the page), unique donors, page views and people reached by shared links. Page views count a visitor once per Fundly per UTC day, human traffic only, from the page's presence heartbeat (`POST /presence/fundraisers/{id}`). Shares is the share impact's `impressions` (`GET /fundraisers/{id}/share-impact`). The owner, an owner or admin of the Fundly's organization team, or staff; anyone else answers `403`. No-store response.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The organizer's figures",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "raised_cents",
                        "donors",
                        "views",
                        "shares"
                      ],
                      "properties": {
                        "raised_cents": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Raised in cents."
                        },
                        "donors": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Unique donors."
                        },
                        "views": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "All-time page views."
                        },
                        "shares": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Visits through shared links",
                          "bots excluded.": null
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/donations": {
      "post": {
        "tags": [
          "Donations"
        ],
        "summary": "Create donation",
        "operationId": "createDonation",
        "description": "Record a `pending` donation row against a fundraiser. The Stripe fee is computed server-side and the donor is the session's account.\nRequires a bearer session **and a verified email address**, is gated by the `features.donations` flag, and is protected by reCAPTCHA v3 (action `donation`) — send the token as `recaptcha_token` in the body or in the `x-recaptcha-token` header. Because this route already requires a verified email, a Cognito session may omit the token; an API key or impersonation session without one answers `400`. A token that is sent is always verified: below the score threshold answers `403`.\nThis is the bookkeeping half of a gift. Money is moved by `POST /payments/create-intent` + `POST /payments/confirm`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "x-recaptcha-token",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "reCAPTCHA v3 token, action `donation`. Alternative to `recaptcha_token` in the body."
          },
          {
            "name": "x-app-attest-key-id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "iOS only. The App Attest key id (standard base64, as `DCAppAttestService.generateKey` returns it) of a key registered with `POST /app-attest/attest`. Send with `x-app-attest-assertion`."
          },
          {
            "name": "x-app-attest-assertion",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "iOS only. base64 of the assertion from `generateAssertion(keyId, clientDataHash: SHA256(raw request body))`. The body must carry a fresh `app_attest_challenge`. A valid assertion replaces the reCAPTCHA token; the headers alone never do. An invalid one answers `403` with `code` `APP_ATTEST_INVALID`, `APP_ATTEST_KEY_UNKNOWN` (attest a new key) or `APP_ATTEST_CHALLENGE_INVALID` (fetch a new challenge), unless the request passes reCAPTCHA some other way."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DonationCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Donation created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Donation"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error, or the reCAPTCHA token is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Email not verified, donations disabled (`features.donations` is off), reCAPTCHA rejected the request, or an App Attest assertion was invalid (`code` `APP_ATTEST_*`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{fundraiserId}/donation-map": {
      "get": {
        "tags": [
          "Donations"
        ],
        "summary": "Read fundraiser donation map",
        "operationId": "getFundraiserDonationMap",
        "description": "Latest 200 paid gifts, newest first, with the donor wall's ledger-derived net cents, moderated messages and canonical public profile routes. Anonymous and guest routes use opaque keys; email and internal identity IDs are never returned. Referral sources come only from recorded, non-self attributions whose sharer is public, active and named. Campaign readability and the owner/admin exception match the donor wall. Unknown or unreadable campaigns return empty data and total zero. Responses are private, no-store. Larger campaigns report has_more; the paginated donations endpoint remains the complete list.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "in": "path",
            "name": "fundraiserId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public map gifts and recorded referrals",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "maxItems": 200,
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "amount_cents": {
                            "type": "integer",
                            "description": "Ledger donation credit less processor fee"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "donor_name": {
                            "type": "string",
                            "nullable": true
                          },
                          "donor_avatar": {
                            "type": "string",
                            "nullable": true
                          },
                          "donor_href": {
                            "type": "string",
                            "nullable": true,
                            "description": "Canonical /@handle, /d/guest/key or /d/anon/key route"
                          },
                          "is_anonymous": {
                            "type": "boolean"
                          },
                          "anonymous_key": {
                            "type": "string",
                            "nullable": true
                          },
                          "comment": {
                            "type": "string",
                            "nullable": true
                          },
                          "via": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "avatar": {
                                "type": "string",
                                "nullable": true
                              },
                              "href": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer",
                          "enum": [
                            200
                          ]
                        },
                        "has_more": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid fundraiser UUID"
          },
          "429": {
            "description": "Too many requests"
          },
          "500": {
            "description": "Unable to load donations map"
          }
        }
      }
    },
    "/fundraisers/{fundraiserId}/donations": {
      "get": {
        "tags": [
          "Donations"
        ],
        "summary": "List donations for fundraiser",
        "operationId": "listFundraiserDonations",
        "description": "Public donor wall for one fundraiser: paid donations only, newest first, with a true total count. Donor email and payment identifiers are never returned, and anonymous gifts have their donor name and avatar stripped. Amounts are **net** (donation minus the Stripe fee) so the list agrees with the creator's balance.\nOnly a campaign anyone may open by link (live, ended or paused; not private; not deleted) has a public donor wall. For any other campaign the answer is an empty `data` array with `total: 0`, the same as for an unknown id, unless the caller is signed in as the campaign's owner or an admin.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "fundraiserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size, clamped to 1–200. A missing, zero, negative or non-numeric value means 20.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "A missing, negative or non-numeric value means 0.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of donations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Donation"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/donations/receipt/{receiptId}/nonprofit-monthly/cancel": {
      "post": {
        "operationId": "cancelNonprofitMonthlyGift",
        "summary": "Stop future nonprofit monthly gifts from a paid receipt",
        "description": "The opaque receipt ID or its Stripe PaymentIntent ID is the guest donor's capability. Stops the linked monthly subscription without refunding past gifts or changing the amount or beneficiary. Repeated cancellation is safe. Pending subscription creation is stopped too. A receipt for another product or a guessed identifier cannot cancel a nonprofit gift.",
        "security": [],
        "tags": [
          "Donations"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "receiptId",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 16,
              "maxLength": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Future monthly giving stopped",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "canceled": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No nonprofit monthly gift matches this receipt"
          },
          "422": {
            "description": "Invalid receipt"
          },
          "429": {
            "description": "Too many requests"
          }
        }
      }
    },
    "/donations/receipt/{receiptId}": {
      "get": {
        "tags": [
          "Donations"
        ],
        "summary": "Get donation by receipt ID",
        "operationId": "getDonationByReceipt",
        "description": "The donor's receipt. Public — the receipt id is the Stripe PaymentIntent (`pi_…`) or invoice (`in_…`) id, a capability token only the donor holds, so treat it as a secret: the response includes the donor's email and card details. Answers for a donation in any payment state, including `pending`. Responses are `Cache-Control: private, no-store`. `receipt_context` identifies the donation flow independently of a tax acknowledgment and is available while nonprofit settlement is pending. A reservation identity is never returned as `nonprofit_receipt`.",
        "parameters": [
          {
            "name": "receiptId",
            "in": "path",
            "required": true,
            "description": "The receipt id, or the donation's PaymentIntent id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Receipt details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "fundraiser_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true
                        },
                        "amount_cents": {
                          "type": "integer",
                          "description": "Gross donation in cents."
                        },
                        "net_amount_cents": {
                          "type": "integer"
                        },
                        "fee_amount_cents": {
                          "type": "integer"
                        },
                        "tip_amount_cents": {
                          "type": "integer"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "donor_name": {
                          "type": "string",
                          "nullable": true
                        },
                        "donor_email": {
                          "type": "string",
                          "nullable": true
                        },
                        "is_anonymous": {
                          "type": "boolean"
                        },
                        "payment_status": {
                          "type": "string",
                          "enum": [
                            "paid",
                            "refunded",
                            "failed",
                            "pending"
                          ]
                        },
                        "payment_method_type": {
                          "type": "string",
                          "nullable": true
                        },
                        "card_brand": {
                          "type": "string",
                          "nullable": true
                        },
                        "card_last4": {
                          "type": "string",
                          "nullable": true
                        },
                        "receipt_id": {
                          "type": "string",
                          "nullable": true
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "campaign_title": {
                          "type": "string",
                          "nullable": true
                        },
                        "campaign_slug": {
                          "type": "string",
                          "nullable": true
                        },
                        "beneficiary_name": {
                          "type": "string",
                          "nullable": true
                        },
                        "receipt_context": {
                          "$ref": "#/components/schemas/DonationReceiptContext"
                        },
                        "nonprofit_receipt": {
                          "type": "object",
                          "nullable": true,
                          "description": "Private immutable legal identity and original contribution snapshot; check nonprofit_receipt_adjustment for current validity. Platform tip is excluded from amount_cents.",
                          "additionalProperties": true
                        },
                        "nonprofit_receipt_adjustment": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "state": {
                              "type": "string",
                              "enum": [
                                "valid",
                                "partial_refund",
                                "refunded",
                                "disputed",
                                "void",
                                "review"
                              ]
                            },
                            "refunded_charge_cents": {
                              "type": "integer",
                              "minimum": 0,
                              "description": "Actual returned card amount including any refunded platform tip; not an allocation for tax purposes."
                            }
                          }
                        },
                        "nonprofit_monthly": {
                          "type": "object",
                          "nullable": true,
                          "description": "Current subscription or pending setup state; this receipt capability can stop future gifts. No provider customer or subscription IDs are exposed.",
                          "properties": {
                            "status": {
                              "type": "string",
                              "description": "Billing subscription status; `starting` while the first month is being set up, `canceled` once stopped, and `paused` (with a null next_payment_at) while the nonprofit cannot accept gifts, during which nothing is charged."
                            },
                            "cancel_at_period_end": {
                              "type": "boolean"
                            },
                            "next_payment_at": {
                              "type": "string",
                              "format": "date-time",
                              "nullable": true
                            }
                          }
                        },
                        "fundraiser": {
                          "type": "object",
                          "properties": {
                            "title": {
                              "type": "string",
                              "nullable": true
                            },
                            "slug": {
                              "type": "string",
                              "nullable": true
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/donations/receipt/email": {
      "post": {
        "tags": [
          "Donations"
        ],
        "summary": "Send donation receipt",
        "operationId": "sendDonationReceipt",
        "description": "Email the receipt for one donation.\n\nThe donation is named by `receipt_id` and nothing else — every figure\nin the email is read from that row, so the caller cannot dictate the\ncontents. `receipt_id` is the Stripe PaymentIntent id, which is not\nguessable.\n\n`recipient_email` is deliberately free-form, because \"send it to my\naccountant\" is the feature. What bounds it instead is a cap of **5\nsends per donation**, after which this returns `429` for that donation\npermanently.\n\nAuthentication is optional; the endpoint is rate limited.\n",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "receipt_id",
                  "recipient_email"
                ],
                "properties": {
                  "receipt_id": {
                    "type": "string",
                    "description": "The donation's receipt id. The donation's `payment_intent_id` is also accepted — the two have been written interchangeably over time.",
                    "example": "pi_3abc123def456"
                  },
                  "recipient_email": {
                    "type": "string",
                    "format": "email",
                    "description": "Lowercased before use. Need not be the original donor's address."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Receipt sent.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Receipt queued; it will be delivered shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "queued": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`receipt_id` or `recipient_email` missing, or the address is malformed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such receipt, or the donation was never paid — the two answer the same.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The nonprofit payment record is adjusted, disputed or under review; an unqualified charitable acknowledgment cannot be emailed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Either the shared rate limit (5 requests per minute per IP), or this donation has already been emailed the maximum of 5 times.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The email provider rejected the message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/categories": {
      "get": {
        "tags": [
          "Categories"
        ],
        "summary": "List categories",
        "operationId": "listCategories",
        "description": "Get all active fundraiser categories, ordered by `display_order`.",
        "responses": {
          "200": {
            "description": "List of categories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Category"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/categories/stats": {
      "get": {
        "tags": [
          "Categories"
        ],
        "summary": "Get all category statistics",
        "operationId": "getAllCategoryStats",
        "description": "Organization count, active-campaign count and funds raised for every active category, in `display_order`. Only public campaigns and approved or verified organizations are counted; funds raised are over the category's counted campaigns (approved, public, not deleted).",
        "responses": {
          "200": {
            "description": "Statistics for all categories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "category_name": {
                            "type": "string"
                          },
                          "category_slug": {
                            "type": "string"
                          },
                          "organization_count": {
                            "type": "integer"
                          },
                          "campaign_count": {
                            "type": "integer",
                            "description": "Public campaigns with status `active`."
                          },
                          "total_raised_cents": {
                            "type": "integer",
                            "description": "The sum of the category's counted campaigns' cards, in cents: what reached their creators (net of the Stripe fee, tips excluded), ended campaigns included."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/categories/{id}": {
      "get": {
        "tags": [
          "Categories"
        ],
        "summary": "Get category",
        "operationId": "getCategory",
        "description": "A single active category, addressed by its numeric id or its slug.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Category id (an integer) or slug.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Category details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Category"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/categories/{id}/stats": {
      "get": {
        "tags": [
          "Categories"
        ],
        "summary": "Get category statistics",
        "operationId": "getCategoryStats",
        "description": "Organization count, active-campaign count and funds raised for one category. Only public campaigns with status `active` and approved or verified organizations are counted.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Category id (an integer) or slug.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Category statistics with fundraiser counts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "category_name": {
                          "type": "string"
                        },
                        "organization_count": {
                          "type": "integer"
                        },
                        "fundraiser_count": {
                          "type": "integer"
                        },
                        "total_raised_cents": {
                          "type": "integer",
                          "description": "The sum of the category's counted campaigns' cards, in cents: what reached their creators (net of the Stripe fee, tips excluded), ended campaigns included. The same figure as the campaign-level total_raised_cents, summed."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/organizations": {
      "get": {
        "tags": [
          "Organizations"
        ],
        "summary": "List organizations",
        "operationId": "listOrganizations",
        "description": "Public list of approved/verified, non-deleted organizations. Returns their public fields plus a true total count. Rate-limited. Every organization is a non-profit now (`kind: nonprofit`); the non-profit directory with its cards and filters is `GET /nonprofits`.",
        "parameters": [
          {
            "name": "verification_status",
            "in": "query",
            "required": false,
            "description": "Only `approved` or `verified` take effect; other values fall back to the default public filter.",
            "schema": {
              "type": "string",
              "enum": [
                "approved",
                "verified"
              ]
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Clamped to 1..100. Defaults to 20.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of organizations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "legal_name": {
                            "type": "string"
                          },
                          "dba_name": {
                            "type": "string",
                            "nullable": true
                          },
                          "slug": {
                            "type": "string",
                            "nullable": true
                          },
                          "country": {
                            "type": "string",
                            "nullable": true
                          },
                          "address": {
                            "type": "string",
                            "nullable": true
                          },
                          "website": {
                            "type": "string",
                            "nullable": true
                          },
                          "logo": {
                            "type": "string",
                            "nullable": true
                          },
                          "banner_image": {
                            "type": "string",
                            "nullable": true
                          },
                          "description": {
                            "type": "string",
                            "nullable": true
                          },
                          "mission": {
                            "type": "string",
                            "nullable": true
                          },
                          "categories": {
                            "type": "array",
                            "nullable": true,
                            "items": {
                              "type": "string"
                            }
                          },
                          "social_links": {
                            "type": "object",
                            "nullable": true,
                            "additionalProperties": true
                          },
                          "founded_year": {
                            "type": "integer",
                            "nullable": true
                          },
                          "verification_status": {
                            "type": "string",
                            "enum": [
                              "approved",
                              "verified"
                            ]
                          },
                          "verification_completed_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "nonprofit"
                            ],
                            "description": "Every organization is a non-profit."
                          },
                          "parent_organization_id": {
                            "type": "string",
                            "format": "uuid",
                            "nullable": true
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updated_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Organizations"
        ],
        "summary": "Create organization",
        "operationId": "createOrganization",
        "deprecated": true,
        "description": "Retired: this creates nothing. A request that passes the checks below always answers `410`, pointing to `/nonprofits/new`; add a non-profit with `POST /nonprofits` instead. The request body below is the old multi-tier onboarding payload, kept for reference.\nRequires a bearer session **and a verified email address** — an unverified session answers `403`. Calls are capped at **5 per hour** per (IP, user).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "legal_name"
                ],
                "properties": {
                  "legal_name": {
                    "type": "string"
                  },
                  "ein": {
                    "type": "string",
                    "pattern": "^\\d{2}-\\d{7}$",
                    "example": "12-3456789"
                  },
                  "country": {
                    "type": "string"
                  },
                  "website": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "categories": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "company",
                      "conglomerate"
                    ],
                    "default": "company"
                  },
                  "parent_organization_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "A conglomerate the new company sits under."
                  },
                  "dbas": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "dba_name"
                      ],
                      "properties": {
                        "dba_name": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "locations": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "address"
                      ],
                      "properties": {
                        "label": {
                          "type": "string"
                        },
                        "address": {
                          "type": "object",
                          "description": "Free-form address fields, each a string (e.g. `line1`, `city`, `postal_code`).",
                          "additionalProperties": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Email verification required"
          },
          "410": {
            "description": "Always, once the session, verified-email and rate-limit checks pass: legacy company registration is retired. Use POST /nonprofits and its verification flow; `href` is the add flow's page on the site.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Organization registration has moved to nonprofit onboarding."
                    },
                    "href": {
                      "type": "string",
                      "example": "/nonprofits/new"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/organizations/me": {
      "get": {
        "tags": [
          "Organizations"
        ],
        "summary": "Get the caller's organizations",
        "operationId": "getMyOrganizations",
        "description": "Organizations the authenticated caller holds an active org-scoped role on. Flat array, no pagination.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Caller's organizations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "legal_name": {
                            "type": "string"
                          },
                          "dba_name": {
                            "type": "string",
                            "nullable": true
                          },
                          "slug": {
                            "type": "string",
                            "nullable": true
                          },
                          "country": {
                            "type": "string",
                            "nullable": true
                          },
                          "website": {
                            "type": "string",
                            "nullable": true
                          },
                          "logo": {
                            "type": "string",
                            "nullable": true
                          },
                          "description": {
                            "type": "string",
                            "nullable": true
                          },
                          "verification_status": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "nonprofit"
                            ],
                            "description": "Every organization is a non-profit."
                          },
                          "parent_organization_id": {
                            "type": "string",
                            "format": "uuid",
                            "nullable": true
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updated_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "role_name": {
                            "type": "string"
                          },
                          "role_display_name": {
                            "type": "string"
                          },
                          "role_hierarchy_level": {
                            "type": "integer"
                          },
                          "org_role_title_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "org_role_title_label": {
                            "type": "string",
                            "nullable": true
                          },
                          "org_role_title_category": {
                            "type": "string",
                            "nullable": true
                          },
                          "start_date": {
                            "type": "string",
                            "format": "date",
                            "nullable": true
                          },
                          "end_date": {
                            "type": "string",
                            "format": "date",
                            "nullable": true
                          },
                          "is_current": {
                            "type": "boolean"
                          },
                          "affiliation_description": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/organizations/{id}": {
      "get": {
        "tags": [
          "Organizations"
        ],
        "summary": "Get organization by ID or slug",
        "operationId": "getOrganization",
        "description": "Public read of a single org by UUID or slug. Anonymous callers only see approved/verified non-deleted orgs; an active member of the organization can also read it in its other states and additionally receives suspension/rejection metadata (`suspension_reason`, `rejected_reason`, `suspended_until`) and the unredacted `contact_email`. Authentication is therefore optional but not inert. Every organization is a non-profit now (`kind: nonprofit`), so `children`, which lists a conglomerate's companies, is always empty; the non-profit page itself is `GET /nonprofits/{slug}`.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Organization UUID or slug.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Organization detail",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "legal_name": {
                          "type": "string"
                        },
                        "dba_name": {
                          "type": "string",
                          "nullable": true
                        },
                        "slug": {
                          "type": "string",
                          "nullable": true
                        },
                        "country": {
                          "type": "string",
                          "nullable": true
                        },
                        "website": {
                          "type": "string",
                          "nullable": true
                        },
                        "logo": {
                          "type": "string",
                          "nullable": true
                        },
                        "banner_image": {
                          "type": "string",
                          "nullable": true
                        },
                        "description": {
                          "type": "string",
                          "nullable": true
                        },
                        "mission": {
                          "type": "string",
                          "nullable": true
                        },
                        "verification_status": {
                          "type": "string"
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "nonprofit"
                          ],
                          "description": "Every organization is a non-profit."
                        },
                        "parent_organization_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true
                        },
                        "address": {
                          "type": "string",
                          "nullable": true
                        },
                        "categories": {
                          "type": "array",
                          "nullable": true,
                          "items": {
                            "type": "string"
                          }
                        },
                        "social_links": {
                          "type": "object",
                          "nullable": true,
                          "additionalProperties": true
                        },
                        "founded_year": {
                          "type": "integer",
                          "nullable": true
                        },
                        "verification_completed_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "contact_email": {
                          "type": "string",
                          "nullable": true,
                          "description": "Null unless `contact_email_public` is true or the caller is a member."
                        },
                        "contact_email_public": {
                          "type": "boolean"
                        },
                        "suspension_reason": {
                          "type": "string",
                          "nullable": true,
                          "description": "Members only."
                        },
                        "rejected_reason": {
                          "type": "string",
                          "nullable": true,
                          "description": "Members only."
                        },
                        "suspended_until": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true,
                          "description": "Members only."
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "primary_location": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "label": {
                              "type": "string",
                              "nullable": true
                            },
                            "address": {
                              "type": "object",
                              "additionalProperties": true
                            },
                            "is_publicly_visible": {
                              "type": "boolean"
                            }
                          }
                        },
                        "dbas": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "dba_name": {
                                "type": "string"
                              },
                              "is_default": {
                                "type": "boolean"
                              }
                            }
                          }
                        },
                        "children": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "slug": {
                                "type": "string",
                                "nullable": true
                              },
                              "legal_name": {
                                "type": "string"
                              },
                              "logo": {
                                "type": "string",
                                "nullable": true
                              },
                              "verification_status": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/organizations/{id}/stats": {
      "get": {
        "tags": [
          "Organizations"
        ],
        "summary": "Get organization stats",
        "operationId": "getOrganizationStats",
        "description": "Campaign counts, funds raised, unique donors and followers for an org (UUID or slug). A bare object — not wrapped in `data`. Every figure but the followers is over the org's **counted campaigns**: approved, public, not deleted, and active, pending, paused or ended.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Organization stats",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "campaignCount": {
                      "type": "integer",
                      "description": "Counted campaigns with status `active`."
                    },
                    "totalCampaignCount": {
                      "type": "integer",
                      "description": "Counted campaigns."
                    },
                    "totalFundsRaisedCents": {
                      "type": "integer",
                      "description": "What reached the creators of the counted campaigns, in integer CENTS: each counted gift (paid or refunded) at its donation less the Stripe fee, never the tip. The sum of the org's campaign cards. Divide by 100 for dollars.",
                      "example": 45600000
                    },
                    "uniqueDonorCount": {
                      "type": "integer",
                      "description": "Distinct donors of those gifts: a signed-in donor by account, a guest by email (trimmed, case-insensitive), an anonymous donor by their anonymous identity."
                    },
                    "followerCount": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/organizations/{id}/members": {
      "get": {
        "tags": [
          "Organizations"
        ],
        "summary": "Get organization public team",
        "operationId": "getOrganizationMembers",
        "description": "Public \"Our team\" list for an org (UUID or slug). Filtered to active, publicly-visible, non-expired memberships whose user profile is not private.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Organization team members",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "user_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "profile_slug": {
                            "type": "string",
                            "nullable": true
                          },
                          "avatar": {
                            "type": "string",
                            "nullable": true
                          },
                          "kyc_verified_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "org_role_title_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "role_title_label": {
                            "type": "string",
                            "nullable": true,
                            "description": "The taxonomy label, or the custom title the admin typed."
                          },
                          "role_title_category": {
                            "type": "string",
                            "nullable": true
                          },
                          "role_title_sort_order": {
                            "type": "integer",
                            "nullable": true
                          },
                          "start_date": {
                            "type": "string",
                            "format": "date",
                            "nullable": true
                          },
                          "end_date": {
                            "type": "string",
                            "format": "date",
                            "nullable": true
                          },
                          "is_current": {
                            "type": "boolean"
                          },
                          "affiliation_description": {
                            "type": "string",
                            "nullable": true
                          },
                          "rbac_role_name": {
                            "type": "string"
                          },
                          "rbac_hierarchy_level": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/organizations/{id}/updates": {
      "get": {
        "tags": [
          "Organizations"
        ],
        "summary": "Get organization updates feed",
        "operationId": "getOrganizationUpdates",
        "description": "Public, latest-first updates feed for an org (UUID or slug). Offset pagination, limit clamped 1..50.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Organization updates",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "org_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "author_user_id": {
                            "type": "string",
                            "format": "uuid",
                            "nullable": true
                          },
                          "title": {
                            "type": "string"
                          },
                          "body": {
                            "type": "string"
                          },
                          "cover_image": {
                            "type": "string",
                            "nullable": true
                          },
                          "published_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updated_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "author_name": {
                            "type": "string",
                            "nullable": true
                          },
                          "author_profile_slug": {
                            "type": "string",
                            "nullable": true
                          },
                          "author_avatar": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/organizations/{id}/documents/public": {
      "get": {
        "tags": [
          "Organizations"
        ],
        "summary": "List public organization documents",
        "operationId": "getOrganizationPublicDocuments",
        "description": "Approved trust documents an organization admin has marked public, for an approved or verified org (UUID or slug). Metadata only — there is no public download.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public documents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "doc_type": {
                            "type": "string"
                          },
                          "original_filename": {
                            "type": "string"
                          },
                          "content_type": {
                            "type": "string"
                          },
                          "size_bytes": {
                            "type": "integer"
                          },
                          "reviewed_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/users/{id}": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Get user profile",
        "operationId": "getUserProfile",
        "description": "Public profile by UUID or profile_slug. Authentication is optional: the caller's own profile may include their email, and a profile marked private is redacted for every other viewer.\nWHAT SURVIVES THE REDACTION (#1696): `id`, `name`, `avatar`, `profile_slug`, `created_at` and the four counters — `campaign_count`, `total_funds_raised`, `follower_count` and `following_count` — with their REAL values. The leaderboard has always published a private person's rank and impact, so a profile reporting zeroes beside a board reporting real figures would be two surfaces disagreeing about one person rather than privacy.\nDropped: `bio`, `location`, `website`, `social_links`, `email`, `phone`, `private_contact_email`, `display_name`, `account_status`, `kyc_verified_at` and `account_kind`. The last three are more than a name — a Team chip and a verification tick say something about the person, which is exactly what a private profile withholds.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "User UUID or profile_slug.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User profile — a bare object, not wrapped in `data`. The fields marked *own profile only* are present only when the caller is the profile's owner.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "name": {
                      "type": "string",
                      "nullable": true,
                      "description": "The name the person gave, or `null` when they have not set one. Never derived from their email address; use `display_name` for a label that is always present."
                    },
                    "display_name": {
                      "type": "string",
                      "description": "What to call this person: their name, else `@` and their profile handle, else `FundlyHub member`. Never an email address."
                    },
                    "email": {
                      "type": "string",
                      "description": "*Own profile only.*"
                    },
                    "avatar": {
                      "type": "string",
                      "nullable": true
                    },
                    "bio": {
                      "type": "string",
                      "nullable": true
                    },
                    "location": {
                      "type": "string",
                      "nullable": true
                    },
                    "website": {
                      "type": "string",
                      "nullable": true
                    },
                    "social_links": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "profile_visibility": {
                      "type": "string",
                      "enum": [
                        "public",
                        "private"
                      ]
                    },
                    "profile_slug": {
                      "type": "string"
                    },
                    "account_status": {
                      "type": "string"
                    },
                    "role": {
                      "type": "string"
                    },
                    "campaign_count": {
                      "type": "integer"
                    },
                    "total_funds_raised": {
                      "type": "number",
                      "description": "Raised across the person's campaigns, in DOLLARS (a decimal) — the one profile counter not yet in cents."
                    },
                    "follower_count": {
                      "type": "integer"
                    },
                    "following_count": {
                      "type": "integer"
                    },
                    "phone": {
                      "type": "string",
                      "description": "*Own profile only.*"
                    },
                    "private_contact_email": {
                      "type": "string",
                      "description": "*Own profile only.*"
                    },
                    "private_contact_verified": {
                      "type": "boolean",
                      "description": "*Own profile only.*"
                    },
                    "kyc_verified_at": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "account_kind": {
                      "type": "string",
                      "description": "The badge the profile header shows (e.g. a Team or Ambassador chip), resolved server-side."
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Users"
        ],
        "summary": "Update user profile",
        "operationId": "updateProfile",
        "description": "Update your own profile. The fields below are the whole writable set;\nanything else in the body is ignored rather than rejected.\n\n`location` has been accepted since #1654 and was missing from this\nschema; `profile_visibility` is new in #1696.\n",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "profile_slug": {
                    "type": "string"
                  },
                  "social_links": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "location": {
                    "type": "string",
                    "description": "A city and a two-letter state, e.g. `Sacramento, CA`. Digits\nare refused: a ZIP or a street number does not belong on a\npublic profile. An empty string clears it.\n",
                    "example": "Sacramento, CA"
                  },
                  "profile_visibility": {
                    "type": "string",
                    "enum": [
                      "public",
                      "private"
                    ],
                    "description": "Who may see the detail of this profile.\n\nA `private` profile still publishes its avatar, its name and\nits four counters — campaigns, impact, followers, following.\nWhat it withholds is everything descriptive (bio, location,\nwebsite, social links) and everything the person has done:\ncampaigns, achievements, supported causes, organizations,\ncreator tiers and the activity feed. `GET /users/{id}/impact`\nanswers the headline figure only, and the follower and\nfollowing LISTS refuse.\n\n`unlisted` is not accepted here.\n",
                    "example": "private"
                  },
                  "show_followed_cities_to_friends": {
                    "type": "boolean",
                    "description": "Settings > Privacy (#2064, default true). Off: friends never see this\nperson's face on the cities they follow; they are still counted.\n"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Profile updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The path id is not the caller's own profile.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users/{id}/organizations": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Get a user's organization memberships",
        "operationId": "getUserOrganizations",
        "description": "Public org memberships for a user (UUID or profile_slug). Memberships marked not publicly visible, memberships of deleted organizations, and every membership of a private profile — even to its owner — are left out. 404 only when the user does not exist.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User organizations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "The organization's public fields plus the membership: the same shape as `GET /organizations/me`.",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "legal_name": {
                            "type": "string"
                          },
                          "dba_name": {
                            "type": "string",
                            "nullable": true
                          },
                          "slug": {
                            "type": "string",
                            "nullable": true
                          },
                          "logo": {
                            "type": "string",
                            "nullable": true
                          },
                          "verification_status": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string"
                          },
                          "role_name": {
                            "type": "string"
                          },
                          "role_display_name": {
                            "type": "string"
                          },
                          "org_role_title_label": {
                            "type": "string",
                            "nullable": true
                          },
                          "start_date": {
                            "type": "string",
                            "format": "date",
                            "nullable": true
                          },
                          "end_date": {
                            "type": "string",
                            "format": "date",
                            "nullable": true
                          },
                          "is_current": {
                            "type": "boolean"
                          },
                          "affiliation_description": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/users/{id}/activity": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Get a user's public activity feed",
        "operationId": "getProfileActivity",
        "description": "The public activity feed on a profile (#1693): six kinds of public act, ordered newest first. Accepts a UUID or a profile_slug; auth-optional.\n\n`campaign_launched` (the campaign passed approval), `achievement_earned` (a badge, read through the same public projection the profile badge strip uses), `commented`, `donated`, `update_posted` and `endorsed` (declared, or their referral link for that campaign recorded a visit — the definition the Endorsed-by dialog and the profile chip already use).\n\nEach row inherits the visibility of the thing it reports: a refunded or charged-back gift, a hidden or retracted comment, a withdrawn update, a soft-deleted campaign and a revoked award are all simply absent. **Anonymous gifts never appear, for anyone, including the profile's owner.** A campaign that is unlisted, private, paused, draft or deleted is never named. A profile with `show_donations_on_profile` off keeps every row type except `donated`.\n\nAll money is INTEGER CENTS, never dollars. `amount_cents` on a `donated` row is what the gift raised — net of fees, tips excluded: its ledger credit less its Stripe fee — which is the same figure the profile's Impact stat sums and the campaign's donor wall prints, so they cannot disagree.\n\nPaging is a KEYSET cursor, not an offset: pass the `nextCursor` from the previous page back as `cursor`. A cursor this endpoint did not issue is a 400. `nextCursor` is null on the last page.\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A user UUID or a profile_slug.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "group",
            "in": "query",
            "required": false,
            "description": "Filter chip. `giving` is `donated`; `fundraising` is `campaign_launched` and `update_posted`; `community` is `commented`, `achievement_earned` and `endorsed`. An unrecognised value falls back to `all`. The `summary` block is NOT filtered — it is the strip above the chips and always counts every type.\n",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "giving",
                "fundraising",
                "community"
              ],
              "default": "all"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The opaque `nextCursor` from the previous page. Omit for page 1.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of the feed. A private profile answers 200 with an empty `items` array to everybody but its owner, rather than 404 — the page renders and the section is simply empty.\n",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "items",
                    "nextCursor",
                    "joinedAt",
                    "summary"
                  ],
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "type",
                          "at"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "`<type>:<source key>` — stable, usable as a list key and as a deep link. For `achievement_earned` the source key is the badge SLUG, which is how every public surface addresses a badge.\n",
                            "example": "donated:6f1c2a2e-2b0a-4c6f-9a7e-2f0b9c1d4e55"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "donated",
                              "commented",
                              "update_posted",
                              "campaign_launched",
                              "achievement_earned",
                              "endorsed"
                            ]
                          },
                          "at": {
                            "type": "string",
                            "format": "date-time",
                            "description": "The witnessed timestamp for this row. For `donated` that is when the gift settled, not when the payment form was opened.\n"
                          },
                          "campaign": {
                            "nullable": true,
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "slug": {
                                "type": "string"
                              },
                              "title": {
                                "type": "string"
                              },
                              "cover_image": {
                                "type": "string",
                                "nullable": true
                              }
                            }
                          },
                          "amount_cents": {
                            "type": "integer",
                            "nullable": true,
                            "description": "Integer minor units. Never dollars."
                          },
                          "currency": {
                            "type": "string",
                            "nullable": true
                          },
                          "excerpt": {
                            "type": "string",
                            "nullable": true,
                            "description": "Comment body or update title, trimmed to 280 characters. Null for a comment that is only a GIF."
                          },
                          "gif": {
                            "allOf": [
                              {
                                "$ref": "#/components/schemas/Gif"
                              }
                            ],
                            "nullable": true,
                            "description": "The GIF on a `commented` row (#1963); null on every other row."
                          },
                          "achievement": {
                            "nullable": true,
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The badge slug."
                              },
                              "title": {
                                "type": "string",
                                "nullable": true
                              },
                              "tagline": {
                                "type": "string",
                                "nullable": true
                              },
                              "tier": {
                                "type": "string",
                                "nullable": true
                              },
                              "badge_art_url": {
                                "type": "string",
                                "nullable": true
                              },
                              "background_color": {
                                "type": "string",
                                "nullable": true
                              }
                            }
                          }
                        }
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    },
                    "joinedAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When the account was created — the terminal \"Joined FundlyHub\" row at the end of the feed.\n"
                    },
                    "summary": {
                      "type": "object",
                      "properties": {
                        "windowDays": {
                          "type": "integer",
                          "enum": [
                            30
                          ]
                        },
                        "total": {
                          "type": "integer"
                        },
                        "byType": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "description": "The `features.activity_feed` flag is off."
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/users/{id}/donation-activity": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Get a user's public donation activity",
        "operationId": "getUserDonationActivity",
        "description": "\"Causes I support\" on a public profile — the aggregate plus one entry per supported campaign. Accepts a UUID or a profile_slug; 404 only when the user does not exist.\n\nAnonymous gifts are excluded, always. A profile that is private, or that has `show_donations_on_profile` off, answers zeroes. Only settled (`paid`) gifts count, and only to a campaign a reader could actually open — a deleted, draft, private, paused or unlisted campaign is neither listed nor counted (#1694).\n\nEach entry in `recent_supported_causes` is a full campaign card, the same read model `/fundraisers` serves the /causes grid from, so the section renders the card the rest of the product uses. `total_cents` figures are INTEGER CENTS.\n\n`total_donated_cents` is the PUBLIC figure and excludes anonymous gifts. It is what those gifts raised — net of fees, tips excluded: each gift's ledger credit less its Stripe fee, over its paid and refunded gifts to public campaigns — so it agrees with the profile activity feed's per-gift figures and with the campaign cards those gifts went to. `/donor/me/summary` counts every gift the owner made and is a different number by design; do not compare them.\n\n`currency` is the ISO 4217 code `total_donated_cents` is denominated in, taken from the donor's most recent gift that named one. Read it: minor units are not always hundredths, so formatting the total without it is a 100x error for a zero-decimal currency, not just the wrong symbol.\n",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Causes per page. The profile rail asks for 6; the dedicated page asks for more.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 48,
              "default": 6
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User donation activity",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "total_donated_cents": {
                          "type": "integer",
                          "description": "INTEGER MINOR UNITS. What the counted gifts raised, net of fees, tips excluded.\n"
                        },
                        "currency": {
                          "type": "string",
                          "description": "ISO 4217 code for `total_donated_cents`, from the donor's most recent gift that named one; the platform default when no gift does.\n",
                          "example": "USD"
                        },
                        "causes_supported_count": {
                          "type": "integer"
                        },
                        "recent_supported_causes": {
                          "type": "array",
                          "description": "One campaign card per supported campaign, newest gift first. Carries the campaign's public fields plus `profiles`, `owner_name`, `owner_avatar`, `category_name`, `total_raised_cents`, `donor_count` and `gallery` (the card's photos, cover first, at most six — as on `GET /fundraisers`), and the `fundraiser_id` and `last_donation_at` fields.\n",
                          "items": {
                            "type": "object"
                          }
                        },
                        "pagination": {
                          "type": "object",
                          "properties": {
                            "limit": {
                              "type": "integer"
                            },
                            "offset": {
                              "type": "integer"
                            },
                            "total": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/users/{id}/impact": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Get a user's Impact and leaderboard rank",
        "operationId": "getUserImpact",
        "description": "The figures behind the Impact stat on a public profile, read from the same all-time field `/leaderboard` is served from, so the two surfaces always agree. Accepts a UUID or a profile_slug. All money is integer cents. A user who has not moved money answers zeroes and a null rank rather than 404 — their referral impressions are still reported. A private profile answers its headline `impact` figure only, with the rest of the breakdown zeroed and `rank` null, to everybody but its owner. If the leaderboard field cannot be read the endpoint answers `200` with zeroes rather than failing the profile.\n",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The user's Impact breakdown",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "impact": {
                      "type": "object",
                      "properties": {
                        "rank": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Place on the all-time Everyone leaderboard, or null when unranked."
                        },
                        "impact": {
                          "type": "integer",
                          "description": "raised + given + driven, in cents — what the leaderboard ranks on."
                        },
                        "raised": {
                          "type": "integer",
                          "description": "Sum of the person's counted campaign cards, in cents. Own gifts included."
                        },
                        "given": {
                          "type": "integer",
                          "description": "What every gift they made raised, to their own campaigns and to others', in cents: net of fees, tips excluded."
                        },
                        "driven": {
                          "type": "integer",
                          "description": "What gifts through their referral links raised for campaigns they do not organise, in cents: net of fees, tips excluded."
                        },
                        "impressions": {
                          "type": "integer",
                          "description": "Non-bot visits on their referral links. A count, not money."
                        },
                        "gifts": {
                          "type": "integer",
                          "description": "The gifts behind `given` (paid or refunded, to public campaigns)."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/users/{id}/permissions": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Get a user's permissions",
        "operationId": "getUserPermissions",
        "description": "Role assignments and effective permissions for the user named in the path. Requires a bearer session. Callers may read their own; reading another user's requires the `view_all_users` permission, and any other caller gets `403`. Answers can be several minutes old; for the caller's own, current permissions use `GET /me/capabilities`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User permissions — a bare object.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "roles": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "role_name": {
                            "type": "string"
                          },
                          "context_type": {
                            "type": "string",
                            "description": "`global`, `organization`, …"
                          },
                          "context_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "hierarchy_level": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "permissions": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "roleDefinitions": {
                      "type": "array",
                      "description": "Every role on the platform, with its hierarchy level.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "hierarchy_level": {
                            "type": "integer"
                          },
                          "context_type": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The path id is not the caller's own and the caller lacks `view_all_users`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users/{id}/preferences": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Get user preferences",
        "operationId": "getUserPreferences",
        "description": "Returns the caller's own preferences. Callers may only access their own — any other path id answers `403`.\nAccounts with no stored row get a default object rather than a `404`, so the returned key set differs slightly between the two cases. `suppressed_scopes` is always present: it lists the notification scopes this account's **email address** has been unsubscribed from via an emailed link. Those suppressions are keyed by address, not by account, so they stop mail even while the matching toggle reads true — which is exactly why they are reported separately rather than folded into the toggles.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User preferences",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "properties": {
                    "user_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "email_notifications": {
                      "type": "boolean"
                    },
                    "push_notifications": {
                      "type": "boolean"
                    },
                    "suppressed_scopes": {
                      "type": "array",
                      "description": "Notification scopes this account's email address has opted out of. Only self-service opt-outs appear here — suppressions FundlyHub applies itself (for example after a bounce) stay in force and are not listed.",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The path id is not the caller's own profile.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Users"
        ],
        "summary": "Update user preferences",
        "operationId": "updateUserPreferences",
        "description": "Upserts the caller's own preferences and returns the stored row. Callers may only update their own — any other path id answers `403`. `suppressed_scopes` is read-only and is not accepted here; an address unsubscribed by an emailed link can only be resubscribed through `/unsubscribe/resubscribe`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "A partial update — an omitted field keeps its stored value. Unknown fields are ignored.",
                "properties": {
                  "view_mode": {
                    "type": "string",
                    "enum": [
                      "grid",
                      "list"
                    ]
                  },
                  "theme": {
                    "type": "string"
                  },
                  "admin_theme": {
                    "type": "string"
                  },
                  "recent_searches": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "search_suggestions": {
                    "type": "boolean"
                  },
                  "email_notifications": {
                    "type": "boolean"
                  },
                  "push_notifications": {
                    "type": "boolean"
                  },
                  "reduced_motion": {
                    "type": "boolean"
                  },
                  "high_contrast": {
                    "type": "boolean"
                  },
                  "font_size": {
                    "type": "string"
                  },
                  "has_completed_onboarding": {
                    "type": "boolean"
                  },
                  "has_skipped_onboarding": {
                    "type": "boolean"
                  },
                  "last_visited": {
                    "type": "string"
                  },
                  "auto_save": {
                    "type": "boolean"
                  },
                  "default_category": {
                    "type": "string"
                  },
                  "notify_donations": {
                    "type": "boolean"
                  },
                  "notify_comments": {
                    "type": "boolean"
                  },
                  "notify_updates": {
                    "type": "boolean"
                  },
                  "notify_milestones": {
                    "type": "boolean"
                  },
                  "notify_campaign_status": {
                    "type": "boolean"
                  },
                  "notify_followers": {
                    "type": "boolean"
                  },
                  "notify_org_status": {
                    "type": "boolean"
                  },
                  "notify_payouts": {
                    "type": "boolean"
                  },
                  "notify_digest": {
                    "type": "boolean"
                  },
                  "notify_donation_reminders": {
                    "type": "boolean"
                  },
                  "notify_endorsement_requests": {
                    "type": "boolean"
                  },
                  "notify_communities": {
                    "type": "boolean"
                  },
                  "notify_sponsors": {
                    "type": "boolean",
                    "description": "Sponsor emails. Off is \"Unsubscribe from all sponsor emails\"."
                  },
                  "show_sponsor_perks": {
                    "type": "boolean",
                    "description": "Privacy, \"Show sponsor perks\". Off hides perks, codes and sponsor alerts."
                  },
                  "notify_nearby_perks": {
                    "type": "boolean",
                    "description": "A sponsor near you adds a perk for an achievement you hold. Default false."
                  },
                  "notify_perk_changes": {
                    "type": "boolean",
                    "description": "A perk you used is getting smaller or ending, 14 days ahead. Default true."
                  },
                  "notify_sponsor_posts": {
                    "type": "boolean",
                    "description": "New perks and updates from sponsors you follow. Default true."
                  },
                  "notify_resources": {
                    "type": "boolean",
                    "description": "Resources emails to the people who run a provider's listings: reviews, reminders to confirm, fundraisers that name the help, staff changes, licenses. Default true. A listing hidden or taken down is emailed whatever it says."
                  },
                  "notify_my_help": {
                    "type": "boolean",
                    "description": "My help emails: what a provider said about the help your fundraiser names. Default true."
                  },
                  "notify_free_stuff": {
                    "type": "boolean",
                    "description": "Free stuff emails: an ask's news, your posts, the daily asks digest, a pickup message unread for an hour. Default true. A post taken down or a pause on you is emailed whatever it says."
                  },
                  "notify_events": {
                    "type": "boolean",
                    "description": "Events emails: reminders, recaps, a host's message, host and volunteer notices, co-host invitations, the waitlist, tickets going on sale. Default true. Your tickets, receipts, payment links, refunds, cancellations and a change of date or place to an event you hold a ticket to are emailed whatever it says."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated preferences — the stored row.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The path id is not the caller's own profile.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users/{id}/avatar": {
      "post": {
        "tags": [
          "Users"
        ],
        "summary": "Upload user avatar",
        "operationId": "uploadAvatar",
        "description": "Upload the caller's own avatar from a base64-encoded image — JPEG, PNG or WebP, at most 5 MB decoded. Callers may only update their own.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "fileBase64",
                  "contentType"
                ],
                "properties": {
                  "fileBase64": {
                    "type": "string"
                  },
                  "contentType": {
                    "type": "string",
                    "enum": [
                      "image/jpeg",
                      "image/png",
                      "image/webp"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Avatar uploaded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "avatar_url": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The path id is not the caller's own profile.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Users"
        ],
        "summary": "Delete user avatar",
        "operationId": "deleteAvatar",
        "description": "Delete the caller's own avatar. Callers may only delete their own.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Avatar deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The path id is not the caller's own profile.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users/{id}/deactivate": {
      "post": {
        "tags": [
          "Users"
        ],
        "summary": "Self-deactivate account",
        "operationId": "selfDeactivateAccount",
        "description": "Deactivates the caller's own account and clears auth cookies. Callers may only deactivate their own.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Account deactivated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The path id is not the caller's own profile.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Account could not be deactivated: it still owns active campaigns that have collected money. `error` names them.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users/me/deletion-request": {
      "post": {
        "tags": [
          "Users"
        ],
        "summary": "Request account deletion",
        "operationId": "requestAccountDeletion",
        "description": "Schedules deletion of the caller's account 30 days from now. In the same step every personal campaign of theirs that is active, paused or pending is closed (status `ended`), so it stops taking donations, and every session is signed out: the cookies of this one are cleared, every refresh token is revoked and every API key is revoked. An access token already issued keeps working until it expires (at most an hour).\n\nThe person can sign in again during the 30 days, which is how they reach Cancel; `GET /cognito/me` and the sign-in response then carry `deletion_scheduled_for`. They cannot publish or reopen a campaign meanwhile (publish blocker `account_deletion_pending`).\n\nAfter the 30 days the account is deleted once nothing is owed to the person: money not yet paid out is paid out to their verified payout account first, and deletion waits for it. Donation and payout records are kept, anonymised; everything else is deleted, including the sign-in. Campaigns they created for an organization are the organization's: they keep running, and when the deletion completes they are handed to an owner of that organization, unchanged.\n\nIdempotent: while a request is pending, calling again returns `200` with the same schedule and changes nothing. Requires a signed-in session; refused for an API key and while FundlyHub support is viewing the account.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "A deletion was already pending; its schedule, unchanged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountDeletionSchedule"
                }
              }
            }
          },
          "201": {
            "description": "Deletion scheduled; this session is signed out.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountDeletionSchedule"
                },
                "example": {
                  "scheduled_for": "2026-11-06T12:00:00.000Z",
                  "requested_at": "2026-10-07T12:00:00.000Z"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not a signed-in session (`SESSION_CREDENTIAL_REQUIRED`), or FundlyHub support is viewing the account (`IMPERSONATION_RESTRICTED_ACTION`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Nothing was scheduled, for one of two reasons. The caller is the only owner of one or more organizations (`SOLE_ORGANIZATION_OWNER`, with `organizations`): deleting the account would leave each with nobody able to run it; make another member an owner, or close the organization, first. Or the caller owns a sponsor that is under review, asked for changes, live, paused or suspended (`SOLE_SPONSOR_OWNER`, with `sponsors`): a sponsor has one owner, so hand it over to someone on its team at `team_url`, withdraw its application, or leave FundlyHub and wait for it to close, first. A sponsor that is still a draft, or has closed, does not block. Organizations are checked first.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "organizations": {
                          "description": "With `SOLE_ORGANIZATION_OWNER`, the organizations the caller alone owns.",
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "name": {
                                "type": "string",
                                "nullable": true
                              }
                            }
                          }
                        },
                        "sponsors": {
                          "description": "With `SOLE_SPONSOR_OWNER`, the sponsors the caller owns, by name.",
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "id",
                              "slug",
                              "name",
                              "status",
                              "team_url"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "slug": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "under_review",
                                  "changes_requested",
                                  "live",
                                  "paused",
                                  "suspended"
                                ]
                              },
                              "team_url": {
                                "type": "string",
                                "format": "uri",
                                "description": "The sponsor workspace's Team screen, where the owner hands the sponsor over."
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "organization": {
                    "value": {
                      "error": "You are the only owner of an organization. Make someone else an owner, or close the organization, before deleting your account.",
                      "code": "SOLE_ORGANIZATION_OWNER",
                      "organizations": [
                        {
                          "id": "7d1f0c2a-9b3e-4f5a-8c6d-1e2f3a4b5c6d",
                          "name": "Riverside Food Bank"
                        }
                      ]
                    }
                  },
                  "sponsor": {
                    "value": {
                      "error": "You own a sponsor on FundlyHub. Hand it over to someone on its team in Team, withdraw its application, or leave FundlyHub and wait for it to close, before deleting your account.",
                      "code": "SOLE_SPONSOR_OWNER",
                      "sponsors": [
                        {
                          "id": "b8a0c7a2-2d1e-4c55-9a8e-0e6f1d2c3b4a",
                          "slug": "fast-cat-coffee-bar",
                          "name": "Fast Cat Coffee Bar",
                          "status": "live",
                          "team_url": "https://fundlyhub.org/sponsors/fast-cat-coffee-bar/manage/team"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Get the pending account deletion",
        "operationId": "getAccountDeletion",
        "description": "The caller's pending account deletion. `awaiting_payout` is true once the 30 days have passed and deletion is waiting for money owed to the caller to be paid out.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "A deletion is pending.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "requested_at",
                    "scheduled_for",
                    "awaiting_payout"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "pending"
                      ]
                    },
                    "requested_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "scheduled_for": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "awaiting_payout": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "status": "pending",
                  "requested_at": "2026-10-07T12:00:00.000Z",
                  "scheduled_for": "2026-11-06T12:00:00.000Z",
                  "awaiting_payout": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No deletion is pending (`NO_PENDING_DELETION`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Users"
        ],
        "summary": "Cancel account deletion",
        "operationId": "cancelAccountDeletion",
        "description": "Cancels the caller's pending account deletion. Allowed until the deletion has completed. Campaigns the request closed go back to the status they had, if they are still closed and not deleted; any other campaign is left as it is. Requires a signed-in session; refused for an API key and while FundlyHub support is viewing the account.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Cancelled.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "cancelled_at",
                    "restored_campaign_ids"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "cancelled"
                      ]
                    },
                    "cancelled_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "restored_campaign_ids": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "description": "The campaigns reopened to their earlier status."
                    }
                  }
                },
                "example": {
                  "status": "cancelled",
                  "cancelled_at": "2026-10-08T09:30:00.000Z",
                  "restored_campaign_ids": [
                    "5b0c3a8e-2f4d-4c1a-9e7b-0d6f1a2b3c4d"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not a signed-in session (`SESSION_CREDENTIAL_REQUIRED`), or FundlyHub support is viewing the account (`IMPERSONATION_RESTRICTED_ACTION`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No deletion is pending (`NO_PENDING_DELETION`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users/me/private-contact": {
      "put": {
        "tags": [
          "Users"
        ],
        "summary": "Set private contact email",
        "operationId": "setPrivateContact",
        "description": "Sets the caller's private contact email (visible only to the FundlyHub team). Validates format, blocks disposable domains, and triggers a verification email when the address changes — unless it is the caller's own verified sign-in address, which counts as verified at once. Shares the verification-resend limit: 5 requests per minute per user.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Private contact email saved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "email": {
                      "type": "string"
                    },
                    "verified": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The address is already another account's contact or sign-in address (`code: CONTACT_EMAIL_TAKEN`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/users/me/phone": {
      "put": {
        "tags": [
          "Users"
        ],
        "summary": "Set phone number",
        "operationId": "setPhone",
        "description": "Sets the caller's phone number, unverified. A changed number is no longer verified (`phone_verified` goes back to false); verify it with a texted code through `/users/me/phone-verification/send` and `/confirm`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "phone"
                ],
                "properties": {
                  "phone": {
                    "type": "string",
                    "pattern": "^[+\\d\\s\\-().]{7,20}$",
                    "description": "Digits, spaces, `+`, `-`, `(`, `)` and `.`, 7 to 20 characters. Stored trimmed."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Phone number saved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "phone": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/users/me/phone-verification": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Phone verification status",
        "operationId": "getPhoneVerification",
        "description": "Whether the caller can verify a phone with a texted code here (`available`), whether their phone is verified (`profiles.phone_verified`, which free stuff requires), and the last four digits of the number on file. Never the number itself.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhoneVerificationStatus"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/users/me/phone-verification/send": {
      "post": {
        "tags": [
          "Users"
        ],
        "summary": "Text me a code",
        "operationId": "sendPhoneVerificationCode",
        "description": "Sets the caller's Cognito `phone_number` to this number and Cognito texts a code to it (the attribute's own verification, with the session's access token). The profile does not change until the code is confirmed. US and Canadian numbers may be written without +1; others start with + and the country code. Limits: a code a minute, 5 an hour and 10 a day per person, and 3 an hour and 5 a day per number whoever asks (429 `too_many_codes` with `details.retry_after_seconds` and `Retry-After`). Already verified with this number: nothing is sent. 503 `phone_verification_unavailable` (\"Phone verification isn't available yet\") until the service is switched on and the user pool can send SMS, or when the session's access token can't make these calls. Refused while impersonating and for API keys. The number and the code are never logged.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "phone"
                ],
                "properties": {
                  "phone": {
                    "type": "string",
                    "maxLength": 24,
                    "example": "(916) 555-0108"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The code was sent (or the number is already verified).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sent": {
                      "type": "boolean"
                    },
                    "alreadyVerified": {
                      "type": "boolean"
                    },
                    "phone": {
                      "type": "string",
                      "description": "The last four digits, \"•••• 0108\"."
                    },
                    "resendAfterSeconds": {
                      "type": "integer",
                      "description": "Seconds before another code can be asked for."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Not signed in, or the session's access token is missing or not this person's (`sign_in_again`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhoneVerificationError"
                }
              }
            }
          },
          "403": {
            "description": "An impersonation session (`IMPERSONATION_RESTRICTED_ACTION`) or an API key (`SESSION_CREDENTIAL_REQUIRED`)."
          },
          "409": {
            "description": "`phone_in_use`: another account already uses this number.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhoneVerificationError"
                }
              }
            }
          },
          "422": {
            "description": "`phone_invalid`: not a mobile number.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhoneVerificationError"
                }
              }
            }
          },
          "429": {
            "description": "`too_many_codes`, with `details.retry_after_seconds`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhoneVerificationError"
                }
              }
            }
          },
          "503": {
            "description": "`phone_verification_unavailable`: Phone verification isn't available yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhoneVerificationError"
                }
              }
            }
          }
        }
      }
    },
    "/users/me/phone-verification/confirm": {
      "post": {
        "tags": [
          "Users"
        ],
        "summary": "Confirm the texted code",
        "operationId": "confirmPhoneVerificationCode",
        "description": "Cognito checks the code (VerifyUserAttribute on `phone_number`). Once Cognito reports the number verified, the profile records the number Cognito verified and `phone_verified = true`, and the change is audited (`user.phone_verified`). 10 tries an hour per person (429 `too_many_tries`). Same 401, 403 and 503 answers as send.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "pattern": "^\\d{4,8}$",
                    "example": "123456"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verified.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "phoneVerified": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "phone": {
                      "type": "string",
                      "nullable": true,
                      "description": "The last four digits, \"•••• 0108\"."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "An impersonation session or an API key."
          },
          "409": {
            "description": "`not_verified`: Cognito did not mark the number verified; ask for a new code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhoneVerificationError"
                }
              }
            }
          },
          "422": {
            "description": "`code_wrong` or `code_expired`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhoneVerificationError"
                }
              }
            }
          },
          "429": {
            "description": "`too_many_tries`, with `details.retry_after_seconds`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhoneVerificationError"
                }
              }
            }
          },
          "503": {
            "description": "`phone_verification_unavailable`: Phone verification isn't available yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhoneVerificationError"
                }
              }
            }
          }
        }
      }
    },
    "/users/me/publish-readiness": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Get publish-readiness checklist",
        "operationId": "getPublishReadiness",
        "description": "Returns the publish-gate checklist for the caller (hard blockers + soft suggestions). When the checklist is unavailable the answer is `ready: true`, `checklist: null` and `migration_pending: true`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Publish-readiness status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ready": {
                      "type": "boolean"
                    },
                    "checklist": {
                      "type": "object",
                      "nullable": true,
                      "additionalProperties": {
                        "type": "boolean"
                      }
                    },
                    "blockers": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "suggestions": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "migration_pending": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/users/me/blocks": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "List the people you have blocked",
        "operationId": "listMyBlocks",
        "description": "The people the caller has blocked, newest first, with the public name (never an email), avatar and handle. Rate limited per account.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Blocked people",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BlockedUser"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/users/{id}/block": {
      "post": {
        "tags": [
          "Users"
        ],
        "summary": "Block a person",
        "operationId": "blockUser",
        "description": "Blocks a person (App Store Guideline 1.2). `id` is a profile UUID or handle, with or without `@`, as on `GET /users/{id}`. Idempotent: `201` when the block is new, `200` when it already existed.\n\nA block, enforced by the server for every client:\n- the caller stops receiving that person's comments and replies\n  (`GET /fundraisers/{fundraiserId}/comments`) and the commented rows\n  of their profile activity;\n\n- follows between the two are removed in BOTH directions, and neither\n  can follow the other while the block stands\n  (`POST /subscriptions` answers `403 USER_BLOCKED`);\n\n- the blocked person cannot comment on the caller's campaigns or reply\n  to the caller's comments (`403 COMMENTING_BLOCKED`).\n\nNobody is notified. Unblocking does not restore removed follows.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Profile UUID or handle."
          }
        ],
        "responses": {
          "200": {
            "description": "Already blocked; nothing changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlockState"
                }
              }
            }
          },
          "201": {
            "description": "Blocked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlockState"
                }
              }
            }
          },
          "400": {
            "description": "`code: CANNOT_BLOCK_SELF`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodedError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`code: USER_NOT_FOUND`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodedError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Users"
        ],
        "summary": "Unblock a person",
        "operationId": "unblockUser",
        "description": "Removes the caller's block of this person. Idempotent: `200` whether or not a block existed. Follows the block removed are not restored.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Profile UUID or handle."
          }
        ],
        "responses": {
          "200": {
            "description": "Not blocked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "user_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "blocked": {
                          "type": "boolean",
                          "enum": [
                            false
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`code: CANNOT_BLOCK_SELF`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodedError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`code: USER_NOT_FOUND`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodedError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/users/check-slug/{slug}": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Check profile slug availability",
        "operationId": "checkProfileSlug",
        "description": "Whether a profile handle (the `@name` in a profile's address) is free to take. The value is trimmed, a leading `@` is dropped and it is lower-cased before the check. `available` is false for a reserved handle, a handle another profile uses, and a handle another account used before (a retired handle stays with its first owner, so its old links cannot be taken over). Pass your own user id as `exclude` so that your current handle and the ones you retired count as available. No authentication.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "exclude",
            "in": "query",
            "required": false,
            "description": "User id to exclude from the uniqueness check.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Slug availability",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "available": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/leaderboard": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "Public leaderboard",
        "operationId": "getLeaderboard",
        "description": "One ranked list on impact = raised + given + driven, in integer cents, over the chosen period.\nAll three value a gift the one way the campaign card does: what it raised, net of fees, tips excluded\n(its ledger credit less its Stripe fee), over paid and refunded gifts to public campaigns — a refund\ndoes not lower any of them.\nRaised is the sum of the person's counted campaign cards — gifts to public fundraisers they organize, their own gifts included;\nGiven is every such gift they made under their name; Driven is other people's such gifts through\ntheir share or ambassador link to fundraisers they do not organize. Every dollar counts once.\nAnonymous donors appear as alias rows keyed on an opaque `anonymousKey`; guest and anonymous rows link to their donor page under `/d/{kind}/{key}`.\nWhen the request carries a session, `standing` describes where the caller ranks on the full view.\n`q` searches the ranked board by name without renumbering it: a match keeps the rank it has on the full view.\n\nViews and scopes (#2070). Cities and communities are filters on the same board. `view` picks people,\ncommunities or cities; `city` (with `area=1` for its metro) and `community` narrow it. A city scope ranks\nevery row whose ONE home city is in it: a registered person's profile city; without one (and for guest\nand anonymous rows), the city most of that row's own settled gifts come from (`donor_place_id`, all time;\na tie goes to the most recent gift). Guest and anonymous rows are the same rows as Everywhere: a guest by\nthe name the donor wall prints, an anonymous donor by its alias key, never a name, an email or a user id;\na person's anonymous gifts are their alias row's and never place their named row. A community scope ranks its members on\nimpact through that community (`amount_cents`, each gift once per member), and a member who turned off\n\"Show me\" appears as \"A member\" (`hidden: true`, an opaque id, no name). A private community lists its\nmembers to its members only. Scope totals and community/city rows count each settled gift ONCE, in the\nfirst part that claims it (fund, raised, given, driven), so a total is less than its people rows added up;\n`dedupe_note` says when such a total is on the page. Every combination is a valid URL: a view the scope\ndoes not offer falls back to `people`, and only an unknown city or community is a 404 `SCOPE_NOT_FOUND`\n(which is also the answer before the cities and communities tables exist; the two views are then empty).\n",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "period",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "30d",
                "7d"
              ],
              "default": "all"
            }
          },
          {
            "name": "role",
            "in": "query",
            "description": "Everyone; people organizing a public fundraiser; ambassador role holders; or donors — everyone with a settled gift under their name, whatever their role, anonymous identities included. Everyone, creators and ambassadors rank on impact; donors rank on given (see `metric`). A filtered view is ranked within itself.",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "creators",
                "ambassadors",
                "donors"
              ],
              "default": "all"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Name search over this view. Trimmed and cut to 100 characters.",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "lang",
            "in": "query",
            "description": "Language for badge titles and anonymous aliases (en, ru, uk, es). Defaults from Accept-Language.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "view",
            "in": "query",
            "description": "What is ranked. A city scope offers people and communities; a community scope offers people (its members). Another value falls back to people.",
            "schema": {
              "type": "string",
              "enum": [
                "people",
                "communities",
                "cities"
              ],
              "default": "people"
            }
          },
          {
            "name": "city",
            "in": "query",
            "description": "A city's slug (e.g. `sacramento-ca`), case-insensitive. An old slug of a renamed or merged city resolves to the surviving one; `scope.slug` is canonical.",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "area",
            "in": "query",
            "description": "With `city`, `1` includes the city's whole metro, counted as one scope. Ignored for a city with no metro.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          },
          {
            "name": "community",
            "in": "query",
            "description": "A community's slug (or id), case-insensitive. Wins over `city` when both are sent.",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of the ranked view",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entries": {
                      "type": "array",
                      "description": "Rows of the view, discriminated by `type`: people rows (below), or `LeaderboardCommunityRow` / `LeaderboardCityRow` on the communities and cities views.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": [
                              "person",
                              "community",
                              "city"
                            ]
                          },
                          "city": {
                            "type": "object",
                            "nullable": true,
                            "description": "People rows. The city on the person's PROFILE, never a billing address or IP; always null on guest, anonymous and hidden rows.",
                            "properties": {
                              "slug": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              }
                            }
                          },
                          "community_scope": {
                            "type": "object",
                            "nullable": true,
                            "description": "People rows. Set on the City of Goodness Team account's row, which links to its community scope (`href` is then `/leaderboard?community=<slug>`).",
                            "properties": {
                              "slug": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              }
                            }
                          },
                          "is_viewer": {
                            "type": "boolean",
                            "description": "People rows. This row is the signed-in caller, hidden rows included"
                          },
                          "community_role": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "owner",
                              "leader",
                              "volunteer",
                              "member"
                            ],
                            "description": "Community scope only. Null when the community hides its team and the caller is not its owner or a leader."
                          },
                          "hidden": {
                            "type": "boolean",
                            "description": "Community scope only. \"Show me\" is off: the row is \"A member\", with an opaque `member:<key>` id and no name, avatar, link or city"
                          },
                          "rank": {
                            "type": "integer",
                            "description": "Consecutive, 1..N; an equal figure goes to the more recent person"
                          },
                          "tied": {
                            "type": "boolean",
                            "description": "Always false; ranks are consecutive. Kept for compatibility"
                          },
                          "id": {
                            "type": "string",
                            "description": "Profile id, `guest:<key>` for a guest donor, or `anon:<key>` for an anonymous identity"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "individual",
                              "team",
                              "ambassador",
                              "org",
                              "anonymous"
                            ]
                          },
                          "name": {
                            "type": "string",
                            "nullable": true
                          },
                          "avatar": {
                            "type": "string",
                            "nullable": true
                          },
                          "href": {
                            "type": "string",
                            "nullable": true,
                            "description": "Profile path, or `/d/guest/<key>` / `/d/anon/<key>` for a donor identity; null only for a private profile"
                          },
                          "anonymousKey": {
                            "type": "string",
                            "nullable": true
                          },
                          "isCreator": {
                            "type": "boolean"
                          },
                          "isAmbassador": {
                            "type": "boolean"
                          },
                          "raised": {
                            "type": "integer",
                            "description": "Cents: the sum of the person's campaign cards"
                          },
                          "given": {
                            "type": "integer",
                            "description": "Cents the person's gifts raised: net of fees, tips excluded"
                          },
                          "driven": {
                            "type": "integer",
                            "description": "Cents their referred gifts raised: net of fees, tips excluded"
                          },
                          "impact": {
                            "type": "integer",
                            "description": "Cents; raised + given + driven"
                          },
                          "score": {
                            "type": "integer",
                            "description": "Cents this row is ranked on — impact, or given on the donors view"
                          },
                          "impressions": {
                            "type": "integer"
                          },
                          "gifts": {
                            "type": "integer"
                          },
                          "badges": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "slug": {
                                  "type": "string"
                                },
                                "artKey": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "artUrl": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "tier": {
                                  "type": "string"
                                },
                                "title": {
                                  "type": "string",
                                  "nullable": true
                                }
                              }
                            }
                          },
                          "badgeCount": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "qualified": {
                      "type": "integer",
                      "description": "Everyone on this view, loaded or not"
                    },
                    "hasMore": {
                      "type": "boolean"
                    },
                    "standing": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "rank": {
                          "type": "integer"
                        },
                        "tied": {
                          "type": "boolean"
                        },
                        "score": {
                          "type": "integer",
                          "description": "Cents the caller is ranked on in this view"
                        },
                        "impact": {
                          "type": "integer"
                        },
                        "raised": {
                          "type": "integer"
                        },
                        "given": {
                          "type": "integer"
                        },
                        "driven": {
                          "type": "integer"
                        },
                        "gap": {
                          "type": "integer",
                          "description": "Cents of score to the person one rank up; 0 at the top or when only recency separates them"
                        },
                        "above": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    },
                    "period": {
                      "type": "string",
                      "enum": [
                        "all",
                        "30d",
                        "7d"
                      ]
                    },
                    "role": {
                      "type": "string",
                      "enum": [
                        "all",
                        "creators",
                        "ambassadors",
                        "donors"
                      ]
                    },
                    "metric": {
                      "type": "string",
                      "enum": [
                        "impact",
                        "given"
                      ],
                      "description": "What this view ranks on"
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "query": {
                      "type": "string",
                      "nullable": true,
                      "description": "The `q` that was applied, after trimming; null when none"
                    },
                    "view": {
                      "type": "string",
                      "enum": [
                        "people",
                        "communities",
                        "cities"
                      ],
                      "description": "The effective view"
                    },
                    "views": {
                      "type": "array",
                      "description": "The views this scope offers",
                      "items": {
                        "type": "string",
                        "enum": [
                          "people",
                          "communities",
                          "cities"
                        ]
                      }
                    },
                    "scope": {
                      "type": "object",
                      "nullable": true,
                      "description": "The scope card; null everywhere",
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/LeaderboardCityScope"
                        },
                        {
                          "$ref": "#/components/schemas/LeaderboardCommunityScope"
                        }
                      ]
                    },
                    "viewer_standing": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/LeaderboardViewerStanding"
                        }
                      ],
                      "nullable": true,
                      "description": "The caller's place in the people view of this scope; null signed out and on the communities and cities views"
                    },
                    "jump_to": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/LeaderboardJumpTo"
                        }
                      ],
                      "nullable": true,
                      "description": "The caller's city and communities; null signed out"
                    },
                    "dedupe_note": {
                      "type": "boolean",
                      "description": "A total that counts each settled gift once is on the page (any scope, the communities and cities views)"
                    },
                    "executionTimeMs": {
                      "type": "integer"
                    },
                    "cached": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown, hidden or malformed city or community, or no such tables yet",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "SCOPE_NOT_FOUND"
                      ]
                    },
                    "scope": {
                      "type": "string",
                      "enum": [
                        "city",
                        "community"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/donors/{kind}/{key}": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "Public donor page",
        "operationId": "getDonorProfile",
        "description": "The public page behind a guest or anonymous donor row on the leaderboard.\n\nA donor identity is addressed ONLY by an opaque public key of 20 hex characters. The key is\none-way: no email, no identity id and no account reference ever leaves the server, and the\nguest key and the anonymous key of one person cannot be related to each other.\n\n`given` and `gifts` cover the identity's paid and refunded gifts to public campaigns — the\nsame figures the leaderboard row shows — each valued at what it raised: net of fees, tips\nexcluded. The `campaigns` list is drawn from those same gifts. A gift to a campaign that is\nnot public is in none of these figures; `campaignsHidden` only counts how many there are.\n\nAn anonymous identity is never named: `name` is null and `anonymousKey` carries the key, from\nwhich the client derives the same localized alias the donor wall shows.\n\nNo authentication: the page is viewer-independent. Money is in integer cents.\n",
        "parameters": [
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "guest",
                "anon"
              ]
            }
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{20}$"
            },
            "description": "The opaque public key from a leaderboard row or a search result."
          }
        ],
        "responses": {
          "200": {
            "description": "The donor page",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "guest",
                        "anon"
                      ]
                    },
                    "key": {
                      "type": "string",
                      "description": "The key, echoed. Never the identity behind it"
                    },
                    "name": {
                      "type": "string",
                      "nullable": true,
                      "description": "The guest's own name; always null for an anonymous identity"
                    },
                    "anonymousKey": {
                      "type": "string",
                      "nullable": true,
                      "description": "The key again for an anonymous identity, so the client can derive the alias and the avatar tone"
                    },
                    "given": {
                      "type": "integer",
                      "description": "Minor units this person's gifts raised: net of fees, tips excluded, over their paid and refunded gifts to public campaigns"
                    },
                    "gifts": {
                      "type": "integer"
                    },
                    "currency": {
                      "type": "string",
                      "nullable": true,
                      "description": "ISO 4217 for every figure on the page, from the most recent gift; null when the rows carried none"
                    },
                    "firstGiftAt": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "lastGiftAt": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "rank": {
                      "type": "integer",
                      "nullable": true,
                      "description": "Place on the all-time Everyone leaderboard; null when it could not be computed"
                    },
                    "score": {
                      "type": "integer",
                      "description": "Cents that rank is on"
                    },
                    "href": {
                      "type": "string",
                      "description": "The page's own path"
                    },
                    "campaigns": {
                      "type": "array",
                      "description": "Public campaigns this person gave to, most recent gift first, at most 24.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "slug": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "coverImage": {
                            "type": "string",
                            "nullable": true
                          },
                          "isProject": {
                            "type": "boolean",
                            "description": "Projects live at /p/<slug>, campaigns at /f/<slug>"
                          },
                          "givenCents": {
                            "type": "integer",
                            "description": "What their gifts to this campaign raised: net of fees, tips excluded"
                          },
                          "gifts": {
                            "type": "integer"
                          },
                          "lastGiftAt": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "campaignsHidden": {
                      "type": "integer",
                      "description": "Gifts to campaigns that are not public. A count only: they are in no figure on the page"
                    },
                    "hasMoreCampaigns": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such donor. Returned for an unknown kind, a malformed key, a key that resolves to nobody and an identity with no settled gift alike — the endpoint does not distinguish them, so it cannot be used to discover which keys are real.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/donor/me/summary": {
      "get": {
        "tags": [
          "Donors"
        ],
        "summary": "Get donor summary",
        "operationId": "getDonorSummary",
        "description": "Aggregate giving stats for the authenticated donor, anonymous gifts included. `lifetimeAmountCents` counts paid gifts only (no refunds or failures); the counts include every gift that left `pending`. A bare object.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Donor summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "lifetimeAmountCents": {
                      "type": "integer",
                      "description": "Gross donation amount in cents, tips excluded."
                    },
                    "donationCount": {
                      "type": "integer"
                    },
                    "supportedFundraisers": {
                      "type": "integer"
                    },
                    "lastDonationAt": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/donor/me/donations": {
      "get": {
        "tags": [
          "Donors"
        ],
        "summary": "Get donor donation history",
        "operationId": "getDonorDonations",
        "description": "Paginated giving history for the authenticated donor with optional filters.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "paid",
                "refunded",
                "failed",
                "pending"
              ]
            }
          },
          {
            "name": "fundraiserId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Donor donations, newest first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "fundraiser_id": {
                            "type": "string",
                            "format": "uuid",
                            "nullable": true
                          },
                          "fundraiser_title": {
                            "type": "string",
                            "nullable": true
                          },
                          "fundraiser_slug": {
                            "type": "string",
                            "nullable": true
                          },
                          "amount_cents": {
                            "type": "integer"
                          },
                          "tip_amount_cents": {
                            "type": "integer"
                          },
                          "fee_amount_cents": {
                            "type": "integer"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "payment_status": {
                            "type": "string",
                            "enum": [
                              "paid",
                              "refunded",
                              "failed",
                              "pending"
                            ]
                          },
                          "payment_intent_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "is_anonymous": {
                            "type": "boolean"
                          },
                          "comment": {
                            "type": "string",
                            "nullable": true
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "totalPages": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/donor/me/annual-statement": {
      "get": {
        "tags": [
          "Donors"
        ],
        "summary": "Download annual giving statement",
        "operationId": "getDonorAnnualStatement",
        "description": "Generates a year-end giving summary for the authenticated donor as PDF or CSV (binary download). Includes only paid donations in the requested calendar year. Not a tax receipt.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "year",
            "in": "query",
            "required": true,
            "description": "Calendar year. Between 2026 and the current year.",
            "schema": {
              "type": "integer",
              "minimum": 2026
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "pdf",
                "csv"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Generated statement file",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/search": {
      "get": {
        "tags": [
          "Search"
        ],
        "summary": "Full-text search",
        "operationId": "fullTextSearch",
        "description": "Search across campaigns, organizations, users, donors, cities, communities and events. Queries shorter than two characters return an empty result set rather than an error. Authentication is optional and does not change the result set, except that Events staff see event rows before Events launch.\nEvent rows (`type: event`, #2495) are live, listed events matched on their title, an accepted host's name (FundlyHub's own row aside) or the city of their venue, upcoming first, then past. They come only while Events are on (features.events), on the first page only, and do not count toward `total`. They carry figures (`starts_at`, `ends_at`, `time_zone`, `day_count`, `host_name`, `city_name`, `cancelled`, `postponed`) for the client to word.\nCity rows (`type: city`) are cities with a page, each metro anchor followed by its metro (`area: true`); community rows (`type: community`) are active, listed communities. Like donor rows they come on the first page only and do not count toward `total`. Their `link` opens the page; `scope_href` is the leaderboard scope the /leaderboard header search offers instead. Donor rows cover guest donors (matched on the name given at checkout — never on an email) and anonymous identities (matched on the localized alias the donor wall shows for that identity), and they link to `/d/{kind}/{key}`.\nTwo limits apply to donor rows specifically. They are returned on the FIRST PAGE ONLY (`offset=0`); the donor ranking is a single highest-given-first list with no stable second page, so a later offset would repeat the same rows rather than continue them. And a guest-donor name match needs three consecutive alphanumeric characters somewhere in the query — `An`, `a_n` and `___` match no guest donor. Anonymous alias matching is unaffected and keeps the two-character minimum. Campaigns, organizations and users page normally and have no such floor.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Search query. Fewer than 2 characters returns an empty result set."
          },
          {
            "name": "scope",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "campaigns",
                "users",
                "orgs",
                "donors",
                "cities",
                "communities",
                "places",
                "events"
              ],
              "default": "all"
            },
            "description": "Limit to a specific resource type. `places` is cities and communities together."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            },
            "description": "Pages campaigns. Donor rows are returned only at `offset=0` — see the description above."
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            },
            "description": "Language an anonymous donor's alias is matched and cached in. Defaults from Accept-Language."
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/suggest": {
      "get": {
        "tags": [
          "Search"
        ],
        "summary": "Autocomplete suggestions",
        "operationId": "autocompleteSuggestions",
        "description": "Typeahead suggestions drawn from the titles of active, public campaigns: a prefix of the original title or of any translated title matches, and the suggestion is the title in the reader's language (`lang`, the language cookie, then `Accept-Language`). Queries shorter than two characters return an empty list.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Suggestions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "suggestions": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "executionTimeMs": {
                      "type": "integer"
                    },
                    "cached": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/payouts/earnings": {
      "get": {
        "tags": [
          "Payouts"
        ],
        "summary": "Get user earnings",
        "operationId": "getUserEarnings",
        "description": "Returns the authenticated creator's earnings summary in integer CENTS (#1499) — every field is suffixed `_cents` and must be divided by 100 before display. The target is always derived from the authenticated principal — any `?userId` query param is ignored (#1072). `total_cents` and `fees_cents` are lifetime aggregates from the canonical ledger. For creators with an active Stripe Connect account, `available_cents`, `pending_cents` and `withdrawn_cents` come from Stripe directly (`pending_cents` additionally includes platform-held net funds that haven't transferred yet). Creators without a Connect account see `available_cents` and `withdrawn_cents` as 0 and `pending_cents` equal to `total_cents` (everything sits on FundlyHub's platform balance awaiting onboarding). Rate limited to 100 requests per minute per account.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Earnings summary (all values are integer cents)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total_cents": {
                      "type": "integer",
                      "description": "Lifetime gross raised (canonical ledger figure), in cents."
                    },
                    "pending_cents": {
                      "type": "integer",
                      "description": "Funds not yet available for withdrawal, including platform-held net funds, in cents."
                    },
                    "available_cents": {
                      "type": "integer",
                      "description": "Balance available to withdraw now (from Stripe), in cents."
                    },
                    "withdrawn_cents": {
                      "type": "integer",
                      "description": "Funds already paid out toward the creator's bank (Stripe payouts in paid/in_transit), in cents."
                    },
                    "ready_to_pay_out_cents": {
                      "type": "integer",
                      "description": "The part of `pending_cents` that has settled at Stripe and is eligible for release now, in cents. 0 for creators without a connected account."
                    },
                    "fees_cents": {
                      "type": "integer",
                      "description": "Lifetime platform + processing fees, in cents."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/payouts/earnings/pending-breakdown": {
      "get": {
        "tags": [
          "Payouts"
        ],
        "summary": "Get pending earnings breakdown",
        "operationId": "getPendingBreakdown",
        "description": "Per-donation attribution of the creator's not-yet-available money, lazy-loaded by the Earnings tab's Pending-tile dialog (#1131). The target is always the authenticated principal. Each donation is classified into one of three states: `destination_charge_pending` (in the creator's own Stripe balance, not yet available; read from Stripe on each request, with Stripe's own `available_on`), `platform_held_unsettled` (platform balance, awaiting settlement), or `platform_held_settled` (platform balance, eligible for release now). `available_on` is 00:00 UTC of the release day. Rows already transferred to the creator's Stripe balance and rows under review are excluded from the platform-held states. Rate limited to 100 requests per minute per account.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Pending breakdown (all amounts in cents)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pending_breakdown": {
                      "type": "object",
                      "properties": {
                        "has_payout_account": {
                          "type": "boolean",
                          "description": "Whether the creator has a Stripe Connect account on file. False means everything below is sitting on the platform balance awaiting onboarding."
                        },
                        "total_cents": {
                          "type": "integer"
                        },
                        "destination_charge_cents": {
                          "type": "integer"
                        },
                        "platform_held_unsettled_cents": {
                          "type": "integer"
                        },
                        "platform_held_settled_cents": {
                          "type": "integer"
                        },
                        "dates_from_stripe": {
                          "type": "boolean",
                          "description": "True when the destination_charge_pending rows and their dates were read from the creator's Stripe account just now; false when Stripe could not be reached (those rows then carry no date)."
                        },
                        "release_schedule": {
                          "type": "array",
                          "description": "The destination_charge_pending money summed by the day Stripe makes it available, soonest first. Empty when dates_from_stripe is false.",
                          "items": {
                            "type": "object",
                            "properties": {
                              "available_on": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "amount_cents": {
                                "type": "integer"
                              },
                              "count": {
                                "type": "integer"
                              }
                            }
                          }
                        },
                        "donations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "donation_id": {
                                "type": "string",
                                "format": "uuid",
                                "nullable": true,
                                "description": "Null for a pending Stripe transaction that cannot be traced to a donation."
                              },
                              "amount_cents": {
                                "type": "integer"
                              },
                              "fundraiser_title": {
                                "type": "string",
                                "nullable": true
                              },
                              "fundraiser_slug": {
                                "type": "string",
                                "nullable": true
                              },
                              "state": {
                                "type": "string",
                                "enum": [
                                  "destination_charge_pending",
                                  "platform_held_unsettled",
                                  "platform_held_settled"
                                ]
                              },
                              "available_on": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                              },
                              "donated_at": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "donation",
                                  "adjustment",
                                  "other"
                                ],
                                "description": "donation for a payment in, adjustment for a refund or other negative entry, other for pending money beyond the transactions read."
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/stripe/accounts": {
      "get": {
        "tags": [
          "Payouts"
        ],
        "summary": "List Stripe connected accounts",
        "operationId": "getStripeAccounts",
        "description": "Returns the authenticated user's Stripe Connect accounts. Refreshes each account's enabled/onboarding flags from the Stripe API on read (transient downgrades are suppressed unless Stripe reports a concrete requirement). Returns an empty array if the user has no connected account. Rate limited to 100 requests per minute per account.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Connected accounts (array; empty if none)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "stripe_account_id": {
                        "type": "string"
                      },
                      "charges_enabled": {
                        "type": "boolean"
                      },
                      "payouts_enabled": {
                        "type": "boolean"
                      },
                      "details_submitted": {
                        "type": "boolean"
                      },
                      "onboarding_complete": {
                        "type": "boolean"
                      },
                      "country": {
                        "type": "string"
                      },
                      "default_currency": {
                        "type": "string"
                      },
                      "created_at": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "requirements": {
                        "type": "object",
                        "nullable": true,
                        "description": "Stripe account requirements (currently_due / past_due / disabled_reason)."
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/stripe/connect/accounts": {
      "post": {
        "tags": [
          "Payouts"
        ],
        "summary": "Start or resume Stripe Connect onboarding",
        "operationId": "createConnectedAccount",
        "description": "Creates the caller's Stripe Connect account if they do not have one, then returns a **fresh onboarding link** in either case. Send the creator to `onboardingUrl`; the link is single-use and short-lived, so call this again rather than caching it.\nIf the stored account no longer exists at Stripe, a new account is created transparently. Requires a bearer session; rate limited to 100 requests per minute per account.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "businessType": {
                    "type": "string",
                    "default": "individual",
                    "description": "Passed through to Stripe when the account is created."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account id plus a fresh onboarding link",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accountId": {
                      "type": "string",
                      "example": "acct_1AbCdEfGhIjKlMnO"
                    },
                    "onboardingUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "status": {
                      "type": "string",
                      "description": "Always `pending` — read the real state from `GET /stripe/accounts`."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/stripe/connect/accounts/{accountId}/status": {
      "get": {
        "tags": [
          "Payouts"
        ],
        "summary": "Get connected-account status",
        "operationId": "getConnectedAccountStatus",
        "description": "Reads one connected account straight from Stripe and refreshes the cached flags on FundlyHub's side. The account is addressed by its Stripe id, which you get from `GET /stripe/accounts`.\n**Ownership:** `accountId` must be a connected account the caller owns: their own account, or an organization's account where the caller holds `org.read_payouts` in that organization. Any other id, including one that does not exist, returns `404`; the response does not distinguish the two.\nThis is a pure read: it never moves money. Requires a bearer session; rate limited to 100 requests per minute per account.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "accountId",
            "in": "path",
            "required": true,
            "description": "Stripe connected-account id.",
            "schema": {
              "type": "string",
              "example": "acct_1AbCdEfGhIjKlMnO"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Account status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "complete",
                        "pending"
                      ],
                      "description": "`complete` only when charges and payouts are both enabled."
                    },
                    "chargesEnabled": {
                      "type": "boolean"
                    },
                    "payoutsEnabled": {
                      "type": "boolean"
                    },
                    "detailsSubmitted": {
                      "type": "boolean"
                    },
                    "requirements": {
                      "type": "object",
                      "nullable": true,
                      "description": "Stripe's requirements object (currently_due / past_due / disabled_reason)."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No connected account with this id is owned by the caller (it does not exist, or it belongs to someone else).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/stripe/connect/sessions": {
      "post": {
        "tags": [
          "Payouts"
        ],
        "summary": "Create an embedded-components account session",
        "operationId": "createAccountSession",
        "description": "Mints a Stripe Account Session client secret for the embedded Connect components (`account_onboarding`, `payouts`, `payments`). Omit `accountId` to use the caller's most recent connected account.\n**Ownership:** an explicit `accountId` must be a connected account the caller owns: their own account, or an organization's account where the caller holds `org.manage_payouts` in that organization. Any other id, including one that does not exist, returns `404` and no session is created.\nRequires a bearer session; rate limited to 100 requests per minute per account.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "accountId": {
                    "type": "string",
                    "description": "Defaults to the caller's most recently created connected account. When set, it must be an account the caller owns (see Ownership above)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account session",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "clientSecret": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`accountId` was omitted and the caller has no connected account, or `accountId` names an account the caller does not own (or one that does not exist).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/stripe/connect/transfers": {
      "get": {
        "tags": [
          "Payouts"
        ],
        "summary": "List transfers to the creator's Stripe balance",
        "operationId": "listConnectTransfers",
        "description": "Platform → creator transfers recorded for the authenticated caller, newest first. These are movements onto the creator's Stripe balance; payouts to their bank are a separate list (`GET /stripe/connect/payouts`). Requires a bearer session; rate limited to 100 requests per minute per account.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transfer rows (bare array)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "stripe_transfer_id": {
                        "type": "string"
                      },
                      "donation_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "fundraiser_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "amount_cents": {
                        "type": "integer"
                      },
                      "application_fee_cents": {
                        "type": "integer"
                      },
                      "currency": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "pending",
                          "paid",
                          "failed",
                          "reversed"
                        ]
                      },
                      "failure_reason": {
                        "type": "string",
                        "nullable": true
                      },
                      "created_at": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "arrived_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/stripe/connect/payouts": {
      "get": {
        "tags": [
          "Payouts"
        ],
        "summary": "List payouts to the creator's bank",
        "operationId": "listConnectPayouts",
        "description": "Payouts from the creator's Stripe balance to their bank account. Read live from Stripe so the list matches what the creator sees in their bank; if Stripe is unreachable the endpoint falls back to FundlyHub's own records, which only cover payouts this API initiated or that a webhook recorded.\n`arrival_date` and `created` are **Unix timestamps in seconds**, not ISO strings. Stripe paginates by cursor, so `offset` only applies to the database fallback. Requires a bearer session; rate limited to 100 requests per minute per IP.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Only honoured by the database fallback path.",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Payout rows (bare array)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "example": "po_1AbCdEfGhIjKlMnO"
                      },
                      "amount": {
                        "type": "integer",
                        "description": "Amount in cents."
                      },
                      "currency": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string",
                        "description": "Stripe payout status (`paid`, `pending`, `in_transit`, `failed`, `canceled`)."
                      },
                      "arrival_date": {
                        "type": "integer",
                        "nullable": true,
                        "description": "Unix timestamp (seconds)."
                      },
                      "created": {
                        "type": "integer",
                        "description": "Unix timestamp (seconds)."
                      },
                      "destination": {
                        "type": "string",
                        "nullable": true,
                        "description": "Stripe external-account id. Always null on the database fallback path."
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Payouts"
        ],
        "summary": "Withdraw available balance to the bank",
        "operationId": "createConnectPayout",
        "description": "Initiates a standard payout from the caller's connected Stripe balance to their bank account. Omit `amountCents` to withdraw the full available balance.\nThe minimum payout is **$1.00 (100 cents)** and the amount may not exceed the available balance. The caller must have a payout-enabled connected account. Gated by the `features.payouts` flag; requires a bearer session; rate limited to 100 requests per minute per account.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amountCents": {
                    "type": "integer",
                    "minimum": 100,
                    "description": "Defaults to the entire available balance."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payout initiated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "payoutId": {
                      "type": "string",
                      "example": "po_1AbCdEfGhIjKlMnO"
                    },
                    "amount": {
                      "type": "integer",
                      "description": "Amount in cents."
                    },
                    "currency": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "arrivalDate": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "No payout-enabled account, zero available balance, amount below the $1.00 minimum, amount above the available balance, or Stripe rejected the payout (its message and `code` are returned).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Payouts are disabled (`features.payouts` is off).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/stripe/connect/payouts/reconcile": {
      "post": {
        "tags": [
          "Payouts"
        ],
        "summary": "Refresh payouts and withdrawals from Stripe",
        "operationId": "reconcileConnectPayouts",
        "description": "Re-reads every payout of the caller's connected Stripe account and repairs FundlyHub's own records of them: the payout rows, the link between each payout and the donations it carried, and the payout entries in the financial ledger. These are what a campaign's Updates feed (`GET /projects/{fundraiserId}/updates`) lists as withdrawals, so a payout Stripe made on its automatic schedule shows up there without waiting for a webhook. Moves no money. Never a dry run.\nOmit `accountId` to refresh the caller's own account. An `acct_…` id of an organization account the caller can manage payouts for is also accepted; any other id answers 404, like an unknown one.\nRequires a bearer session; rate limited to 100 requests per minute per account, and to one refresh per account per minute (429 with `Retry-After`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "accountId": {
                    "type": "string",
                    "example": "acct_1AbCdEfGhIjKlMnO",
                    "description": "Defaults to the caller's own connected account."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Refresh result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accountId": {
                      "type": "string",
                      "example": "acct_1AbCdEfGhIjKlMnO"
                    },
                    "payoutsFound": {
                      "type": "integer",
                      "description": "Payouts Stripe lists for the account."
                    },
                    "payoutRowsInserted": {
                      "type": "integer",
                      "description": "Payouts FundlyHub had no record of until now."
                    },
                    "payoutRowsUpdated": {
                      "type": "integer",
                      "description": "Payouts whose recorded status or arrival date changed."
                    },
                    "donationsStamped": {
                      "type": "integer",
                      "description": "Donations newly linked to the payout that carried them."
                    },
                    "donationsCleared": {
                      "type": "integer",
                      "description": "Donations unlinked from a failed or canceled payout."
                    },
                    "balanceTransactionsBackfilled": {
                      "type": "integer",
                      "description": "Donations whose Stripe balance transaction was traced so they could be linked."
                    },
                    "ledgerRowsWritten": {
                      "type": "integer",
                      "description": "Payout entries written to the financial ledger."
                    },
                    "errors": {
                      "type": "integer",
                      "description": "Steps that failed and will be retried by the next refresh."
                    },
                    "payouts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "example": "po_1AbCdEfGhIjKlMnO"
                          },
                          "status": {
                            "type": "string",
                            "description": "Stripe payout status (`paid`, `pending`, `in_transit`, `failed`, `canceled`)."
                          },
                          "amount": {
                            "type": "integer",
                            "description": "Amount in cents."
                          },
                          "currency": {
                            "type": "string"
                          },
                          "row": {
                            "type": "string",
                            "enum": [
                              "inserted",
                              "updated",
                              "unchanged"
                            ]
                          },
                          "donationsStamped": {
                            "type": "integer"
                          },
                          "ledgerRowsWritten": {
                            "type": "integer"
                          },
                          "ok": {
                            "type": "boolean"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "The caller has no connected account, or `accountId` is not one they manage.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited, or this account was refreshed less than a minute ago.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/stripe/connect/payout-settings": {
      "get": {
        "tags": [
          "Payouts"
        ],
        "summary": "Get payout methods and schedule",
        "operationId": "getPayoutSettings",
        "description": "The bank accounts and debit cards attached to the caller's connected account, plus the payout schedule Stripe currently applies. Requires a bearer session; rate limited to 100 requests per minute per account.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Payout methods and schedule",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "payoutMethods": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "bank_account",
                              "card"
                            ]
                          },
                          "bankName": {
                            "type": "string",
                            "nullable": true
                          },
                          "last4": {
                            "type": "string"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "country": {
                            "type": "string"
                          },
                          "routingNumber": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string"
                          },
                          "defaultForCurrency": {
                            "type": "boolean"
                          },
                          "brand": {
                            "type": "string",
                            "nullable": true,
                            "description": "Card brand. Only present on `card` entries."
                          }
                        }
                      }
                    },
                    "schedule": {
                      "$ref": "#/components/schemas/PayoutSchedule"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "The caller has no connected account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/stripe/connect/payout-schedule": {
      "put": {
        "tags": [
          "Payouts"
        ],
        "summary": "Update the payout schedule",
        "operationId": "updatePayoutSchedule",
        "description": "Sets how often Stripe pays the creator out. `weekly` requires `weeklyAnchor` (a weekday name), `monthly` requires `monthlyAnchor` (1–31); `manual` and `daily` take neither. Requires a bearer session; rate limited to 100 requests per minute per account.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "interval"
                ],
                "properties": {
                  "interval": {
                    "type": "string",
                    "enum": [
                      "manual",
                      "daily",
                      "weekly",
                      "monthly"
                    ]
                  },
                  "weeklyAnchor": {
                    "type": "string",
                    "example": "monday",
                    "description": "Required when `interval` is `weekly`."
                  },
                  "monthlyAnchor": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 31,
                    "description": "Required when `interval` is `monthly`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The schedule Stripe now applies",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PayoutSchedule"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid `interval`, a missing anchor, or Stripe rejected the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "The caller has no connected account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/stripe/connect/express-login": {
      "get": {
        "tags": [
          "Payouts"
        ],
        "summary": "Get a Stripe dashboard link",
        "operationId": "getExpressLoginLink",
        "description": "Returns a URL into Stripe for the caller's connected account — a single-use Express login link deep-linked to payouts for Express accounts, or the Connect dashboard URL for other account types. Do not cache it. Requires a bearer session; rate limited to 100 requests per minute per account.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Dashboard URL",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Stripe refused to mint a login link for this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "The caller has no connected account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{fundraiserId}/milestones": {
      "get": {
        "tags": [
          "Milestones"
        ],
        "summary": "List milestones",
        "operationId": "listMilestones",
        "description": "Get all milestones for a fundraiser, earliest due date first. Readable exactly when `GET /fundraisers/{id}` is: a campaign that is not `active`, `paused` or `ended`, is `private`, or has been deleted answers `404` to everyone but its owner. Authentication is optional.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "fundraiserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Overlay the stored translation of title and description for this language, when one exists.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of milestones",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "milestones": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Milestone"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "tags": [
          "Milestones"
        ],
        "summary": "Create milestone",
        "operationId": "createMilestone",
        "description": "Add a milestone to a campaign. Only the campaign owner may post one, the caller's email must be verified, and the endpoint is gated by the `features.milestones` flag.\n**The request body is camelCase** (`targetAmountCents`, `dueDate`) while the response row is snake_case (`target_amount_cents`, `due_date`). Both are in CENTS; `target_amount_cents` is also accepted in the body. The dollars-era `targetAmount` is not, and is ignored.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "fundraiserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title"
                ],
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string",
                    "nullable": true
                  },
                  "targetAmountCents": {
                    "type": "number",
                    "nullable": true,
                    "description": "Optional. When present it must be greater than 0."
                  },
                  "dueDate": {
                    "type": "string",
                    "format": "date",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Milestone created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Milestone"
                }
              }
            }
          },
          "400": {
            "description": "Title missing, or `targetAmountCents` is not a positive integer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not the campaign owner, email not verified, or milestones are disabled (`features.milestones` is off).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/milestones/{id}": {
      "get": {
        "tags": [
          "Milestones"
        ],
        "summary": "Get milestone",
        "operationId": "getMilestone",
        "description": "A single milestone by id. Public when its campaign is: a milestone of a campaign that is not `active`, `paused` or `ended`, is `private`, or has been deleted answers `404` to everyone but the campaign's owner. Authentication is optional.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Overlay the stored translation of title and description for this language, when one exists.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Milestone details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Milestone"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "tags": [
          "Milestones"
        ],
        "summary": "Update milestone",
        "operationId": "updateMilestone",
        "description": "Partial update of a milestone. Only the owner of the parent campaign may update it, and the caller's email must be verified. Send only the fields you are changing; an empty body answers `400`.\n**The request body is camelCase** (`targetAmountCents`, `dueDate`, `completedAt`) while the response row is snake_case. Setting `completedAt` is what marks a milestone complete.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string",
                    "nullable": true
                  },
                  "targetAmountCents": {
                    "type": "number",
                    "nullable": true
                  },
                  "dueDate": {
                    "type": "string",
                    "format": "date",
                    "nullable": true
                  },
                  "completedAt": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Milestone updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Milestone"
                }
              }
            }
          },
          "400": {
            "description": "No fields to update, empty title, or non-positive `targetAmountCents`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not the owner of the parent campaign, or email not verified.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Milestones"
        ],
        "summary": "Delete milestone",
        "operationId": "deleteMilestone",
        "description": "Deletes a milestone. Only the owner of the parent campaign may delete it.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not the owner of the parent campaign.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/payments/create-intent": {
      "post": {
        "tags": [
          "Payments"
        ],
        "summary": "Create payment intent",
        "operationId": "createPaymentIntent",
        "description": "Create a Stripe PaymentIntent for a donation. This is the first half of\nthe donation flow; confirm it with `POST /payments/confirm` once Stripe\nreports the payment succeeded.\n\n**Every field is snake_case, and every amount is in integer cents.**\n`amount_cents` is the donation itself; `tip_amount_cents` is the\noptional tip to FundlyHub for personal fundraisers. For a nonprofit or\nchurch beneficiary, omit it or send zero; nonzero tips are rejected. The charge Stripe sees is\n`amount_cents + tip_amount_cents`, and it must clear Stripe's $0.50\n(50 cent) minimum.\n\n`amount_cents` was called `amount`. The value was always cents — only\nthe name has changed, so that it says so.\n\n**`fundraiser_id` decides where the money goes.** Omit it and the\nPaymentIntent is created against the platform account with no campaign\nattribution — the donation is not credited to any campaign and no\ntransfer to a creator is scheduled. It is optional in the sense that\nthe request succeeds without it, not in the sense that it is safe to\nleave out.\n\nThe campaign must be `active` and not deleted; anything else is\nrejected (`404` if the id is unknown, `409` if the campaign exists but\ncannot accept money).\n\nAuthentication is optional — a signed-in donor gets the donation linked\nto their account, an anonymous one does not. reCAPTCHA is enforced\n(see below), except that a signed-in session whose email is verified\nmay omit the token. While donations are switched off platform-wide the\nrequest is refused with `403` and no PaymentIntent is created.\nA personal campaign reserves its pending donation under the fundraiser row\nlock before the provider request, preventing concurrent owner/beneficiary\nreassignment. The same row is enriched with the PaymentIntent before its\nclient secret is returned. Unconfirmed intents whose reservation cannot\nbe saved are canceled and the request fails; no usable secret is returned.\nFailed preparation remains a failed payment attempt without increasing\nraised totals. Nonprofit checkout keeps its existing immutable reservation.\n",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "x-recaptcha-token",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "reCAPTCHA v3 token, action `payment`. Required unless supplied as `recaptcha_token` in the body, or the caller is a signed-in session with a verified email. Missing (guest or unverified) → `400`; failing the score threshold → `403`, whoever sent it."
          },
          {
            "name": "x-app-attest-key-id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "iOS only. The App Attest key id (standard base64, as `DCAppAttestService.generateKey` returns it) of a key registered with `POST /app-attest/attest`. Send with `x-app-attest-assertion`."
          },
          {
            "name": "x-app-attest-assertion",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "iOS only. base64 of the assertion from `generateAssertion(keyId, clientDataHash: SHA256(raw request body))`. The body must carry a fresh `app_attest_challenge`. A valid assertion replaces the reCAPTCHA token; the headers alone never do. An invalid one answers `403` with `code` `APP_ATTEST_INVALID`, `APP_ATTEST_KEY_UNKNOWN` (attest a new key) or `APP_ATTEST_CHALLENGE_INVALID` (fetch a new challenge), unless the request passes reCAPTCHA some other way."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "amount_cents"
                ],
                "properties": {
                  "amount_cents": {
                    "type": "integer",
                    "description": "Donation amount in integer cents. Must be a whole number — a fractional value is rejected with `400`. Renamed from `amount`; the value was always cents, the name now says so.",
                    "example": 5000
                  },
                  "currency": {
                    "type": "string",
                    "default": "usd",
                    "example": "usd"
                  },
                  "fundraiser_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "The campaign to credit. See the note above — omitting this silently sends the money to the platform balance."
                  },
                  "checkout_key": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required for a nonprofit campaign. Reuse the same key only for an unchanged checkout retry; use a new key for a new gift. Nonprofit gifts route to the organization's verified connected account. Unavailable or disabled nonprofit accounts are refused with 409 and never fall back to the organizer's personal account."
                  },
                  "tip_amount_cents": {
                    "type": "integer",
                    "default": 0,
                    "description": "Optional tip to FundlyHub for personal donations, in integer cents. Must be omitted or zero for nonprofit and church beneficiaries.",
                    "example": 500
                  },
                  "tip_percent": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "How the tip was expressed, when it was chosen as a percentage rather than typed as an amount. Recorded only so an abandoned-donation reminder can restore the widget the way the donor left it; it does not affect the charge. Anything that is not a whole number in 0–100 is stored as null and read as \"typed\"."
                  },
                  "donor_email": {
                    "type": "string",
                    "format": "email"
                  },
                  "donor_name": {
                    "type": "string"
                  },
                  "is_anonymous": {
                    "type": "boolean",
                    "default": false
                  },
                  "donor_timezone": {
                    "type": "string",
                    "description": "IANA zone, e.g. `America/New_York`. Used to time reminder emails.",
                    "example": "America/New_York"
                  },
                  "donor_locale": {
                    "type": "string",
                    "description": "BCP-47 tag used to localise reminder emails.",
                    "example": "en"
                  },
                  "recaptcha_token": {
                    "type": "string",
                    "description": "Alternative to the `x-recaptcha-token` header."
                  },
                  "app_attest_challenge": {
                    "type": "string",
                    "description": "iOS App Attest only: a challenge from `POST /app-attest/challenge`, single use. Required when the App Attest headers are sent."
                  }
                }
              },
              "examples": {
                "campaignDonation": {
                  "summary": "$50 donation with a $5 tip",
                  "value": {
                    "amount_cents": 5000,
                    "currency": "usd",
                    "fundraiser_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                    "tip_amount_cents": 500,
                    "tip_percent": 10,
                    "donor_email": "donor@example.com",
                    "donor_name": "Alex Rivera",
                    "is_anonymous": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "PaymentIntent created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "client_secret": {
                      "type": "string",
                      "description": "Pass to Stripe.js to collect the payment."
                    },
                    "payment_intent_id": {
                      "type": "string",
                      "description": "Hand this back to `POST /payments/confirm`.",
                      "example": "pi_3abc123def456"
                    },
                    "amount_cents": {
                      "type": "integer",
                      "description": "Total charged, in cents (`amount_cents` + `tip_amount_cents`).",
                      "example": 5500
                    },
                    "stripe_fee_cents": {
                      "type": "integer",
                      "description": "Processing fee in cents (2.9% + 30¢).",
                      "example": 190
                    },
                    "net_amount_cents": {
                      "type": "integer",
                      "description": "What reaches the creator, in cents.",
                      "example": 5310
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Amount is not whole cents, is below Stripe's 50-cent minimum, or the fee would consume the whole donation; or the reCAPTCHA token is missing on a request that is not from a verified, signed-in session.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Donations are switched off (`features.donations` is off; the body carries `feature_key`), reCAPTCHA verification failed, or an App Attest assertion was invalid (`code` `APP_ATTEST_*`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`fundraiser_id` does not match any campaign.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The campaign exists but cannot accept money — it is draft, paused, ended, pending or rejected review, or deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/app-attest/challenge": {
      "post": {
        "tags": [
          "App Attest"
        ],
        "summary": "Issue an App Attest challenge",
        "operationId": "createAppAttestChallenge",
        "description": "A random, single-use challenge for the iOS app, valid for\n`expires_in_seconds` (300). Fetch one before attesting a key and one\nbefore every donation request that carries an App Attest assertion.\n\nPublic (guests call it). Rate limited to 30 a minute per address.\nAnswers `503` with `code: APP_ATTEST_DISABLED` while App Attest is not\nconfigured on the server.\n",
        "security": [
          {}
        ],
        "responses": {
          "200": {
            "description": "A fresh challenge (`Cache-Control: no-store`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "challenge",
                    "expires_in_seconds"
                  ],
                  "properties": {
                    "challenge": {
                      "type": "string",
                      "description": "base64url (no padding) of 32 random bytes — 43 characters. Use it verbatim.",
                      "example": "q7uE3fP9yK2sV1xW4zA6bC8dE0fG2hJ4kL6mN8pR0tU"
                    },
                    "expires_in_seconds": {
                      "type": "integer",
                      "example": 300
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "App Attest is not enabled (`code: APP_ATTEST_DISABLED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/app-attest/attest": {
      "post": {
        "tags": [
          "App Attest"
        ],
        "summary": "Register an App Attest key",
        "operationId": "attestAppAttestKey",
        "description": "Register a device key with its attestation. The server verifies the\ncertificate chain to Apple's App Attestation Root CA, that the\nattestation was made for `challenge`\n(`clientDataHash = SHA256(UTF-8 bytes of challenge)`), the App ID, the\nenvironment, a zero counter and that `key_id` is the key's hash, then\nstores the public key. Attest once per key; attesting a key that is\nalready registered changes nothing.\n\nPublic (guests call it). Rate limited to 10 a minute per address.\n",
        "security": [
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "key_id",
                  "attestation",
                  "challenge"
                ],
                "properties": {
                  "key_id": {
                    "type": "string",
                    "description": "The key id from `DCAppAttestService.generateKey` (standard base64)."
                  },
                  "attestation": {
                    "type": "string",
                    "description": "base64 of the attestation object from `attestKey`."
                  },
                  "challenge": {
                    "type": "string",
                    "description": "An unused challenge from `POST /app-attest/challenge`, exactly as received."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Key verified and registered."
          },
          "400": {
            "description": "Invalid input or attestation (`code: APP_ATTEST_INVALID`, `reason` names the failed check), or the challenge is unknown, expired or used (`code: APP_ATTEST_CHALLENGE_INVALID`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "App Attest is not enabled (`code: APP_ATTEST_DISABLED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/payments/confirm": {
      "post": {
        "tags": [
          "Payments"
        ],
        "summary": "Confirm payment",
        "operationId": "confirmPayment",
        "description": "Confirm a PaymentIntent that Stripe has reported as `succeeded`, and\nsettle the donation record.\n\nThe field is `payment_intent_id` (snake_case) — the value returned as\n`payment_intent_id` by `POST /payments/create-intent`.\n\nSafe to retry: a PaymentIntent whose donation is already `paid` is\nreturned as-is rather than double-counted. Stripe webhooks reconcile the\nsame donation independently, so a client that never reaches this call\nstill ends up with a settled donation — calling it just makes the\nreceipt available immediately.\n",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "payment_intent_id"
                ],
                "properties": {
                  "payment_intent_id": {
                    "type": "string",
                    "example": "pi_3abc123def456"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment confirmed; the settled donation is returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/Donation"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "campaign_title": {
                              "type": "string"
                            },
                            "campaign_slug": {
                              "type": "string"
                            },
                            "card_brand": {
                              "type": "string",
                              "nullable": true
                            },
                            "card_last4": {
                              "type": "string",
                              "nullable": true
                            },
                            "payment_method_type": {
                              "type": "string",
                              "nullable": true
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`payment_intent_id` missing, or the PaymentIntent has not succeeded yet (its Stripe status is echoed in the message).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/ai/enhance-text": {
      "post": {
        "tags": [
          "AI"
        ],
        "summary": "Enhance text",
        "operationId": "enhanceText",
        "description": "Rewrite or generate one campaign field with an LLM. Requires a bearer session and is gated by the `features.ai_text_enhancement` flag. Throughput is capped per user (10 requests per minute by default).\n`context.field` selects the system prompt and must be one of `summary`, `story` or `milestone`; any other value falls back to the `summary` prompt. `text` is capped at the server's maximum length.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "action",
                  "text",
                  "context"
                ],
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "generate",
                      "refine",
                      "expand",
                      "shorten"
                    ],
                    "description": "An unrecognised action answers `400`."
                  },
                  "text": {
                    "type": "string",
                    "description": "The current text, or the starting idea when `action` is `generate`."
                  },
                  "context": {
                    "type": "object",
                    "required": [
                      "field"
                    ],
                    "description": "Campaign context folded into the prompt. `field` is required; the rest are optional hints.",
                    "properties": {
                      "field": {
                        "type": "string",
                        "enum": [
                          "summary",
                          "story",
                          "milestone"
                        ]
                      },
                      "title": {
                        "type": "string"
                      },
                      "category": {
                        "type": "string"
                      },
                      "goalAmount": {
                        "type": "number"
                      },
                      "beneficiaryName": {
                        "type": "string"
                      },
                      "milestoneTitle": {
                        "type": "string"
                      },
                      "milestoneAmount": {
                        "type": "number"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Enhanced text",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enhancedText": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing `action`, `text` or `context.field`; unknown action; or text too long.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "AI text enhancement is disabled (`features.ai_text_enhancement` is off).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "description": "The AI provider is not configured or is unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/ai/campaign-chat": {
      "post": {
        "tags": [
          "AI"
        ],
        "summary": "Campaign AI chat",
        "operationId": "campaignAiChat",
        "description": "Conversational assistant for the campaign-creation wizard. Requires a\nbearer session; throughput is capped per user (10 requests per minute\nby default).\n\n**The response is a Server-Sent Events stream** (`text/event-stream`),\nnot a JSON document. Each event carries one JSON object:\n\n- `{\"type\":\"token\",\"content\":\"…\"}` — one streamed text token\n- `{\"type\":\"campaign_data\",\"data\":{…}}` — campaign fields the model extracted\n- `{\"type\":\"done\"}` — stream complete\n- `{\"type\":\"error\",\"message\":\"…\"}` — the stream failed mid-flight\n\nOnly the most recent 30 messages of `messages` are sent to the model.\n",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "messages"
                ],
                "properties": {
                  "messages": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "object",
                      "required": [
                        "role",
                        "content"
                      ],
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": [
                            "user",
                            "assistant"
                          ]
                        },
                        "content": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "extractedData": {
                    "type": "object",
                    "description": "Fields the user has already filled in, so the assistant does not ask for them again.",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Server-Sent Events stream of tokens and extracted campaign data.",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "`messages` missing or empty.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "description": "The AI provider is not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/ai/detect-category": {
      "post": {
        "tags": [
          "AI"
        ],
        "summary": "Detect category",
        "operationId": "detectCategory",
        "description": "Classifies a campaign into one of the platform's categories. Requires a bearer session; throughput is capped per user (10 requests per minute by default).\nSend any combination of `title`, `summary` and `description` — they are joined, truncated to 500 characters and classified. At least one must be present and the joined text must be 3 characters or longer.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "summary": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Detected category",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "categoryName": {
                      "type": "string",
                      "description": "The matched category name. If the model answers with something outside the catalogue, its raw answer is returned instead — match it against `GET /categories` before relying on it."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "No usable text supplied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "description": "The AI provider is not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/capabilities": {
      "get": {
        "tags": [
          "RBAC"
        ],
        "summary": "Get current user capabilities",
        "operationId": "getCurrentCapabilities",
        "description": "Scope-aware permissions and roles for the authenticated user. Requires a bearer session and nothing else — this is the endpoint a client should use to decide what to show. The answer always includes the caller's global roles; with an `organization` or `fundraiser` scope it adds the roles held in that scope. A bare object, not wrapped in `data`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "scopeType",
            "in": "query",
            "required": false,
            "description": "Defaults to `global`. `scopeId` is required for the other two.",
            "schema": {
              "type": "string",
              "enum": [
                "global",
                "organization",
                "fundraiser"
              ],
              "default": "global"
            }
          },
          {
            "name": "scopeId",
            "in": "query",
            "required": false,
            "description": "The organization or fundraiser id. Required unless `scopeType` is `global`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User capabilities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "permissions": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "roles": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "scope": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string"
                        },
                        "id": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    },
                    "fetchedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When this answer should be considered stale and fetched again."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/stats": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "Get platform statistics",
        "operationId": "getPlatformStats",
        "description": "Public endpoint returning aggregate platform stats. A bare object, not wrapped in `data`. Every figure is over the **counted campaigns**: approved, public, not deleted, and active, pending, paused or ended. A draft, private or deleted campaign is part of none of them.",
        "responses": {
          "200": {
            "description": "Platform statistics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "totalRaisedCents": {
                      "type": "integer",
                      "description": "What reached the creators of the counted campaigns, in integer CENTS: each counted gift (paid or refunded) at its donation less the Stripe fee, never the tip. The sum of the campaign cards, and the same figure as `raised_for_causes_cents` on `GET /platform/numbers`.",
                      "example": 1234560000
                    },
                    "activeCampaigns": {
                      "type": "integer",
                      "description": "Counted campaigns with status `active`."
                    },
                    "totalSupporters": {
                      "type": "integer",
                      "description": "Distinct donors of the counted gifts to the counted campaigns: a signed-in donor by account, a guest by email (trimmed, case-insensitive), an anonymous donor by their anonymous identity."
                    },
                    "totalCreators": {
                      "type": "integer",
                      "description": "Distinct owners of a counted campaign."
                    },
                    "totalGoalCents": {
                      "type": "integer",
                      "description": "Sum of the goals of the counted campaigns, in integer CENTS.",
                      "example": 5000000000
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/trust/status": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "Get trust center status",
        "operationId": "getTrustStatus",
        "description": "Live security and compliance status for the Trust Center. Public; cached for up to 15 minutes.",
        "responses": {
          "200": {
            "description": "Trust status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "overallStatus": {
                          "type": "string",
                          "enum": [
                            "operational",
                            "degraded",
                            "outage"
                          ]
                        },
                        "lastChecked": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "controls": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "icon": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "active",
                                  "degraded",
                                  "inactive"
                                ]
                              },
                              "lastChecked": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "details": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "The status could not be assembled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/location/zip/{zipCode}": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "ZIP code lookup",
        "operationId": "lookupZipCode",
        "description": "Look up city and state from a 5-digit US ZIP code. Public; answers are cached. The top-level location keeps the first upstream place for existing callers; places lists every unique city/state choice in upstream order.",
        "parameters": [
          {
            "name": "zipCode",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "95630"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Location data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "zipCode": {
                      "type": "string"
                    },
                    "city": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "stateAbbreviation": {
                      "type": "string"
                    },
                    "places": {
                      "type": "array",
                      "minItems": 1,
                      "description": "Unique city/state choices for this ZIP, with the top-level location first.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "zipCode": {
                            "type": "string"
                          },
                          "city": {
                            "type": "string"
                          },
                          "state": {
                            "type": "string"
                          },
                          "stateAbbreviation": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The ZIP code is not exactly 5 digits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/notifications": {
      "get": {
        "tags": [
          "Notifications"
        ],
        "summary": "List notifications",
        "operationId": "getNotifications",
        "description": "Returns the authenticated user's notifications, newest first, together with the unread count. The count always excludes archived rows, even when `archived=true` is requested.\nThere is no offset pagination here — raise `limit` (max 100) to see further back.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "archived",
            "in": "query",
            "required": false,
            "description": "Pass \"true\" to return archived notifications instead of the active ones. Any other value returns the active ones.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Notifications payload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "notifications": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Notification"
                      }
                    },
                    "unreadCount": {
                      "type": "integer",
                      "description": "Unread, non-archived notifications for this user."
                    },
                    "updatesUnreadCount": {
                      "type": "integer",
                      "nullable": true,
                      "description": "Unread campaign updates for this user — the same number as `unread_count` on `GET /me/campaign-updates`. The Activity badge is `unreadCount + updatesUnreadCount`, from this one request (`limit=1` keeps it cheap to poll). `null` when that count could not be computed this time: keep the previous value rather than showing zero."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "delete": {
        "tags": [
          "Notifications"
        ],
        "summary": "Delete notifications",
        "operationId": "deleteNotifications",
        "description": "Permanently deletes the given notifications for the authenticated user.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ids"
                ],
                "properties": {
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deletion result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "deleted": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/notifications/mark-read": {
      "patch": {
        "tags": [
          "Notifications"
        ],
        "summary": "Mark notifications as read",
        "operationId": "markNotificationsRead",
        "description": "Marks the given notification ids as read for the authenticated user.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ids"
                ],
                "properties": {
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "updated": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/notifications/read-all": {
      "put": {
        "tags": [
          "Notifications"
        ],
        "summary": "Mark all notifications as read",
        "operationId": "markAllNotificationsRead",
        "description": "Marks all of the authenticated user's notifications as read.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Update result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "updated": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/notifications/{id}/read": {
      "put": {
        "tags": [
          "Notifications"
        ],
        "summary": "Mark one notification as read",
        "operationId": "markOneNotificationRead",
        "description": "Marks a single notification as read for the authenticated user.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Update result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "updated": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/notifications/archive": {
      "patch": {
        "tags": [
          "Notifications"
        ],
        "summary": "Archive notifications",
        "operationId": "archiveNotifications",
        "description": "Archives the given notification ids for the authenticated user.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ids"
                ],
                "properties": {
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Archive result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "archived": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/me/campaign-updates": {
      "get": {
        "tags": [
          "Notifications"
        ],
        "summary": "List my campaign updates",
        "operationId": "getMyCampaignUpdates",
        "description": "Updates posted on campaigns the authenticated user is connected to, newest first, each with its read state, plus the unread count. Read state is kept on the server, so it is the same on every device.\nA campaign is included when the user follows its holder — the person running a personal campaign, or the organization an org campaign belongs to — and the campaign is public and active or ended; or when the user has a paid gift to it and it is active, ended or paused and not private (an unlisted campaign a donor holds the link to is included). The user's own campaigns and own updates are never included, nor deleted campaigns or withdrawn updates.\nAn update posted before the user started following or first gave is returned with `is_read: true` and never counts as unread.\nPaged by an opaque keyset cursor: pass `next_cursor` back as `cursor` until it is `null`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The `next_cursor` of the previous page. A cursor this API did not mint is a 400.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Overlay translations into this locale, as `GET /projects/{fundraiserId}/updates` does.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of the feed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CampaignUpdateFeedItem"
                      }
                    },
                    "next_cursor": {
                      "type": "string",
                      "nullable": true
                    },
                    "unread_count": {
                      "type": "integer",
                      "description": "Unread updates across the whole feed, not just this page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/me/campaign-updates/read-all": {
      "put": {
        "tags": [
          "Notifications"
        ],
        "summary": "Mark all my campaign updates as read",
        "operationId": "markAllMyCampaignUpdatesRead",
        "description": "Marks every unread update in the user's feed read. With `until`, only updates posted at or before that instant (inclusive to the millisecond), so clearing the list a client is showing does not also clear an update that arrived after it was fetched.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "until": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Typically the `created_at` of the newest update the client is showing."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update result and the new unread count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "updated": {
                      "type": "integer",
                      "description": "How many updates this call marked read."
                    },
                    "unread_count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/me/campaign-updates/{updateId}/read": {
      "put": {
        "tags": [
          "Notifications"
        ],
        "summary": "Mark one campaign update as read",
        "operationId": "markMyCampaignUpdateRead",
        "description": "Marks one update read for the authenticated user. Idempotent: an update already read answers `updated: 0` and keeps its first `read_at`. Any existing, non-withdrawn update may be marked, whether or not it is in the user's feed, so a client can mark an update read wherever it was opened. There is no \"mark unread\", as for notifications.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "updateId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Update result and the new unread count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "updated": {
                      "type": "integer",
                      "enum": [
                        0,
                        1
                      ]
                    },
                    "unread_count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such update, or it was withdrawn",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/subscriptions/status": {
      "get": {
        "tags": [
          "Social"
        ],
        "summary": "Check follow status",
        "operationId": "getSubscriptionStatus",
        "description": "Returns whether `followerId` currently follows `followingId`. A signed-in caller may ask about any pair — follow edges are public.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "followerId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "followingId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "followingType",
            "in": "query",
            "required": false,
            "description": "Defaults to \"user\".",
            "schema": {
              "type": "string",
              "enum": [
                "user",
                "organization"
              ],
              "default": "user"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Follow status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "isFollowing": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/subscriptions": {
      "post": {
        "tags": [
          "Social"
        ],
        "summary": "Follow a user or organization",
        "operationId": "createSubscription",
        "description": "Creates a follow edge from the authenticated caller to following_id. The follower is always the authenticated user and cannot be supplied by the client. Gated by the `features.user_follow_user` flag.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "following_id"
                ],
                "properties": {
                  "following_id": {
                    "type": "string"
                  },
                  "following_type": {
                    "type": "string",
                    "enum": [
                      "user",
                      "organization"
                    ],
                    "default": "user"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Follow created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing following_id, invalid following_type, or cannot follow yourself",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Following is disabled (`features.user_follow_user` is off — the one flag gates organization follows too), or `code: USER_BLOCKED`: one of the two people has blocked the other.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodedError"
                }
              }
            }
          },
          "404": {
            "description": "No user or organization with that id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/subscriptions/{followerId}/{followingId}/{followingType}": {
      "delete": {
        "tags": [
          "Social"
        ],
        "summary": "Unfollow a user or organization",
        "operationId": "deleteSubscription",
        "description": "Removes a follow edge. The path followerId must match the authenticated caller.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "followerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "followingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "followingType",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "user",
                "organization"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Follow removed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/users/{id}/followers": {
      "get": {
        "tags": [
          "Social"
        ],
        "summary": "List a user's followers",
        "operationId": "getFollowers",
        "description": "Returns the users that follow the given user. Emails are never exposed.\nA PRIVATE PROFILE ANSWERS AN EMPTY ARRAY to anyone but its owner (#1696). This list publishes other people's names, avatars, handles and counts, one row per follow, so a private profile's social graph is not enumerable through it. The COUNTS remain public — they ride on the profile payload, which carries real figures for a private profile. 200 with `[]`, not 404: the person exists, their graph is closed.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Follower list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      },
                      "avatar": {
                        "type": "string",
                        "nullable": true
                      },
                      "email": {
                        "type": "string",
                        "nullable": true,
                        "description": "Always null."
                      },
                      "role": {
                        "type": "string"
                      },
                      "profile_slug": {
                        "type": "string",
                        "nullable": true
                      },
                      "follower_count": {
                        "type": "integer"
                      },
                      "campaign_count": {
                        "type": "integer"
                      },
                      "type": {
                        "type": "string",
                        "enum": [
                          "user"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/users/{id}/following": {
      "get": {
        "tags": [
          "Social"
        ],
        "summary": "List who a user is following",
        "operationId": "getFollowing",
        "description": "Returns the entities the given user follows. Emails are never exposed.\nA PRIVATE PROFILE ANSWERS AN EMPTY ARRAY to anyone but its owner (#1696). This list publishes other people's names, avatars, handles and counts, one row per follow, so a private profile's social graph is not enumerable through it. The COUNTS remain public — they ride on the profile payload, which carries real figures for a private profile. 200 with `[]`, not 404: the person exists, their graph is closed.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Following list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      },
                      "avatar": {
                        "type": "string",
                        "nullable": true
                      },
                      "email": {
                        "type": "string",
                        "nullable": true,
                        "description": "Always null."
                      },
                      "role": {
                        "type": "string"
                      },
                      "profile_slug": {
                        "type": "string",
                        "nullable": true
                      },
                      "follower_count": {
                        "type": "integer"
                      },
                      "campaign_count": {
                        "type": "integer"
                      },
                      "type": {
                        "type": "string",
                        "enum": [
                          "user",
                          "organization"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{fundraiserId}/comments": {
      "get": {
        "tags": [
          "Comments"
        ],
        "summary": "List comments for a fundraiser",
        "operationId": "getCommentsByFundraiser",
        "description": "Returns paginated comments for a fundraiser, newest first. Hidden and retracted comments are left out. A comment written as a donor's note from their receipt carries its gift (`donation_amount_cents`, `donation_currency`); on an anonymous gift the author fields are null and `is_anonymous` is true. Every row carries `gif`, a GIF object or null; a GIF comment's `content` may be empty.\nAuthentication is optional. Every row carries `like_count`; for a signed-in caller `liked_by_me` says whether they like it, and for a guest it is always `false`.\nA signed-in caller never receives comments or replies by people they have blocked (`POST /users/{id}/block`), and `pagination.total` counts only what they receive. Nobody else's list changes. A donor's note on an anonymous gift is never filtered this way.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "fundraiserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Comment list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "fundraiser_id": {
                            "type": "string"
                          },
                          "content": {
                            "type": "string",
                            "description": "May be empty when `gif` is set."
                          },
                          "gif": {
                            "allOf": [
                              {
                                "$ref": "#/components/schemas/Gif"
                              }
                            ],
                            "nullable": true,
                            "description": "The GIF on this comment, or null (#1963)."
                          },
                          "parent_comment_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updated_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "author_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "author_name": {
                            "type": "string",
                            "nullable": true
                          },
                          "author_avatar": {
                            "type": "string",
                            "nullable": true
                          },
                          "can_manage": {
                            "type": "boolean",
                            "description": "True only for the authenticated author. Does not expose anonymous author IDs."
                          },
                          "is_anonymous": {
                            "type": "boolean"
                          },
                          "donation_amount_cents": {
                            "type": "integer",
                            "nullable": true,
                            "description": "The gift behind a donor note, net of the Stripe fee, in cents. Null on an ordinary comment."
                          },
                          "donation_currency": {
                            "type": "string",
                            "nullable": true
                          },
                          "like_count": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "Accounts that like this comment (#1833)."
                          },
                          "liked_by_me": {
                            "type": "boolean",
                            "description": "Whether the caller likes it; always false for a guest (#1833)."
                          }
                        }
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Comments"
        ],
        "summary": "Create a comment",
        "operationId": "createComment",
        "description": "Creates a comment (or reply) on a fundraiser. The author is derived from the authenticated user. Content must be 2000 characters or less, and is required unless `gif_id` is set.\n`gif_id` attaches a GIF (#1963): a GIPHY id from `GET /gifs/trending` or `GET /gifs/search`. The server looks it up on GIPHY and stores the GIF object it builds itself; clients never send URLs. Only `g` and `pg` GIFs are accepted. A request with `gif_id` also counts against the GIF rate limit (60 a minute per account).\nRequires a verified email address, and is gated by the `features.comments` flag — either gate failing answers `403`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "fundraiserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Required unless `gif_id` is set; may then be empty or whitespace."
                  },
                  "parent_comment_id": {
                    "type": "string",
                    "nullable": true
                  },
                  "gif_id": {
                    "type": "string",
                    "nullable": true,
                    "pattern": "^[A-Za-z0-9]{6,40}$",
                    "description": "A GIPHY GIF id (#1963). Replies take one too."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Comment created — the stored row (including `gif`, a GIF object or null) plus `author_name` and `author_avatar`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid fundraiser ID, missing/oversized content, malformed `gif_id` (`Invalid gif_id`), or parent comment not in this fundraiser",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Email not verified, comments are disabled (`features.comments` is off), or `code: COMMENTING_BLOCKED` — the campaign's owner has blocked the caller, or (for a reply) the parent comment's author has.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodedError"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "`{ \"error\": \"gif_not_found\" }` — GIPHY has no such GIF; `{ \"error\": \"gif_not_allowed\" }` — it is rated above `pg`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "`{ \"error\": \"gifs_upstream\" }` — GIPHY could not be reached while resolving `gif_id`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`{ \"error\": \"gifs_unavailable\" }` — `gif_id` was sent while GIF comments are off (`features.comment_gifs`) or not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/gifs/trending": {
      "get": {
        "tags": [
          "Comments"
        ],
        "summary": "Trending GIFs for the comment GIF picker",
        "operationId": "getTrendingGifs",
        "description": "GIPHY's trending GIFs, rated `pg` or lower, as GIF objects. Cached on the server for a few minutes. Page with `offset` = the previous answer's `next_offset`.\nAuthentication is optional. Rate limited at 60 requests a minute per account (per IP for a guest), on top of the public limit.\nAnswers `503 { \"error\": \"gifs_unavailable\" }` while GIF comments are off (`features.comment_gifs`) or GIPHY is not configured. Clients should hide their GIF button when they get it.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 24,
              "minimum": 1,
              "maximum": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0,
              "maximum": 4999
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of GIFs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GifPage"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "`{ \"error\": \"gifs_upstream\" }` — GIPHY failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`{ \"error\": \"gifs_unavailable\" }` — GIF comments are off or not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/gifs/search": {
      "get": {
        "tags": [
          "Comments"
        ],
        "summary": "Search GIFs for the comment GIF picker",
        "operationId": "searchGifs",
        "description": "GIPHY search, rated `pg` or lower, as GIF objects. Cached on the server by `q`, `offset`, `limit` and `lang`. Same limits and `503` behaviour as `GET /gifs/trending`.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "The search term. Whitespace is collapsed and it is cut to 50 characters.",
            "schema": {
              "type": "string",
              "minLength": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 24,
              "minimum": 1,
              "maximum": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0,
              "maximum": 4999
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "The search language. Anything else is treated as `en`.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of GIFs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GifPage"
                }
              }
            }
          },
          "400": {
            "description": "`{ \"error\": \"invalid_query\" }` — `q` is missing or blank.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "`{ \"error\": \"gifs_upstream\" }` — GIPHY failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`{ \"error\": \"gifs_unavailable\" }` — GIF comments are off or not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/comments/{id}": {
      "patch": {
        "tags": [
          "Comments"
        ],
        "summary": "Edit your own comment",
        "operationId": "editComment",
        "description": "Updates only the authenticated author's text, preserving its post time, author and saved GIF. Donation notes retain their existing three-write limit. Retracted notes cannot be edited. An author_id in the body never changes ownership.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "content"
                ],
                "properties": {
                  "content": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Trimmed text. Empty only when the comment already has a GIF."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Comment updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "content": {
                          "type": "string"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Comment not found or not authorized"
          },
          "409": {
            "description": "Comment can no longer be edited"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Comments"
        ],
        "summary": "Delete a comment",
        "operationId": "deleteComment",
        "description": "Deletes a comment. Only the comment's author may delete it. A donor's note tied to a gift is retracted (hidden, kept for the record) rather than deleted.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Comment deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Comment not found or not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/comments/{id}/report": {
      "post": {
        "tags": [
          "Comments"
        ],
        "summary": "Report a comment",
        "operationId": "reportComment",
        "description": "Reports a comment, a reply or a donor's note to the moderators (App Store Guideline 1.2). Validated like a campaign report: `reason` is a short phrase, sent in English whatever the reader's language because the queue is read in English. Clients offer these reasons: \"Harassment or bullying\", \"Hate speech or symbols\", \"Spam or scam\", \"Sexual or explicit content\", \"Violence or threats\", \"Self-harm or suicide\", \"False or misleading information\", \"Something else\".\n\nOne open report per person per comment: reporting again while the report is still pending updates its reason and details and answers `200` instead of `201`. Once a moderator has resolved it, a new report may be filed. You cannot report your own comment. Requires a verified email address; rate limited per account.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reason"
                ],
                "properties": {
                  "reason": {
                    "type": "string",
                    "minLength": 5,
                    "maxLength": 200,
                    "description": "Trimmed; 5 to 200 characters.",
                    "example": "Harassment or bullying"
                  },
                  "details": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 2000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "You already had a pending report of this comment; it was updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommentReportReceipt"
                }
              }
            }
          },
          "201": {
            "description": "Report recorded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommentReportReceipt"
                }
              }
            }
          },
          "400": {
            "description": "`code` is `INVALID_REASON`, `INVALID_DETAILS` or `CANNOT_REPORT_OWN_COMMENT`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodedError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Email address not verified (`code: EMAIL_NOT_VERIFIED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such comment, or it is hidden, retracted, or on a campaign that is not publicly readable — one answer for all of them.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/comments/{commentId}/like": {
      "put": {
        "tags": [
          "Comments"
        ],
        "summary": "Like a comment",
        "operationId": "likeComment",
        "description": "Likes a comment or a reply as the authenticated user. Idempotent: liking a comment you already like changes nothing and answers the same state. No verified email is required. Gated by the `features.comments` flag and the per-account rate limit.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "commentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Liked; the comment's count after the write",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LikeState"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Comments are disabled (`features.comments` is off).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such comment, or it is hidden, retracted, or on a campaign that is not publicly readable — one answer for all of them.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Comments"
        ],
        "summary": "Unlike a comment",
        "operationId": "unlikeComment",
        "description": "Removes the authenticated user's like from a comment or a reply. Idempotent: unliking a comment you do not like changes nothing.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "commentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Not liked; the comment's count after the write",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LikeState"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Comments are disabled (`features.comments` is off).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such comment, or it is hidden, retracted, or on a campaign that is not publicly readable — one answer for all of them.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/projects/{fundraiserId}/updates": {
      "get": {
        "tags": [
          "Updates"
        ],
        "summary": "Get the project updates feed",
        "operationId": "getProjectUpdates",
        "description": "Returns a unified feed of the fundraiser's updates and its withdrawals, newest first — a bare array. A withdrawal row is this campaign's share of a payout that carried its donations (never the payout's whole amount); paid, in-transit and pending payouts are listed. Withdrawn updates are left out. An unreadable feed answers `200` with an empty array rather than an error.\nReadable exactly when `GET /fundraisers/{id}` is: a campaign that is not `active`, `paused` or `ended`, is `private`, or has been deleted answers `404` to everyone but its owner.\nAuthentication is optional. Every `update` item carries `like_count`; for a signed-in caller `liked_by_me` says whether they like it, and for a guest it is always `false`. Withdrawal items carry neither.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "fundraiserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Overlay update translations into this language, when they exist.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Update feed (items are type \"update\" or \"withdrawal\")",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "update",
                          "withdrawal"
                        ]
                      },
                      "id": {
                        "type": "string"
                      },
                      "created_at": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "title": {
                        "type": "string",
                        "nullable": true,
                        "description": "Updates only."
                      },
                      "body": {
                        "type": "string",
                        "description": "Updates only."
                      },
                      "author": {
                        "type": "object",
                        "description": "Updates only.",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string",
                            "nullable": true
                          },
                          "avatar": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      },
                      "amount_cents": {
                        "type": "integer",
                        "description": "Withdrawals only — this campaign's share, in cents."
                      },
                      "currency": {
                        "type": "string",
                        "description": "Withdrawals only."
                      },
                      "status": {
                        "type": "string",
                        "description": "`active` on an update; `paid`, `in_transit` or `pending` on a withdrawal."
                      },
                      "arrival_date": {
                        "type": "string",
                        "nullable": true,
                        "description": "Withdrawals only."
                      },
                      "like_count": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Accounts that like this update; update items only (#1833)."
                      },
                      "liked_by_me": {
                        "type": "boolean",
                        "description": "Whether the caller likes it; always false for a guest; update items only (#1833)."
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "tags": [
          "Updates"
        ],
        "summary": "Post a project update",
        "operationId": "createProjectUpdate",
        "description": "Creates a project update on a fundraiser. Only the fundraiser owner may post, the caller's email must be verified, and the endpoint is gated by the `features.project_updates` flag. The `body` field is required (at most 20,000 characters; `title` at most 200). The update's language is detected and machine translations are queued.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "fundraiserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "body"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 200
                  },
                  "body": {
                    "type": "string",
                    "maxLength": 20000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Update created — a bare object, not wrapped in `data`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "fundraiser_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "author_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "title": {
                      "type": "string",
                      "nullable": true
                    },
                    "body": {
                      "type": "string"
                    },
                    "source_language": {
                      "type": "string",
                      "nullable": true
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updated_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "update"
                      ]
                    },
                    "author": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string",
                          "nullable": true
                        },
                        "avatar": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Update body is missing, or `title` is not a string",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not the fundraiser owner, email not verified, or updates are disabled (`features.project_updates` is off).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "413": {
            "description": "`title` or `body` is over its length limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/projects/{fundraiserId}/updates/{updateId}": {
      "patch": {
        "tags": [
          "Updates"
        ],
        "summary": "Edit a project update",
        "operationId": "editProjectUpdate",
        "description": "Changes an update's title and/or body. Campaign owner only; the caller's email must be verified, and the endpoint is gated by the `features.project_updates` flag. Send at least one of `title` and `body`; `title: null` (or blank) removes the title.\nWhen the words change, the update's language is detected again, its machine translations are dropped and re-queued, and hand-made translations are flagged as outdated. A withdrawn update answers `404`. Audit-logged.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "fundraiserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "updateId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 200
                  },
                  "body": {
                    "type": "string",
                    "maxLength": 20000,
                    "description": "Must not be blank when sent."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The edited update (bare object)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "fundraiser_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "author_id": {
                      "type": "string",
                      "format": "uuid",
                      "nullable": true
                    },
                    "title": {
                      "type": "string",
                      "nullable": true
                    },
                    "body": {
                      "type": "string"
                    },
                    "source_language": {
                      "type": "string",
                      "nullable": true
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updated_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "update"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Neither field sent, a blank `body`, or a non-string `title`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not the campaign owner, email not verified, or `features.project_updates` is off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Campaign or update not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`title` over 200 or `body` over 20,000 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Updates"
        ],
        "summary": "Delete a project update",
        "operationId": "deleteProjectUpdate",
        "description": "Soft-deletes a project update. Only the fundraiser owner may delete it.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "fundraiserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "updateId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Update deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "deletedId": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not authorized to delete updates from this fundraiser",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Fundraiser or update not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/projects/{fundraiserId}/updates/{updateId}/like": {
      "put": {
        "tags": [
          "Updates"
        ],
        "summary": "Like a project update",
        "operationId": "likeProjectUpdate",
        "description": "Likes a campaign update as the authenticated user. Idempotent: liking an update you already like changes nothing and answers the same state. No verified email is required; the per-account rate limit applies.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "fundraiserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "updateId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Liked; the update's count after the write",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LikeState"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such update under this campaign, or it was deleted, or the campaign is not publicly readable — one answer for all of them.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Updates"
        ],
        "summary": "Unlike a project update",
        "operationId": "unlikeProjectUpdate",
        "description": "Removes the authenticated user's like from a campaign update. Idempotent: unliking an update you do not like changes nothing.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "fundraiserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "updateId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Not liked; the update's count after the write",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LikeState"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such update under this campaign, or it was deleted, or the campaign is not publicly readable — one answer for all of them.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/projects/{fundraiserId}/milestones": {
      "get": {
        "tags": [
          "Updates"
        ],
        "summary": "List project milestones",
        "operationId": "getProjectMilestones",
        "description": "Returns all milestones for a fundraiser, ordered by due date then creation date — a bare array, unlike `GET /fundraisers/{fundraiserId}/milestones`, which wraps the same rows in `milestones`. Readable exactly when `GET /fundraisers/{id}` is: a campaign that is not `active`, `paused` or `ended`, is `private`, or has been deleted answers `404` to everyone but its owner. Authentication is optional.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "fundraiserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Overlay the stored translation of title and description for this language, when one exists.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Milestone list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Milestone"
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/projects/{fundraiserId}/stats": {
      "get": {
        "tags": [
          "Updates"
        ],
        "summary": "Get project funding stats",
        "operationId": "getProjectStats",
        "description": "Returns allocation, disbursement, and milestone-count stats for a project-type fundraiser. Non-project fundraisers return zeroed stats. **Not available yet for project fundraisers:** the endpoint currently answers `500` for them. Readable exactly when `GET /fundraisers/{id}` is: a campaign that is not `active`, `paused` or `ended`, is `private`, or has been deleted answers `404` to everyone but its owner. Authentication is optional.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "fundraiserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Project stats",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "totalAllocated": {
                      "type": "number"
                    },
                    "totalDisbursed": {
                      "type": "number"
                    },
                    "unallocated": {
                      "type": "number"
                    },
                    "milestones": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer"
                        }
                      },
                      "additionalProperties": {
                        "type": "integer"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "description": "Project funding stats are not available yet (every project fundraiser, today).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/shares": {
      "post": {
        "tags": [
          "Shares"
        ],
        "summary": "Track a share event",
        "operationId": "trackShareEvent",
        "description": "Records a social-share event for a fundraiser or profile. Authentication is optional — the sharing user is recorded when a session is present, otherwise the row is anonymous.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "entity_type",
                  "entity_id",
                  "platform"
                ],
                "properties": {
                  "entity_type": {
                    "type": "string",
                    "enum": [
                      "fundraiser",
                      "profile"
                    ]
                  },
                  "entity_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "platform": {
                    "type": "string",
                    "enum": [
                      "copy_link",
                      "facebook",
                      "story",
                      "whatsapp",
                      "instagram",
                      "text",
                      "messenger",
                      "linkedin",
                      "email",
                      "x",
                      "qr",
                      "native",
                      "twitter",
                      "sms"
                    ],
                    "description": "The share button's id. `twitter` and `sms` are accepted as the old names of `x` and `text`, and counted under them."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Share tracked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid share payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-role-titles": {
      "get": {
        "tags": [
          "Organizations"
        ],
        "summary": "List organization role titles",
        "operationId": "listOrgRoleTitles",
        "description": "Public reference list of non-deprecated position titles (the LinkedIn-style \"position\" picker on the org-admin Members page), ordered by `sort_order` then `label`. These titles are display-only and carry no permissions — they are distinct from the RBAC roles `org_owner` / `org_admin` / `org_viewer`. Pass an `id` from this list as `org_role_title_id` when adding a member.",
        "responses": {
          "200": {
            "description": "Role titles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OrgRoleTitle"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/overview": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Get organization dashboard totals",
        "operationId": "getOrgAdminOverview",
        "description": "Headline numbers for the org-admin dashboard. For a conglomerate the figures roll up the organization **and all of its child organizations**; for a company they cover the organization alone. Raised and donors are over the organization's **counted gifts**, the same gifts the Analytics (`GET /org-admin/{slug}/analytics`) and the non-profit month card (`GET /org-admin/{slug}/nonprofit/attention`) read: each counted gift (paid or refunded) to one of its **counted campaigns** (approved, public, not deleted), plus each gift made directly to a non-profit (its general fund and monthly gifts, which have no campaign). `totalRaisedCents` is what reached the recipient, each gift at its donation less the Stripe fee and never the tip, in integer cents; `uniqueDonors` counts the distinct donors of those gifts, guests and anonymous donors included. The public profile counts campaign gifts only, so for a non-profit with general-fund or monthly gifts these figures are deliberately larger than the public ones; otherwise they are equal.\n\n**Requires permission:** `org.read`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "responses": {
          "200": {
            "description": "Dashboard totals",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "activeFundraisers": {
                          "type": "integer",
                          "description": "Counted fundraisers with status `active`."
                        },
                        "totalFundraisers": {
                          "type": "integer",
                          "description": "Counted fundraisers (approved, public, not deleted)."
                        },
                        "totalRaisedCents": {
                          "type": "integer",
                          "description": "What the organization's counted gifts raised (its counted fundraisers plus gifts made directly to a non-profit), in integer CENTS (net of the Stripe fee, tips excluded).",
                          "example": 4560000
                        },
                        "uniqueDonors": {
                          "type": "integer",
                          "description": "Distinct donors of the counted gifts, guests and anonymous donors included."
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "company",
                            "conglomerate"
                          ]
                        },
                        "childrenCount": {
                          "type": "integer",
                          "description": "Number of child organizations (always 0 for a company)."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/fundraisers": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "List the organization's fundraisers",
        "operationId": "listOrgAdminFundraisers",
        "description": "Non-deleted fundraisers owned by this organization (not its children), newest first, with offset pagination. Every status is included — drafts, pending review, ended — unless `status` narrows it. Private contact fields are never returned.\n\n**Requires permission:** `org.read`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only fundraisers with this status. Send one of the listed values.",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "pending",
                "rejected",
                "active",
                "paused",
                "ended"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Clamped to 1..100. Defaults to 20.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 128
            },
            "description": "Search fundraiser titles."
          },
          {
            "name": "dateFrom",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Inclusive fundraiser creation timestamp."
          },
          {
            "name": "dateTo",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Inclusive fundraiser creation timestamp."
          },
          {
            "name": "amount",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^\\d{1,10}(\\.\\d{1,2})?$"
            },
            "description": "Exact fundraiser raised amount in major units."
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated fundraisers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OrgAdminFundraiser"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/OrgAdminPagination"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/donations": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "List donations to the organization's fundraisers",
        "operationId": "listOrgAdminDonations",
        "description": "Donations to this organization's non-deleted fundraisers and gifts made directly to the non-profit (general fund and monthly gifts, whose `fundraiser_id`, `fundraiser_title` and `fundraiser_slug` are null), newest first, with offset pagination. Every payment status is returned unless `status` narrows it.\n\nDonor privacy: `donor_display_name` is `Anonymous donor` when the gift was marked anonymous, the donor's profile name for a signed-in donor, and the checkout name for a guest. Donor email addresses are never returned.\n\n**Requires permission:** `org.read_donations`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only donations with this payment status. Send one of the listed values.",
            "schema": {
              "type": "string",
              "enum": [
                "paid",
                "pending",
                "failed",
                "refunded"
              ]
            }
          },
          {
            "name": "fundraiser_id",
            "in": "query",
            "required": false,
            "description": "Only donations to this fundraiser. Must be a UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Clamped to 1..100. Defaults to 20.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 128
            },
            "description": "Search the visible donor name or fundraiser title."
          },
          {
            "name": "dateFrom",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Inclusive gift creation timestamp."
          },
          {
            "name": "dateTo",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Inclusive gift creation timestamp."
          },
          {
            "name": "amount",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^\\d{1,10}(\\.\\d{1,2})?$"
            },
            "description": "Exact gift amount in major units, without currency symbols."
          },
          {
            "name": "fundraiser",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 128
            },
            "description": "Fundraiser title contains this text."
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated donations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OrgAdminDonation"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/OrgAdminPagination"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/donors": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "List the organization's donors",
        "operationId": "listOrgAdminDonors",
        "description": "Distinct donors of this organization's counted gifts (paid or refunded) to any of its fundraisers that is not deleted, unlisted, private and not-yet-approved ones included, or made directly to the non-profit (general fund and monthly), with their lifetime totals here, most recent gift first, with offset pagination. This is wider than the Overview's and Analytics' figures, which count counted (approved, public) fundraisers only. A donor's total (\"Raised after card fees\", `total_amount_cents`) is what their gifts raised: each gift's ledger donation credit less its Stripe fee, never the tip, a refunded gift included at that amount; not the gross they paid. All anonymous gifts are collapsed into a single `Anonymous donor` row (`donor_key: anonymous`) so they cannot be told apart by amount. Signed-in donors are keyed `user:<profile id>`; guest donors are keyed `guest:<24 hex characters>`. Treat `donor_key` as an opaque identifier: it is stable across pages and requests, but carries no contact details and cannot be turned back into one.\n\n**Requires permission:** `org.read_donors`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Clamped to 1..100. Defaults to 20.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 128
            },
            "description": "Search visible name, registered donor gift email or public city. Guest receipt emails are excluded."
          },
          {
            "name": "dateFrom",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Inclusive gift creation timestamp."
          },
          {
            "name": "dateTo",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Inclusive gift creation timestamp."
          },
          {
            "name": "amount",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^\\d{1,10}(\\.\\d{1,2})?$"
            },
            "description": "Exact gift amount in major units, without currency symbols."
          },
          {
            "name": "fundraiser",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 128
            },
            "description": "Fundraiser title contains this text."
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated donor roll-up",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OrgAdminDonor"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/OrgAdminPagination"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/users/search": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Look up an account by email before adding it as a member",
        "operationId": "searchOrgAdminPlatformUsers",
        "description": "Confirms which FundlyHub account uses an email address, for the Members page's \"Add member\" form. `q` must be a **complete** email address; it is matched case-insensitively against account login emails only, and at most one result comes back, with the address masked. Anything that is not a complete email address (a name, a fragment, a phone number) answers `200` with an empty list. This is not a directory search.\n\nAvailable only to organizations that are approved or verified; any other organization gets `403` with `code: ORG_NOT_APPROVED`.\n\nRate limited to 30 requests per minute per user, in one bucket shared with `POST /org-admin/{slug}/members`.\n\nNote the bare `{ \"results\": [ … ] }` envelope rather than `data`.\n\n**Requires permission:** `org.manage_members`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          },
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "A complete email address (surrounding whitespace is trimmed). Matched case-insensitively against account login emails.",
            "schema": {
              "type": "string",
              "format": "email",
              "maxLength": 254
            },
            "example": "sam@example.org"
          }
        ],
        "responses": {
          "200": {
            "description": "The matching account, or an empty list when no account uses that email or `q` is not a complete email address.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "maxItems": 1,
                      "items": {
                        "$ref": "#/components/schemas/OrgAdminUserSearchResult"
                      }
                    }
                  }
                },
                "example": {
                  "results": [
                    {
                      "id": "3f1c2a9e-5b7d-4e1a-9c2b-8d6f0a1b2c3d",
                      "type": "user",
                      "name": "Sam Rivera",
                      "avatar": null,
                      "masked_email": "s***@example.org"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description, or the organization is not approved or verified yet (`code: ORG_NOT_APPROVED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "missingPermission": {
                    "summary": "Missing permission",
                    "value": {
                      "error": "Forbidden",
                      "message": "Requires permission: org.manage_members"
                    }
                  },
                  "orgNotApproved": {
                    "summary": "Organization not approved yet",
                    "value": {
                      "error": "Member lookup is available once the organization has been approved.",
                      "code": "ORG_NOT_APPROVED"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "description": "More than 30 member lookups and adds by this user in the last minute (`Too many member lookups. Please wait a minute and try again.`), or a broader rate limit.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/members": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "List organization members",
        "operationId": "listOrgAdminMembers",
        "description": "Everyone holding an active, unexpired org-scoped role on this organization, highest role first, then by name. Includes each member's email address, which is why this sits behind the management permission rather than `org.read`.\n\n**Requires permission:** `org.manage_members`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "responses": {
          "200": {
            "description": "Members",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OrgAdminMember"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Add a member",
        "operationId": "addOrgAdminMember",
        "description": "Adds an **existing** FundlyHub user to the organization with the given role. Identify the user with **either** `email` (case-insensitive) **or** `user_id` (the `id` that `GET /org-admin/{slug}/users/search` returns), not both. A deleted account is treated as no account. The membership is active immediately; no invitation is sent and the user does not have to accept. `org_owner` cannot be granted here — add the user first, then promote them with `PATCH /org-admin/{slug}/members/{userId}`.\n\nAn optional display title can be set with **either** `org_role_title_id` (an `id` from `GET /org-role-titles`) **or** `custom_role_title`, not both.\n\nAvailable only to organizations that are approved or verified; any other organization gets `403` with `code: ORG_NOT_APPROVED`.\n\nRate limited to 30 requests per minute per user, in one bucket shared with `GET /org-admin/{slug}/users/search`.\n\n**Requires permission:** `org.manage_members`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "role"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Email address of an existing FundlyHub account. Send this or `user_id`."
                  },
                  "user_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Profile id of an existing FundlyHub account. Send this or `email`."
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "org_admin",
                      "org_viewer"
                    ]
                  },
                  "org_role_title_id": {
                    "type": "string",
                    "description": "An `id` from `GET /org-role-titles`.",
                    "example": "executive_director"
                  },
                  "custom_role_title": {
                    "type": "string",
                    "maxLength": 100,
                    "description": "Free-form title, used when nothing in the taxonomy fits."
                  }
                }
              },
              "examples": {
                "byEmail": {
                  "summary": "By email",
                  "value": {
                    "email": "jane@example.org",
                    "role": "org_viewer"
                  }
                },
                "byUserId": {
                  "summary": "By user id",
                  "value": {
                    "user_id": "4f6c1a8e-2b3d-4c5e-9f70-1a2b3c4d5e6f",
                    "role": "org_admin",
                    "org_role_title_id": "treasurer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Member added",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "user_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "user_name": {
                          "type": "string",
                          "nullable": true
                        },
                        "role_name": {
                          "type": "string",
                          "enum": [
                            "org_admin",
                            "org_viewer"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Neither or both of `email` and `user_id`; `user_id` not a UUID; `role` not `org_admin` / `org_viewer`; `custom_role_title` over 100 characters; both title fields set; or an `org_role_title_id` that is not in the taxonomy (`Unknown org_role_title_id`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description, or the organization is not approved or verified yet (`code: ORG_NOT_APPROVED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "missingPermission": {
                    "summary": "Missing permission",
                    "value": {
                      "error": "Forbidden",
                      "message": "Requires permission: org.manage_members"
                    }
                  },
                  "orgNotApproved": {
                    "summary": "Organization not approved yet",
                    "value": {
                      "error": "Members can be added once the organization has been approved.",
                      "code": "ORG_NOT_APPROVED"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug, or no live FundlyHub account matches (`No FundlyHub user with that email. Ask them to sign up first.` / `No FundlyHub user with that id.`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The user already holds a role on this organization. Use `PATCH` to change it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "More than 30 member lookups and adds by this user in the last minute (`Too many member lookups. Please wait a minute and try again.`), or a broader rate limit.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/members/{userId}": {
      "patch": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Change a member's role or title",
        "operationId": "updateOrgAdminMemberRole",
        "description": "Moves a member to a different org role, changes their display title, or both. Send at least one of `role`, `org_role_title_id`, `custom_role_title`. A title is **either** an `org_role_title_id` **or** a `custom_role_title`; setting one clears the other, and `null` (or a blank string) for the sent field(s) clears the title. Omitting both title fields keeps the current title, including across a role change. A request that changes nothing is an idempotent no-op that still answers `200`.\n\nA title-only change follows the same hierarchy as a role change: changing your own title is always allowed; changing someone else's needs a rank above theirs, and only an owner changes an owner's.\n\nRoles rank `org_owner` > `org_admin` > `org_viewer`. Rules enforced, each a `403` when broken:\n\n  - only an `org_owner` may promote anyone to `org_owner`, or change the role of another owner;\n  - nobody may change the role of a member whose role is equal to or above their own (an\n    `org_admin` manages `org_viewer`s, not other admins);\n  - nobody may grant a role above their own.\n\nLowering your own role (stepping down) is always allowed. The organization's last remaining owner cannot be demoted (`400`) — promote another member to owner first.\n\n**A non-profit's team body.** A body with `title` or `show_on_page`, or whose `role` is a non-profit team role (`admin`, `fundraiser`, `viewer`, `member`, or `org_fundraiser`, `org_member`), goes to the non-profit team handler instead. There `role` is one of those roles (`org_admin` and `org_viewer` are read as `admin` and `viewer`), `title` is a title from `GET /org-role-titles` by id or label, or free text of up to 80 characters (`null` or blank clears it), and `show_on_page` lists or hides the member on the page's team. It answers the member itself, without the `data` wrapper. Its refusals have the non-profit shape (`{ \"error\": { \"code\", \"message\", \"details\" } }`): `422` `transfer_ownership` for the owner role (a non-profit has one owner; use `POST /org-admin/{slug}/transfer-ownership`), `422` `last_owner` for changing the only owner's role, `422` `role`, `title` or `show_on_page` for a bad value, `403` `above_own` for a role above the caller's own, `403` `forbidden` for a member ranked equal to or above the caller, and `404` `not_member`. The older body's `role: org_owner` on a non-profit answers the same `422` `transfer_ownership`.\n\n**Requires permission:** `org.manage_members`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          },
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "description": "The member's profile id. A non-UUID answers `404 Member not found`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "minProperties": 1,
                "properties": {
                  "role": {
                    "type": "string",
                    "enum": [
                      "org_owner",
                      "org_admin",
                      "org_viewer",
                      "admin",
                      "fundraiser",
                      "viewer",
                      "member",
                      "org_fundraiser",
                      "org_member"
                    ],
                    "description": "`org_owner`, `org_admin` and `org_viewer` are the older body's roles; the others send the request to the non-profit team handler. A non-profit's owner role cannot be given here (`422` `transfer_ownership`)."
                  },
                  "title": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 80,
                    "description": "Non-profit team body. A title from `GET /org-role-titles` (by id or label) or free text; `null` or blank clears it."
                  },
                  "show_on_page": {
                    "type": "boolean",
                    "description": "Non-profit team body. Whether the member is listed on the page's team."
                  },
                  "org_role_title_id": {
                    "type": "string",
                    "nullable": true,
                    "description": "An `id` from `GET /org-role-titles`. `null` clears the title.",
                    "example": "board_chair"
                  },
                  "custom_role_title": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 100,
                    "description": "Free-form title. `null` clears the title."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Member updated (or already as requested): `{ data }` for the older body, the team member itself for a non-profit team body.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "required": [
                        "data"
                      ],
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "user_id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "role_name": {
                              "type": "string",
                              "enum": [
                                "org_owner",
                                "org_admin",
                                "org_viewer"
                              ]
                            },
                            "org_role_title_id": {
                              "type": "string",
                              "nullable": true
                            },
                            "custom_role_title": {
                              "type": "string",
                              "nullable": true
                            }
                          }
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/NonprofitTeamMember"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "None of `role`, `org_role_title_id`, `custom_role_title` sent; invalid `role`; a title field that is not a string or null; `custom_role_title` over 100 characters; both title fields set; an `org_role_title_id` not in the taxonomy (`Unknown org_role_title_id`); or the change would demote the only owner.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks `org.manage_members`; holds no role on this organization; is not an owner and is promoting someone to owner or changing an owner's role or title; is changing the role or title of a member ranked equal to or above them; or is granting a role above their own. A non-profit team body answers in the non-profit shape: `above_own` or `forbidden`.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "$ref": "#/components/schemas/NonprofitError"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug, or the user is not a member (`not_member` for a non-profit team body).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "$ref": "#/components/schemas/NonprofitError"
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "`transfer_ownership` (the owner role, from either body, on a non-profit), or, in a non-profit team body, `last_owner` or a bad `role`, `title` or `show_on_page`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Remove a member",
        "operationId": "removeOrgAdminMember",
        "description": "Deactivates every org-scoped role the user holds on this organization. Only an `org_owner` may remove an owner, and nobody may remove a member whose role is equal to or above their own (`403`). Removing yourself (leaving) is always allowed. The organization's last remaining owner cannot be removed (`400`) — promote another member to owner first.\n\n**Requires permission:** `org.manage_members`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          },
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "description": "The member's profile id. A non-UUID answers `404 Member not found`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Member removed"
          },
          "400": {
            "description": "The user is the only owner.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks `org.manage_members`; holds no role on this organization; or is removing an owner without being one, or a member ranked equal to or above them.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Only an organization owner can remove an owner."
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug, or the user is not a member.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/settings": {
      "patch": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Update organization settings",
        "operationId": "updateOrgAdminSettings",
        "description": "Partial update of the organization's profile. Only the fields below are writable; others are ignored. String fields accept a string or `null` and are trimmed. At least one writable field must be present.\n\n`logo` and `banner_image` take a URL as-is; to upload an image use `POST /org-admin/{slug}/avatar` or `/banner` instead.\n\nOn a non-profit (`kind` `nonprofit`) two fields are refused with 422 and nothing is written: `legal_name` (`locked`, the IRS name) and `website` (`use_nonprofit_settings`). A non-profit's website is changed only with `PATCH /org-admin/{slug}/nonprofit`, which normalizes it and, on an unsubmitted draft, resets a work-email authority claim when the website moves to another domain.\n\n**Requires permission:** `org.update_settings`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "legal_name": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 255,
                    "description": "Cannot be set to an empty string."
                  },
                  "website": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 1024,
                    "description": "Refused on a non-profit (422 `use_nonprofit_settings`); use `PATCH /org-admin/{slug}/nonprofit`."
                  },
                  "description": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 4000
                  },
                  "country": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 64
                  },
                  "logo": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 1024
                  },
                  "banner_image": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 1024
                  },
                  "mission": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 4000
                  },
                  "contact_email": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 320,
                    "description": "Must look like an email address when non-empty."
                  },
                  "contact_email_public": {
                    "type": "boolean",
                    "description": "Whether `contact_email` is shown on the public profile. Defaults to false."
                  },
                  "founded_year": {
                    "type": "integer",
                    "nullable": true,
                    "minimum": 1800,
                    "description": "Between 1800 and the current year."
                  },
                  "social_links": {
                    "type": "object",
                    "nullable": true,
                    "description": "Replaces the whole set. Keys are limited to the listed platforms; a `null` or empty value drops that platform, and `{}` or `null` clears them all.",
                    "properties": {
                      "twitter": {
                        "type": "string",
                        "maxLength": 500
                      },
                      "linkedin": {
                        "type": "string",
                        "maxLength": 500
                      },
                      "facebook": {
                        "type": "string",
                        "maxLength": 500
                      },
                      "instagram": {
                        "type": "string",
                        "maxLength": 500
                      },
                      "youtube": {
                        "type": "string",
                        "maxLength": 500
                      },
                      "tiktok": {
                        "type": "string",
                        "maxLength": 500
                      }
                    },
                    "additionalProperties": false
                  },
                  "categories": {
                    "type": "array",
                    "nullable": true,
                    "maxItems": 20,
                    "description": "Replaces the whole set. Each entry is a category `name` from `GET /categories` (matched case-insensitively and stored as that endpoint spells it; blanks and duplicates are dropped). `[]` or `null` clears them.",
                    "items": {
                      "type": "string",
                      "maxLength": 64
                    },
                    "example": [
                      "Education",
                      "Community"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated settings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OrgAdminSettings"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A field has the wrong type or is too long, `legal_name` is empty, `contact_email` is malformed, `founded_year` is out of range, an unknown `social_links` key was sent, `categories` is not an array of strings, has more than 20 entries or names a category that does not exist or is inactive (`Unknown category: …`), or no writable field was present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "422": {
            "description": "The organization is a non-profit and the body has `legal_name` (`locked`) or `website` (`use_nonprofit_settings`, change it with `PATCH /org-admin/{slug}/nonprofit`). Nothing is written.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                },
                "example": {
                  "error": {
                    "code": "use_nonprofit_settings",
                    "message": "A non-profit's website is changed in its page settings (PATCH /org-admin/:slug/nonprofit).",
                    "details": {
                      "field": "website",
                      "reason": "use_nonprofit_settings"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/avatar": {
      "post": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Upload organization logo",
        "operationId": "uploadOrgAdminAvatar",
        "description": "Uploads a new logo as base64 JSON. The image is centre-cropped to 256×256, re-encoded as WebP, stored, and written to the organization's `logo` straight away — no separate settings save is needed. Any previous logo file is deleted. Maximum 5 MB decoded.\n\nNote the bare response body (no `data` envelope).\n\n**Requires permission:** `org.update_settings`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrgAdminImageUpload"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Logo uploaded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "avatar_url": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`fileBase64` or `contentType` missing, the content type is not allowed, the file is over 5 MB, or it is not a valid image.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Remove organization logo",
        "operationId": "removeOrgAdminAvatar",
        "description": "Deletes the stored logo files and clears the organization's `logo`.\n\n**Requires permission:** `org.update_settings`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "responses": {
          "204": {
            "description": "Logo removed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/updates": {
      "post": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Post an organization update",
        "operationId": "createOrgAdminUpdate",
        "description": "Publishes a post to the organization's public updates feed (`GET /organizations/{id}/updates`). The caller is recorded as the author.\n\n**Requires permission:** `org.update_settings`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title",
                  "body"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "body": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 20000
                  },
                  "cover_image": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 2048,
                    "description": "Image URL. An empty string is stored as null."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Update posted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OrgAdminUpdate"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`title` or `body` missing, empty, too long or not a string; or `cover_image` invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/updates/{updateId}": {
      "patch": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Edit an organization update",
        "operationId": "updateOrgAdminUpdate",
        "description": "Partial edit of one of this organization's updates. Send at least one of `title`, `body`, `cover_image`.\n\n**Requires permission:** `org.update_settings`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          },
          {
            "name": "updateId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "body": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 20000
                  },
                  "cover_image": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 2048
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update edited",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OrgAdminUpdate"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A field is invalid, or no editable field was sent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug, or the update does not belong to it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Delete an organization update",
        "operationId": "deleteOrgAdminUpdate",
        "description": "Permanently deletes one of this organization's updates. A malformed `updateId` answers `500` rather than `404`.\n\n**Requires permission:** `org.update_settings`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          },
          {
            "name": "updateId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Update deleted"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug, or the update does not belong to it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/banner": {
      "post": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Upload organization banner",
        "operationId": "uploadOrgAdminBanner",
        "description": "Uploads the public-profile banner as base64 JSON. The image is centre-cropped to 1500×500 (3:1), re-encoded as WebP, stored, and written to the organization's `banner_image` straight away. Any previous banner file is deleted. Maximum 8 MB decoded.\n\nNote the bare response body (no `data` envelope).\n\n**Requires permission:** `org.update_settings`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrgAdminImageUpload"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Banner uploaded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "banner_url": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`fileBase64` or `contentType` missing, the content type is not allowed, the file is over 8 MB, or it is not a valid image.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Remove organization banner",
        "operationId": "removeOrgAdminBanner",
        "description": "Deletes the stored banner files and clears the organization's `banner_image`.\n\n**Requires permission:** `org.update_settings`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "responses": {
          "204": {
            "description": "Banner removed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/dbas": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "List DBAs",
        "operationId": "listOrgAdminDbas",
        "description": "The organization's \"doing business as\" names, default first, then alphabetical.\n\n**Requires permission:** `org.read`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "responses": {
          "200": {
            "description": "DBAs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OrgAdminDba"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Add a DBA",
        "operationId": "addOrgAdminDba",
        "description": "Adds a DBA name. With `is_default: true` it becomes the default and the previous default is cleared in the same transaction.\n\n**Requires permission:** `org.manage_dbas`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "dba_name"
                ],
                "properties": {
                  "dba_name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255
                  },
                  "is_default": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "DBA added",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OrgAdminDba"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`dba_name` missing, blank or over 255 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "409": {
            "description": "The organization already has a DBA with that name.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/dbas/{dbaId}": {
      "patch": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Update a DBA",
        "operationId": "updateOrgAdminDba",
        "description": "Renames a DBA and/or changes whether it is the default. Setting `is_default: true` clears the previous default in the same transaction.\n\n**Requires permission:** `org.manage_dbas`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          },
          {
            "name": "dbaId",
            "in": "path",
            "required": true,
            "description": "A non-UUID answers `404 DBA not found`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dba_name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255
                  },
                  "is_default": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "DBA updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OrgAdminDba"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`dba_name` blank or too long, or no valid field was sent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug, or the DBA does not belong to it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The organization already has a DBA with that name.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Delete a DBA",
        "operationId": "deleteOrgAdminDba",
        "description": "Permanently deletes a DBA. Deleting the default leaves the organization with no default DBA.\n\n**Requires permission:** `org.manage_dbas`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          },
          {
            "name": "dbaId",
            "in": "path",
            "required": true,
            "description": "A non-UUID answers `404 DBA not found`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "DBA deleted"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug, or the DBA does not belong to it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/locations": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "List office locations",
        "operationId": "listOrgAdminLocations",
        "description": "The organization's physical locations, primary first, then oldest first. Includes locations not shown publicly. The separate mailing_address is the organization's own mailing address, the same record nonprofit About, settings and receipts read; it does not create a branch copy or change public visibility.\n\n**Requires permission:** `org.read`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "responses": {
          "200": {
            "description": "Locations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OrgAdminLocation"
                      }
                    },
                    "mailing_address": {
                      "type": "object",
                      "nullable": true,
                      "description": "Canonical mailing address, with line1, line2, city, region, postal_code and country; absent fields are null.",
                      "additionalProperties": {
                        "type": "string",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Add an office location",
        "operationId": "addOrgAdminLocation",
        "description": "Adds a location. With `is_primary: true` it becomes the primary location and the previous primary is cleared in the same transaction. Locations are hidden from the public profile unless `is_publicly_visible` is `true`.\n\n**Requires permission:** `org.manage_locations`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "address"
                ],
                "properties": {
                  "label": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 120,
                    "example": "Headquarters"
                  },
                  "address": {
                    "$ref": "#/components/schemas/OrgAdminAddress"
                  },
                  "is_primary": {
                    "type": "boolean",
                    "default": false
                  },
                  "is_publicly_visible": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Location added",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OrgAdminLocation"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`label` not a string or over 120 characters; `address` missing, not an object, over 16 fields, or a field that is not a string or is over 512 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/locations/{locationId}": {
      "patch": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Update an office location",
        "operationId": "updateOrgAdminLocation",
        "description": "Partial update of a location. `address`, when sent, replaces the whole address object. Setting `is_primary: true` clears the previous primary in the same transaction.\n\n**Requires permission:** `org.manage_locations`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "description": "A non-UUID answers `404 Location not found`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 120
                  },
                  "address": {
                    "$ref": "#/components/schemas/OrgAdminAddress"
                  },
                  "is_primary": {
                    "type": "boolean"
                  },
                  "is_publicly_visible": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Location updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OrgAdminLocation"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A field is invalid, or no valid field was sent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug, or the location does not belong to it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Delete an office location",
        "operationId": "deleteOrgAdminLocation",
        "description": "Permanently deletes a location. Deleting the primary leaves the organization with no primary location.\n\n**Requires permission:** `org.manage_locations`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "description": "A non-UUID answers `404 Location not found`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Location deleted"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug, or the location does not belong to it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/payouts/connect": {
      "post": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Start or resume Stripe Connect onboarding",
        "operationId": "createOrgAdminPayoutsConnect",
        "description": "Creates the organization's Stripe Express account (business type `non_profit` for a non-profit, `company` otherwise) if it has none, or reuses the existing one, and returns a fresh single-use onboarding link. Safe to call repeatedly — each call returns a new link. If the stored account no longer exists on Stripe a new one is created in its place.\n\nA non-profit may connect while its `verification_status` is `pending`, `approved` or `verified`, so while its page is still a draft or under review (creating the account moves no money); any other organization must be `verified`. Otherwise the answer is `400`. The `features.org_level_stripe_connect` flag must be on (`503` otherwise).\n\n**Requires permission:** `org.manage_payouts` (organization owners only)",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "responses": {
          "201": {
            "description": "Onboarding link created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "accountId": {
                          "type": "string",
                          "example": "acct_1Nv0FGQ9RKHgCVdK"
                        },
                        "onboardingUrl": {
                          "type": "string",
                          "format": "uri",
                          "description": "Stripe-hosted onboarding page. Short-lived; redirect the user straight away."
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "existing"
                          ],
                          "description": "`pending` when this call created the account, `existing` when it reused one."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The organization may not connect in its current status (a non-profit that is not pending, approved or verified; any other organization that is not verified).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Org-level Stripe Connect is turned off (`features.org_level_stripe_connect`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/payouts/status": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Get Stripe Connect status",
        "operationId": "getOrgAdminPayoutsStatus",
        "description": "Whether the organization can take charges and receive payouts. Reads the account live from Stripe and refreshes the stored flags. If Stripe cannot be reached, the last stored flags are returned instead and the Stripe-only fields (`defaultCurrency`, `country`, `businessType`, `requirementsCurrentlyDue`) are absent. With no account yet the body is `{ \"data\": { \"connected\": false } }`.\n\n**Requires permission:** `org.read_payouts`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "responses": {
          "200": {
            "description": "Connect status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OrgAdminPayoutsStatus"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Org-level Stripe Connect is turned off (`features.org_level_stripe_connect`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/children": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "List child organizations",
        "operationId": "listOrgAdminChildren",
        "description": "Organizations recorded under this one as children, newest first. Child companies are retired (`POST /org-admin/{slug}/children` answers `410`) and every organization is now a non-profit, which has none, so this is empty for every page added today.\n\n**Requires permission:** `org.read`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "responses": {
          "200": {
            "description": "Child organizations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OrgAdminChildOrganization"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Create a child organization",
        "operationId": "createOrgAdminChild",
        "deprecated": true,
        "description": "Retired: company hierarchies are no longer supported, and this creates nothing. A request that passes the checks below always answers `410`, pointing to `/nonprofits/new`. The request body below is the old child-company payload, kept for reference.\n\nRequires a **verified email address**.\n\n**Requires permission:** `org.manage_children` (organization owners only)",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "legal_name"
                ],
                "properties": {
                  "legal_name": {
                    "type": "string",
                    "maxLength": 255
                  },
                  "ein": {
                    "type": "string",
                    "pattern": "^\\d{2}-\\d{7}$",
                    "example": "12-3456789"
                  },
                  "country": {
                    "type": "string",
                    "maxLength": 64
                  },
                  "website": {
                    "type": "string",
                    "maxLength": 1024
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 4000
                  },
                  "categories": {
                    "type": "array",
                    "maxItems": 20,
                    "items": {
                      "type": "string",
                      "maxLength": 64
                    }
                  },
                  "dbas": {
                    "type": "array",
                    "maxItems": 10,
                    "description": "DBA names must be unique (case-insensitive).",
                    "items": {
                      "type": "object",
                      "properties": {
                        "dba_name": {
                          "type": "string",
                          "maxLength": 255
                        }
                      }
                    }
                  },
                  "locations": {
                    "type": "array",
                    "maxItems": 25,
                    "items": {
                      "type": "object",
                      "required": [
                        "address"
                      ],
                      "properties": {
                        "label": {
                          "type": "string",
                          "maxLength": 120
                        },
                        "address": {
                          "$ref": "#/components/schemas/OrgAdminAddress"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Email address not verified, or the caller lacks `org.manage_children`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "410": {
            "description": "Always, once the session, verified-email and permission checks pass.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Company hierarchies are no longer supported."
                    },
                    "href": {
                      "type": "string",
                      "example": "/nonprofits/new"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/documents": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "List verification documents",
        "operationId": "listOrgAdminDocuments",
        "description": "The organization's verification documents in every state except `superseded`, newest first, including review outcome and whether each is shown on the public profile.\n\nFinancial documents — `w9`, `voided_check` and `other` — are listed only when the caller also holds `org.upload_documents`; otherwise they are left out of the list. Every other type (`ein_letter`, `501c3_determination`, `officer_letter`, `group_ruling`, `reinstatement_letter`) is listed with `org.read` alone.\n\n**Requires permission:** `org.read`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "responses": {
          "200": {
            "description": "Documents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OrgAdminDocument"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Upload a verification document",
        "operationId": "uploadOrgAdminDocument",
        "description": "Uploads a document for platform review as base64 JSON. It is stored privately and enters the review queue as `pending`. Uploading a `doc_type` the organization already has pending or approved marks the older one `superseded`. Approval of an `ein_letter` or a `501c3_determination` moves a `pending` organization to `verified`.\n\nSize limit: 10 MB decoded by default, but the JSON body itself is capped at 10 MB, so in practice a file must stay under about 7.5 MB to fit once base64-encoded — larger bodies get `413` before the handler runs.\n\n**Requires permission:** `org.upload_documents`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "doc_type",
                  "content_type",
                  "file_base64"
                ],
                "properties": {
                  "doc_type": {
                    "type": "string",
                    "enum": [
                      "ein_letter",
                      "501c3_determination",
                      "w9",
                      "voided_check",
                      "other",
                      "officer_letter",
                      "group_ruling",
                      "reinstatement_letter"
                    ],
                    "description": "`officer_letter` is the signed letter `POST /nonprofits/{id}/authority/letter` points to."
                  },
                  "content_type": {
                    "type": "string",
                    "enum": [
                      "application/pdf",
                      "image/png",
                      "image/jpeg"
                    ]
                  },
                  "original_filename": {
                    "type": "string",
                    "description": "Shown back in listings and used as the download filename."
                  },
                  "file_base64": {
                    "type": "string",
                    "format": "byte",
                    "description": "The file, base64-encoded (no `data:` prefix)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Document uploaded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "org_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "doc_type": {
                          "type": "string"
                        },
                        "original_filename": {
                          "type": "string",
                          "nullable": true
                        },
                        "content_type": {
                          "type": "string"
                        },
                        "size_bytes": {
                          "type": "integer"
                        },
                        "verification_status": {
                          "type": "string",
                          "example": "pending"
                        },
                        "uploaded_by_user_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A required field is missing, `doc_type` or `content_type` is not allowed, the file is empty or too large, or `original_filename` is not a string.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Organization not found"
                }
              }
            }
          },
          "413": {
            "description": "The JSON body is over the 10 MB request limit."
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/documents/{docId}/download": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Download a verification document",
        "operationId": "downloadOrgAdminDocument",
        "description": "Streams the stored file with its original `Content-Type` and, when a filename was recorded, `Content-Disposition: attachment`. A document belonging to a different organization answers `404`.\n\nA `w9`, `voided_check` or `other` document can be downloaded only by a caller who also holds `org.upload_documents`; anyone else gets `404`, as if it did not exist.\n\n**Requires permission:** `org.read`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          },
          {
            "name": "docId",
            "in": "path",
            "required": true,
            "description": "A non-UUID answers `404 Document not found`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The file",
            "headers": {
              "Content-Disposition": {
                "description": "`attachment; filename=\"<original filename>\"` when one was recorded.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug, the document does not belong to it, or it is a `w9`, `voided_check` or `other` document and the caller lacks `org.upload_documents`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/documents/{docId}": {
      "delete": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Delete a pending verification document",
        "operationId": "deleteOrgAdminDocument",
        "description": "Withdraws a document that is still `pending`. Approved and rejected documents are kept for the audit trail and cannot be deleted — they answer `404` like a missing document.\n\n**Requires permission:** `org.upload_documents`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          },
          {
            "name": "docId",
            "in": "path",
            "required": true,
            "description": "A non-UUID answers `404 Document not found`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Document deleted"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug, or the document does not exist, belongs to another organization, or is no longer pending.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/documents/{docId}/public-visibility": {
      "patch": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Show or hide a document on the public profile",
        "operationId": "setOrgAdminDocumentPublicVisibility",
        "description": "Sets the document's public-visibility flag. The public profile (`GET /organizations/{id}/documents/public`) lists a document only when it is both flagged public **and** approved, so the flag can be set ahead of review.\n\n**Requires permission:** `org.upload_documents`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The organization's slug (not its UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9-]{0,254}$"
            },
            "example": "local-food-bank-a1b2c3"
          },
          {
            "name": "docId",
            "in": "path",
            "required": true,
            "description": "A non-UUID answers `404 Document not found`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "is_publicly_visible"
                ],
                "properties": {
                  "is_publicly_visible": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Visibility updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "is_publicly_visible": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`is_publicly_visible` is not a boolean.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller lacks the org-scoped permission named in the description.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Forbidden",
                  "message": "Requires permission: org.read"
                }
              }
            }
          },
          "404": {
            "description": "No organization has that slug, or the document does not belong to it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/locations": {
      "get": {
        "tags": [
          "Organizations"
        ],
        "summary": "List campaign locations by US state",
        "operationId": "listCampaignLocationStates",
        "description": "US states that currently have active campaigns, with a campaign count per state, sorted by state name. The state is parsed out of each campaign's free-text `location` (a two-letter code or full state name); campaigns whose location cannot be matched to a state are left out. Cached for 5 minutes. Drives the location filter on campaign browse.",
        "responses": {
          "200": {
            "description": "States with active campaigns",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string",
                            "example": "CA"
                          },
                          "name": {
                            "type": "string",
                            "example": "California"
                          },
                          "count": {
                            "type": "integer",
                            "description": "Active campaigns in this state."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/organizations/{id}/report": {
      "post": {
        "tags": [
          "Organizations"
        ],
        "summary": "Report an organization",
        "operationId": "reportOrganization",
        "description": "Flags an organization for review by FundlyHub's trust team. A signed-in caller with a **verified email address** can report; no relationship to the organization is needed. Each user holds at most one report per organization — reporting again overwrites the earlier category and details and puts the report back to `pending`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Organization UUID (a slug is not accepted and answers `404`).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "category"
                ],
                "properties": {
                  "category": {
                    "type": "string",
                    "enum": [
                      "fraud",
                      "impersonation",
                      "spam",
                      "mission_misalignment",
                      "sexual_content",
                      "hate",
                      "other"
                    ]
                  },
                  "details": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 4000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Report recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`category` missing or not in the list, or `details` not a string or over 4000 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Email address not verified.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No live organization has that id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{id}/translations": {
      "get": {
        "tags": [
          "Translations"
        ],
        "summary": "List a campaign's translations",
        "operationId": "listFundraiserTranslations",
        "description": "The Translations tab's data for one campaign: its source text and language, one row per other supported locale (fields `null` and `source: null` where nothing has been translated yet), the row in the campaign's own language if one exists (`original_row`), and every milestone with its rows.\nOnly the campaign's owner may read it.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Source text and per-locale translations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "fundraiser_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "source": {
                          "type": "object",
                          "properties": {
                            "language": {
                              "type": "string",
                              "enum": [
                                "en",
                                "ru",
                                "uk",
                                "es"
                              ]
                            },
                            "title": {
                              "type": "string"
                            },
                            "summary": {
                              "type": "string",
                              "nullable": true
                            },
                            "story_html": {
                              "type": "string",
                              "nullable": true
                            }
                          }
                        },
                        "translations": {
                          "type": "array",
                          "description": "One entry per supported locale other than the source language.",
                          "items": {
                            "$ref": "#/components/schemas/TranslationFundraiserRow"
                          }
                        },
                        "original_row": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/TranslationFundraiserRow"
                            }
                          ],
                          "nullable": true,
                          "description": "The row in the campaign's own language, if any: a field written in another language machine-translated into it, or a person's version. Readers of that language are served it."
                        },
                        "milestones": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/TranslationMilestoneEntry"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/fundraisers/{id}/translations/{lang}": {
      "put": {
        "tags": [
          "Translations"
        ],
        "summary": "Save a hand-edited campaign translation",
        "operationId": "upsertFundraiserTranslation",
        "description": "Creates or overwrites the campaign's translation in `lang` with a hand-edited version and marks it `source: \"human\"`, so automatic re-translation leaves it alone. Campaign owner only. Audit-logged.\n`lang` may not be the campaign's stored source language; that text is edited on the campaign itself.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "lang",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "summary": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 1000
                  },
                  "story_html": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 100000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The saved row",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/TranslationFundraiserSavedRow"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unsupported `lang`, `lang` is the campaign's source language, or `title` is missing or blank.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "413": {
            "description": "A field is over its limit (title 200, summary 1000, story 100,000 characters). A non-string `summary` or `story_html` also lands here.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Translations"
        ],
        "summary": "Discard a hand-edited version in the campaign's own language",
        "operationId": "discardFundraiserSourceLanguageTranslation",
        "description": "Deletes the hand-edited (`source: \"human\"`) rows in the campaign's OWN language, both the campaign's row and its milestones' rows. Such a version exists when someone edited that language while the campaign was labelled with another one; readers of that language are served it instead of the original until it is discarded. Machine rows for fields written in another language are rebuilt in the background afterwards.\nOnly works for `lang` equal to the campaign's stored source language; a translation into another language is replaced with regenerate instead. Campaign owner only. The discarded text is written to the audit log.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "lang",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "What was discarded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "language": {
                          "type": "string",
                          "enum": [
                            "en",
                            "ru",
                            "uk",
                            "es"
                          ]
                        },
                        "discarded": {
                          "type": "object",
                          "properties": {
                            "campaign": {
                              "type": "integer",
                              "description": "Campaign rows deleted (0 or 1)."
                            },
                            "milestones": {
                              "type": "integer",
                              "description": "Milestone rows deleted."
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unsupported `lang`, or `lang` is not the campaign's source language.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Campaign not found, or no hand-edited version exists in this language.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{id}/translations/{lang}/regenerate": {
      "post": {
        "tags": [
          "Translations"
        ],
        "summary": "Regenerate a campaign translation",
        "operationId": "regenerateFundraiserTranslation",
        "description": "Re-runs machine translation of the campaign into `lang` and stores it as `source: \"machine\"`. The locale's milestone rows are refreshed the same way. Campaign owner only. Audit-logged.\nA hand-edited row is not overwritten unless `force=1` (or `true`) is passed; without it the call answers `409`. It also answers `409` when the campaign text or the row changed while the translation was being generated.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "lang",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          },
          {
            "name": "force",
            "in": "query",
            "required": false,
            "description": "`1` or `true` overwrites a hand-edited row.",
            "schema": {
              "type": "string",
              "enum": [
                "1",
                "true"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The regenerated row",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/TranslationFundraiserSavedRow"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unsupported `lang`, or `lang` is the campaign's source language.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The row is hand-edited and `force` was not set, or the campaign or the row changed while the translation was generated (reload and retry).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The translation provider failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "No translation provider is configured. The body carries a `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TranslationMtError"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{id}/milestones/{milestoneId}/translations/{lang}": {
      "put": {
        "tags": [
          "Translations",
          "Milestones"
        ],
        "summary": "Save a hand-edited milestone translation",
        "operationId": "upsertMilestoneTranslation",
        "description": "Creates or overwrites one milestone's translation in `lang` as `source: \"human\"`. The milestone must belong to the campaign in the path. Campaign owner only. Audit-logged. `lang` may not be the campaign's source language.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "milestoneId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "lang",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "Trimmed before saving."
                  },
                  "description": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 2000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The saved row",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "milestone_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "language": {
                          "type": "string",
                          "enum": [
                            "en",
                            "ru",
                            "uk",
                            "es"
                          ]
                        },
                        "title": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string",
                          "nullable": true
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "human"
                          ]
                        },
                        "translated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unsupported `lang`, `lang` is the campaign's source language, or `title` is missing or blank.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Campaign not found, or the milestone does not belong to it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`title` over 200 or `description` over 2000 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{id}/updates/translations": {
      "get": {
        "tags": [
          "Translations",
          "Updates"
        ],
        "summary": "List translations of a campaign's updates",
        "operationId": "listProjectUpdateTranslations",
        "description": "Every live (not withdrawn) update of the campaign, newest first, with its original text and language and one row per other supported locale. Campaign owner only.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Updates with their translations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "fundraiser_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "updates": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/TranslationProjectUpdateEntry"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/fundraisers/{id}/updates/{updateId}/translations": {
      "get": {
        "tags": [
          "Translations",
          "Updates"
        ],
        "summary": "Get one update's translations",
        "operationId": "getProjectUpdateTranslations",
        "description": "One update of the campaign: its original and its rows in the other three locales. Campaign owner only. A withdrawn update, or one belonging to another campaign, answers `404`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "updateId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The update and its translations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "type": "object",
                          "properties": {
                            "fundraiser_id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "update_id": {
                              "type": "string",
                              "format": "uuid"
                            }
                          }
                        },
                        {
                          "$ref": "#/components/schemas/TranslationProjectUpdateEntry"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Campaign or update not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{id}/updates/{updateId}/translations/{lang}": {
      "put": {
        "tags": [
          "Translations",
          "Updates"
        ],
        "summary": "Save a hand-edited update translation",
        "operationId": "upsertProjectUpdateTranslation",
        "description": "Creates or overwrites an update's translation in `lang` as `source: \"human\"`, so no automatic pass overwrites it. Campaign owner only. Audit-logged. Refused in the update's own language. When the update has a title, the translation must carry one too.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "updateId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "lang",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "content"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 200,
                    "description": "Required when the update itself has a title. Trimmed; blank is stored as null."
                  },
                  "content": {
                    "type": "string",
                    "maxLength": 20000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The saved row",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/TranslationUpdateSavedRow"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unsupported `lang`, `lang` is the update's own language, `content` missing or blank, or `title` missing although the update has one.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Campaign or update not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`content` over 20,000 or `title` over 200 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{id}/updates/{updateId}/translations/{lang}/regenerate": {
      "post": {
        "tags": [
          "Translations",
          "Updates"
        ],
        "summary": "Regenerate an update translation",
        "operationId": "regenerateProjectUpdateTranslation",
        "description": "Re-runs machine translation of one update into `lang` and stores it as `source: \"machine\"`. A hand-edited row is only replaced with `force=1`. Campaign owner only. Audit-logged.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "updateId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "lang",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          },
          {
            "name": "force",
            "in": "query",
            "required": false,
            "description": "`1` or `true` overwrites a hand-edited row.",
            "schema": {
              "type": "string",
              "enum": [
                "1",
                "true"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The regenerated row",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/TranslationUpdateSavedRow"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unsupported `lang`, or `lang` is the update's own language.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Campaign or update not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The row is hand-edited and `force` was not set, or the update or the row changed while the translation was generated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The translation provider failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "No translation provider is configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TranslationMtError"
                }
              }
            }
          }
        }
      }
    },
    "/updates/{updateId}/translations": {
      "get": {
        "tags": [
          "Translations"
        ],
        "summary": "List a legacy update's translations",
        "operationId": "listLegacyUpdateTranslations",
        "deprecated": true,
        "description": "**Legacy.** Campaign updates are translated through `GET /fundraisers/{id}/updates/{updateId}/translations`; use that instead.\nReturns the update's source text and one row per other locale. The caller must own the parent campaign.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "updateId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Source and translations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "update_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "fundraiser_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "source": {
                          "type": "object",
                          "properties": {
                            "language": {
                              "type": "string",
                              "enum": [
                                "en",
                                "ru",
                                "uk",
                                "es"
                              ]
                            },
                            "title": {
                              "type": "string",
                              "nullable": true
                            },
                            "content": {
                              "type": "string",
                              "nullable": true
                            }
                          }
                        },
                        "translations": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/TranslationLegacyUpdateRow"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/updates/{updateId}/translations/{lang}": {
      "put": {
        "tags": [
          "Translations"
        ],
        "summary": "Save a legacy update translation",
        "operationId": "upsertLegacyUpdateTranslation",
        "deprecated": true,
        "description": "**Legacy** (see `GET /updates/{updateId}/translations`). Saves a hand-edited translation as `source: \"human\"`. Owner of the parent campaign only. Audit-logged.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "updateId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "lang",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "content"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 200
                  },
                  "content": {
                    "type": "string",
                    "maxLength": 100000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The saved row",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/TranslationUpdateSavedRow"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unsupported `lang`, `lang` is the update's source language, or `content` missing or blank.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "413": {
            "description": "`content` over 100,000 or `title` over 200 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/ai/generate-update": {
      "post": {
        "tags": [
          "AI"
        ],
        "summary": "Generate a project update",
        "operationId": "generateProjectUpdateText",
        "description": "Writes or rewrites a campaign update's text with an LLM. Requires a bearer session and is gated by the `features.ai_update_generation` flag. Throughput is capped per user inside the handler (10 requests per minute by default).\n`context.fundraiserTitle` is required. Up to three `context.previousUpdates` are folded into the prompt for `generate` and `improve`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "action",
                  "text",
                  "context"
                ],
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "generate",
                      "improve",
                      "expand",
                      "shorten"
                    ],
                    "description": "An unrecognised action answers `400`."
                  },
                  "text": {
                    "type": "string",
                    "description": "The current update, or the idea to write from when `action` is `generate`. Capped at the server's maximum length (10,000 characters by default)."
                  },
                  "context": {
                    "type": "object",
                    "required": [
                      "fundraiserTitle"
                    ],
                    "properties": {
                      "fundraiserTitle": {
                        "type": "string"
                      },
                      "fundraiserId": {
                        "type": "string",
                        "description": "Logged only."
                      },
                      "milestoneTitle": {
                        "type": "string"
                      },
                      "previousUpdates": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated text",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enhancedText": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing `action`, `text` or `context.fundraiserTitle`; unknown action; or text too long.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "AI update generation is disabled (`features.ai_update_generation` is off).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The model call failed. The body carries `details` with the provider's message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "The AI provider is not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/ai/scrape-event-url": {
      "post": {
        "tags": [
          "AI"
        ],
        "summary": "Import descriptive event details from a public URL",
        "operationId": "scrapeEventUrl",
        "description": "Requires a session and the Events feature gate (event staff retain their existing access while the feature is off). Per-account request limits apply. Reads public HTTP(S) event pages, rejects private/reserved destinations, and extracts descriptive fields for the host to review through normal draft saving. Never creates or publishes an event and never imports hosts, prices, permissions, payment settings or a schedule. The host must review the details and set the schedule before publishing.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 2048
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extracted descriptive fields for review; absent fields were not found.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "title": {
                          "type": "string",
                          "maxLength": 120
                        },
                        "subtitle": {
                          "type": "string",
                          "maxLength": 200
                        },
                        "aboutHtml": {
                          "type": "string",
                          "maxLength": 50000,
                          "description": "Sanitized rich text."
                        },
                        "coverImage": {
                          "type": "string",
                          "format": "uri",
                          "maxLength": 2048
                        },
                        "venueName": {
                          "type": "string",
                          "maxLength": 120
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "INVALID_URL — a public HTTP(S) URL is required."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Events are unavailable to this viewer."
          },
          "422": {
            "description": "EVENT_IMPORT_EMPTY — no usable event details could be extracted."
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "EVENT_IMPORT_FAILED — the import provider could not complete the request."
          },
          "503": {
            "description": "EVENT_IMPORT_UNAVAILABLE — event import is temporarily unavailable."
          }
        }
      }
    },
    "/ai/scrape-campaign-url": {
      "post": {
        "tags": [
          "AI"
        ],
        "summary": "Import a campaign from a URL",
        "operationId": "scrapeCampaignUrl",
        "description": "Reads a campaign page on another platform and extracts its fields with an LLM, for the \"import from link\" step of the campaign builder. Requires a bearer session; throughput is capped per user inside the handler (10 requests per minute by default).\nThe response carries a one-time `scrape_token`, valid for 30 minutes; pass it on `POST /fundraisers` when creating the imported campaign. When the LLM is not configured, only the page title is returned, with a `note` and no token.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "An `http` or `https` URL."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extracted campaign fields",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "The fields the model could find; any may be absent. Free-form model output; validate it before use.",
                      "properties": {
                        "title": {
                          "type": "string"
                        },
                        "summary": {
                          "type": "string"
                        },
                        "story": {
                          "type": "string"
                        },
                        "goalAmount": {
                          "type": "number",
                          "description": "Dollars."
                        },
                        "categoryName": {
                          "type": "string"
                        },
                        "beneficiaryName": {
                          "type": "string"
                        },
                        "location": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "personal",
                            "charity"
                          ]
                        },
                        "isProject": {
                          "type": "boolean"
                        },
                        "coverImage": {
                          "type": "string"
                        },
                        "galleryImages": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "platform": {
                      "type": "string",
                      "nullable": true,
                      "description": "The source platform, when recognised."
                    },
                    "scrape_token": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "note": {
                      "type": "string",
                      "description": "Present only when the LLM is not configured."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`url` is missing or not a string.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "description": "The page could not be scraped: invalid or non-HTTP URL, scraping not configured, too little content, a timeout, or the scraper's own rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The extraction failed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/campaigns/{id}/stats": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Get campaign stats (broken)",
        "operationId": "getCampaignStatsLegacy",
        "deprecated": true,
        "description": "**Not available: currently answers `500` for every campaign.** Use `GET /fundraisers/{id}/stats` instead.\nIntended as a public stat-tile read: raised and goal (cents), donor, update and view counts, dates and days left.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Campaign stats (bare object; not currently reachable)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "title": {
                      "type": "string"
                    },
                    "raised": {
                      "type": "string",
                      "description": "Cents, as a numeric string."
                    },
                    "goal": {
                      "type": "string",
                      "description": "Cents, as a numeric string."
                    },
                    "donor_count": {
                      "type": "string"
                    },
                    "update_count": {
                      "type": "string"
                    },
                    "view_count": {
                      "type": "string"
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "end_date": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "days_left": {
                      "type": "integer",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "description": "Always, today.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/slug/{slug}/og-image": {
      "get": {
        "tags": [
          "Shares"
        ],
        "summary": "Campaign link-preview image",
        "operationId": "getFundraiserOgImage",
        "description": "A 1200×630 PNG Open Graph card for the campaign: title, cover, organizer, raised and goal amounts and donor count. Public; served to social crawlers.\nOnly a campaign anyone may open by link (live, ended or paused; not private; not deleted) has an image. Any other campaign is a `404`, the same as an unknown slug, for every caller.\nThe language comes from `?lang=`, else the locale cookie, else `Accept-Language`, else the original text. Without `?lang=` the response varies on `Accept-Language, Cookie`. Cached for 30 seconds.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Language to render in. Without it the locale cookie, then `Accept-Language`, decide.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "PNG image",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Rendering failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/slug/{slug}/share-poster": {
      "get": {
        "tags": [
          "Shares"
        ],
        "summary": "Campaign square share poster",
        "operationId": "getFundraiserSharePoster",
        "description": "A 1080×1080 PNG for feed posts (Instagram and similar). Same data, language rules, caching and `404` for a campaign that is not readable by link as the link-preview image.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Language to render in. Without it the locale cookie, then `Accept-Language`, decide.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "PNG image",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Rendering failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/slug/{slug}/share-story": {
      "get": {
        "tags": [
          "Shares"
        ],
        "summary": "Campaign story card",
        "operationId": "getFundraiserShareStory",
        "description": "A 1080×1920 PNG for Instagram and Facebook Stories. Same data, language rules, caching and `404` for a campaign that is not readable by link as the link-preview image.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Language to render in. Without it the locale cookie, then `Accept-Language`, decide.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "PNG image",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Rendering failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/slug/{slug}/share-kit.zip": {
      "get": {
        "tags": [
          "Shares"
        ],
        "summary": "Campaign share kit",
        "operationId": "getFundraiserShareKit",
        "description": "The link-preview image, the square poster and the story card in one zip download (`<slug>-link.png`, `<slug>-post.png`, `<slug>-story.png`), as linked from the ambassador endorsement-request email. Same language rules, 30-second caching and `404` for a campaign that is not readable by link as the single images. All three must render, or the call answers `404`.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Language to render in. Without it the locale cookie, then `Accept-Language`, decide.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Zip archive, sent as an attachment named `<slug>-share-kit.zip`",
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Rendering or packaging failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{id}/share-impact": {
      "get": {
        "tags": [
          "Shares"
        ],
        "summary": "Get a campaign's share impact",
        "operationId": "getFundraiserShareImpact",
        "description": "What sharing has done for this campaign, all-time: human visits that arrived through a shared link, how many came through endorsers' links, and the paid or refunded, non-self-referred gifts traced back to a share, valued at what they raised (net of fees, tips excluded). Public. A campaign nobody has shared returns zeros. Readable exactly when `GET /fundraisers/{id}` is: a campaign that is not `active`, `paused` or `ended`, is `private`, or has been deleted answers `404` to everyone but its owner. Authentication is optional.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID; anything else answers `400`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Share impact (bare object)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "impressions": {
                      "type": "integer",
                      "description": "Human visits through a shared link."
                    },
                    "viaEndorsers": {
                      "type": "integer",
                      "description": "The part of `impressions` that came through endorsers' links."
                    },
                    "gifts": {
                      "type": "integer"
                    },
                    "donors": {
                      "type": "integer"
                    },
                    "value": {
                      "type": "number",
                      "description": "What those gifts raised, net of fees, tips excluded, in DOLLARS (major units, to the cent)."
                    },
                    "currencies": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Currencies present among those gifts; more than one means `value` is a mixed total."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{id}/share-channels": {
      "get": {
        "tags": [
          "Shares"
        ],
        "summary": "Get a campaign's shares per channel",
        "operationId": "getFundraiserShareChannels",
        "description": "Human clicks through shared links, and the gifts they led to, per share channel, all-time. Every channel is present, with zeros when none. Public. Readable exactly when `GET /fundraisers/{id}` is: a campaign that is not `active`, `paused` or `ended`, is `private`, or has been deleted answers `404` to everyone but its owner. Authentication is optional.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID; anything else answers `400`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Per-channel stats (bare object)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "$ref": "#/components/schemas/ShareChannelStat"
                    },
                    "channels": {
                      "type": "object",
                      "description": "One entry per channel: `copy_link`, `facebook`, `story`, `whatsapp`, `instagram`, `text`, `messenger`, `linkedin`, `email`, `x`, `qr` (links stamped `utm_source=qr`; the fundraiser's QR codes carry plain links, so their scans count with the link they open), `native`.",
                      "additionalProperties": {
                        "$ref": "#/components/schemas/ShareChannelStat"
                      }
                    },
                    "unattributed": {
                      "$ref": "#/components/schemas/ShareChannelStat"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{id}/assess": {
      "post": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Run a pre-publish trust assessment",
        "operationId": "assessFundraiser",
        "description": "Runs the full trust assessment the platform applies at publish time, without publishing: profile and campaign blockers, suggestions, a trust score, an AI analysis of the story, and the moderation decision it would lead to. No request body. Campaign owner only.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Assessment (bare object)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FundraiserTrustAssessment"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/fundraisers/{id}/activity": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Get a campaign's lifecycle timeline",
        "operationId": "getFundraiserActivity",
        "description": "Lifecycle events (created, submitted for review, approved, rejected, updated, update posted, goal reached, deleted), newest first, with who acted. Campaign owner only; works for soft-deleted campaigns too.\nActions taken by FundlyHub staff appear with `role: \"admin\"` and null id, name and email.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Timeline (unwrapped)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "activity": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FundraiserActivityEntry"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "description": "The timeline could not be read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{id}/end": {
      "post": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "End a live campaign",
        "operationId": "endFundraiser",
        "description": "Ends a live campaign now, below its goal or not. Donations stay open unless `keep_donations_open` is false. The owner, a platform admin, or staff holding `manage_campaigns` (the callers the detail read's `viewer.actions.end` allows; it is allowed only for a live campaign not already past its end date). The answer carries the updated `viewer` block. 409 codes: ALREADY_ENDED, PAUSED, NOT_ACTIVE.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "keep_donations_open": {
                    "type": "boolean",
                    "default": true,
                    "description": "False stops donations as the campaign ends."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The campaign after the change, with its fundraising state",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "fundraising": {
                          "$ref": "#/components/schemas/FundraisingState"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Not signed in"
          },
          "403": {
            "description": "Not allowed"
          },
          "404": {
            "description": "Fundraiser not found"
          },
          "409": {
            "description": "The campaign's state does not allow it; `code` says why",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{id}/stop-donations": {
      "post": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Stop donations to an ended campaign",
        "operationId": "stopFundraiserDonations",
        "description": "Stops fundraising on an ended campaign: nobody can donate after this, and the donate action becomes find_similar. A live campaign whose end date has passed is ended by its deadline in the same step. The owner, a platform admin, or staff holding `manage_campaigns`. 409 codes: ALREADY_STOPPED, NOT_ENDED.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The campaign after the change, with its fundraising state",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "fundraising": {
                          "$ref": "#/components/schemas/FundraisingState"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Not signed in"
          },
          "403": {
            "description": "Not allowed"
          },
          "404": {
            "description": "Fundraiser not found"
          },
          "409": {
            "description": "The campaign's state does not allow it; `code` says why",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{id}/report": {
      "post": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Report a campaign",
        "operationId": "reportFundraiser",
        "description": "Flags an active campaign for moderator review. One report per user per campaign: reporting again replaces the earlier reason and details. Requires a verified email address.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reason"
                ],
                "properties": {
                  "reason": {
                    "type": "string",
                    "minLength": 5,
                    "description": "Trimmed; at least 5 characters."
                  },
                  "details": {
                    "type": "string",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Report recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`reason` shorter than 5 characters, or the campaign is not `active`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Email address not verified (`code: EMAIL_NOT_VERIFIED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/fundraisers/{id}/contact": {
      "post": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Contact the organizer",
        "operationId": "contactFundraiserOrganizer",
        "description": "Sends a message to the campaign's organizer by email. The organizer receives it with the sender's `email` as the reply address and answers by replying, so the organizer's own address is never revealed unless they reply. Authentication is optional: anyone who can read the campaign may write, with the same visibility rule as `GET /fundraisers/{id}` (a campaign hidden from the caller answers `404`). Limited to five messages an hour per client address and, when signed in, per account. A message with more than three links is refused, and the name may contain none.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "message"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 254,
                    "description": "Where the organizer's reply goes. Trimmed."
                  },
                  "message": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 2000,
                    "description": "Plain text, trimmed; 1 to 2000 characters, at most three links."
                  },
                  "name": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 100,
                    "description": "How the sender signs the message; the email address is shown when it is omitted. Control characters are removed."
                  }
                }
              },
              "example": {
                "email": "jane@example.com",
                "name": "Jane",
                "message": "Hi! Is there a way to help other than donating?"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The message was accepted for delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sent": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error. `details` lists each problem with its field `path` (`email`, `message` or `name`), a readable `message`, and a `code` — `too_many_links` and `link_in_name` for the link rules, otherwise the validator's own code (e.g. `invalid_string`, `too_small`, `too_big`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Validation error"
                    },
                    "details": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "path": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "message": {
                            "type": "string"
                          },
                          "code": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{id}/donor-highlight": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Get the featured donor for a campaign",
        "operationId": "getFundraiserDonorHighlight",
        "description": "Feeds the campaign page's \"{name} and N others have donated\" row: one featured donor and up to three faces, chosen from the latest 100 paid, non-anonymous gifts. Authentication is optional and only changes WHO is featured: a signed-in viewer sees people they follow, or who follow them, first. Only public campaigns that are active, paused or ended return donors; anything else returns empty.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID; anything else answers `400`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Featured donor (bare object)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "featured": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/DonorFace"
                        }
                      ],
                      "nullable": true
                    },
                    "avatars": {
                      "type": "array",
                      "maxItems": 3,
                      "items": {
                        "$ref": "#/components/schemas/DonorFace"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{id}/related": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Get related campaigns",
        "operationId": "getRelatedFundraisers",
        "description": "Four lists of other people's live, public campaigns for the discovery rail at the bottom of a campaign page: same category (`similar`), same US state (`nearby`), 70–99% funded (`almost`) and newest (`recent`). An empty list means that tab is not shown. Public.\nTitles and summaries are in the reader's language (`?lang=`, then the locale cookie, then `Accept-Language`) when a translation exists; when a language is resolved, each card also carries `translation_source` and, where the text was replaced, `original_title` / `original_summary`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID; anything else answers `400`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Cards per list, clamped to 1–12.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 12,
              "default": 12
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The four lists (bare object)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "similar": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RelatedCampaign"
                      }
                    },
                    "nearby": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RelatedCampaign"
                      }
                    },
                    "almost": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RelatedCampaign"
                      }
                    },
                    "recent": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RelatedCampaign"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{fundraiserId}/top-donors": {
      "get": {
        "tags": [
          "Donations"
        ],
        "summary": "Get a campaign's top donors",
        "operationId": "getFundraiserTopDonors",
        "description": "The campaign's biggest donors, one row per person across all their paid gifts. Anonymous donors keep their total but not their name; they are identified by an opaque `anonymous_key`. When any donor gave in more than one currency, `meta.mixed_currency` is true and the totals should not be shown. Public.\nOnly a campaign anyone may open by link (live, ended or paused; not private; not deleted) has a public ranking. For any other campaign the answer is an empty `data` array, the same as for an unknown id, unless the caller is signed in as the campaign's owner or an admin.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "fundraiserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Rows to return, clamped to 1–25.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Top donors",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "The donor's key; for anonymous donors the same value as `anonymous_key`."
                          },
                          "anonymous_key": {
                            "type": "string",
                            "nullable": true
                          },
                          "is_anonymous": {
                            "type": "boolean"
                          },
                          "donor_name": {
                            "type": "string",
                            "nullable": true
                          },
                          "donor_avatar": {
                            "type": "string",
                            "nullable": true
                          },
                          "total_cents": {
                            "type": "integer"
                          },
                          "donation_count": {
                            "type": "integer"
                          },
                          "last_donation_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "currency": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "mixed_currency": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/cities": {
      "get": {
        "tags": [
          "Cities"
        ],
        "summary": "List cities",
        "operationId": "listCities",
        "description": "Every city with a verified Fundly or a donor, not hidden by staff. Cities below the page threshold are included with `has_page: false` (show them as plain text). `totals` are platform-wide and ignore `q` and `area`. `near_you` is the nearest city with a page within 100 miles of `near`, else of the edge's viewer location headers when present, else of the signed-in viewer's profile city (that city itself when it has a page); `null` otherwise. A malformed `near` is not an error: it is ignored, the location headers are not read, and only the profile city is tried. Authentication is optional and only feeds `near_you`.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Matches the city name or its metro's name."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "az"
              ],
              "default": "active"
            },
            "description": "`active`: the most live Fundlies first, then donors, then raised, then by name. `az`: by name."
          },
          {
            "name": "area",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "us",
                "intl"
              ],
              "default": "all"
            }
          },
          {
            "name": "near",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "38.58,-121.49"
            },
            "description": "A `lat,lng` point for `near_you`."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 24
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of cities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CityCard"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "totals": {
                      "type": "object",
                      "properties": {
                        "cities": {
                          "type": "integer",
                          "description": "Every city with a verified Fundly or a donor (or a page staff forced on), never a hidden one. The leaderboard's all-time cities board ranks exactly these, and `GET /platform/numbers` publishes this count as `cities`."
                        },
                        "us_cities": {
                          "type": "integer"
                        },
                        "countries": {
                          "type": "integer"
                        },
                        "us_states": {
                          "type": "integer"
                        },
                        "fundlies": {
                          "type": "integer"
                        },
                        "fundly_cities": {
                          "type": "integer"
                        },
                        "raised_cents": {
                          "type": "integer",
                          "description": "The sum of `raised_cents` over the cities: the campaign cards of every verified Fundly placed in a city (net of the Stripe fee, tips excluded)."
                        },
                        "donors": {
                          "type": "integer",
                          "description": "Distinct donors who live in a city, each person once."
                        }
                      }
                    },
                    "near_you": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/CityCard"
                        }
                      ],
                      "nullable": true
                    },
                    "map_version": {
                      "type": "string",
                      "example": "1792000000-412",
                      "description": "Changes whenever any city changes (a new city, a moved point, a new photo). Add it as `v` to the map snapshot URLs so a cached image is never older than the cities it shows."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/cities/map": {
      "get": {
        "tags": [
          "Cities"
        ],
        "summary": "City map dots",
        "operationId": "getCityMap",
        "description": "One dot per city with a verified Fundly or a donor. Donor counts are exact; null when none.",
        "parameters": [
          {
            "name": "scope",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "us",
                "world"
              ],
              "default": "world"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The dots",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "points": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CityMapPoint"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/cities/map/snapshot": {
      "get": {
        "tags": [
          "Cities"
        ],
        "summary": "The cities map as an image",
        "operationId": "getCityMapSnapshot",
        "description": "A redirect to a signed Apple Maps Web Snapshot with the same dots when a MapKit key is configured, else the static map: an SVG of Natural Earth outlines with the dots, in Web Mercator. Use it as an image source; it works for both answers.",
        "parameters": [
          {
            "name": "scope",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "us",
                "world"
              ],
              "default": "us"
            }
          },
          {
            "name": "w",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 64,
              "maximum": 2048,
              "default": 1152
            }
          },
          {
            "name": "h",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 64,
              "maximum": 2048,
              "default": 480
            }
          },
          {
            "name": "scheme",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "light",
                "dark"
              ],
              "default": "light"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The static map",
            "content": {
              "image/svg+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "302": {
            "description": "Redirect to a signed Snapshot image"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/cities/unsubscribe": {
      "get": {
        "tags": [
          "Cities"
        ],
        "summary": "The one-click opt-out page",
        "operationId": "previewCityUnsubscribe",
        "description": "The link in every city email. Reads only (mail scanners prefetch links): an HTML page with a button that posts back, or the state as JSON when the caller asks for `application/json`.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "digest",
                "instant"
              ],
              "default": "digest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The page, or the state",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CityUnsubscribeState"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "The token is not one we issued"
          }
        }
      },
      "post": {
        "tags": [
          "Cities"
        ],
        "summary": "One-click opt-out",
        "operationId": "applyCityUnsubscribe",
        "description": "The `List-Unsubscribe-Post` target (RFC 8058) and the page's button: turns off that city's weekly digest (`kind=digest`) or instant alerts (`kind=instant`) for the follow the token names, and keeps the follow. Idempotent. No session: the token is the authorization. A mail client gets JSON; a browser form (it asks for `text/html`) is redirected to Settings, `/profile/settings?city_digest_off={slug}` for a digest.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "digest",
                "instant"
              ],
              "default": "digest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Turned off",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CityUnsubscribeState"
                    }
                  }
                }
              }
            }
          },
          "303": {
            "description": "Turned off; a browser form is sent on to Settings"
          },
          "404": {
            "description": "The token is not one we issued"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/cities/{slug}": {
      "get": {
        "tags": [
          "Cities"
        ],
        "summary": "Get a city page",
        "operationId": "getCity",
        "description": "One city page. `404` (`CITY_NOT_FOUND`) unless the city has a page: 1+ verified Fundly or 1+ donor, or forced on by staff, and never while hidden. A slug retired by a rename or a merge serves the surviving city: `city.slug` is canonical, and a page should redirect to it when it differs. Authentication is optional and personalizes `follow`, the community and non-profit cards (whether the caller is in or follows each) and the sponsor cards (which perks the caller can use, nearest first from their place); render the page server-side without it. The city's businesses (`sponsors`, `stats.sponsors`) are sent only while sponsors are on for everyone.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "sacramento-ca"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            },
            "description": "Fundly titles in this language where a translation exists."
          }
        ],
        "responses": {
          "200": {
            "description": "The city",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CityPage"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/cities/{slug}/snapshot": {
      "get": {
        "tags": [
          "Cities"
        ],
        "summary": "A city's map as an image",
        "operationId": "getCitySnapshot",
        "description": "The map around one city (about 27 km across) with its dots: a redirect to a signed Apple Maps Web Snapshot when a MapKit key is configured, else the static SVG. `404` unless the city has a page.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "w",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 64,
              "maximum": 2048,
              "default": 640
            }
          },
          {
            "name": "h",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 64,
              "maximum": 2048,
              "default": 360
            }
          },
          {
            "name": "scheme",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "light",
                "dark"
              ],
              "default": "light"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The static map",
            "content": {
              "image/svg+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "302": {
            "description": "Redirect to a signed Snapshot image"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/cities/{slug}/follow": {
      "get": {
        "tags": [
          "Cities"
        ],
        "summary": "My follow of a city",
        "operationId": "getCityFollow",
        "description": "The signed-in caller's follow block for one city: whether they follow it, their weekly digest and instant-alert switches (digest on and instant off when they do not follow), the follower count (`null` below 5) and up to three friends who follow it. It answers for any city the slug names (a retired slug too), even one that is hidden or has no public page, where `PUT` answers `404`. An unknown slug answers `404` (`code: CITY_NOT_FOUND`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The follow block",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CityFollowBlock"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "tags": [
          "Cities"
        ],
        "summary": "Follow a city, or change its notifications",
        "operationId": "putCityFollow",
        "description": "Idempotent. Creates the follow with the defaults (weekly digest on, instant alerts off) or changes only the switches given. The bell on the city page sends both `false` to silence a city without unfollowing. `404` when the city has no page.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "digest": {
                    "type": "boolean"
                  },
                  "instant": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The follow block after the change",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CityFollowBlock"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "Cities"
        ],
        "summary": "Unfollow a city",
        "operationId": "deleteCityFollow",
        "description": "Idempotent. Works even after the city lost its page.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The follow block after the change",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CityFollowBlock"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/me/city-follows": {
      "get": {
        "tags": [
          "Cities"
        ],
        "summary": "Cities I follow",
        "operationId": "listMyCityFollows",
        "description": "Settings > Notifications > Cities you follow, newest first, and the Settings > Privacy switch `show_followed_cities_to_friends` (change it with `PATCH /users/{id}`). Change a city's switches with `PUT /cities/{slug}/follow`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The follows",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "city": {
                            "type": "object",
                            "properties": {
                              "slug": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "photo_url": {
                                "type": "string",
                                "nullable": true
                              },
                              "has_page": {
                                "type": "boolean"
                              }
                            }
                          },
                          "digest": {
                            "type": "boolean"
                          },
                          "instant": {
                            "type": "boolean"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "show_followed_cities_to_friends": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/maps/token": {
      "get": {
        "tags": [
          "Cities"
        ],
        "summary": "MapKit JS token",
        "operationId": "getMapToken",
        "description": "The token MapKit JS initializes with. Minted (a 30-minute ES256 token for this site's origin) when the server holds a MapKit key, else the static token configured for the site (`expires_at` null when it has no expiry), else `503` with code `MAPKIT_NOT_CONFIGURED`, and the page keeps its static map. Never cached.",
        "responses": {
          "200": {
            "description": "A token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "description": "Maps are not configured (code `MAPKIT_NOT_CONFIGURED`)."
          }
        }
      }
    },
    "/success-stories": {
      "get": {
        "tags": [
          "Success Stories"
        ],
        "summary": "List success stories",
        "operationId": "listSuccessStories",
        "description": "Every Fundly that has ended (status `ended`, or live with its end date passed), raised more than $0 and passes the safety gates: not deleted, public, its organization not deleted or suspended and under no legal hold, its owner not suspended or banned, not under review, no pending report and no open dispute. There is no opt-in. A story staff hid is left out.\n\n`featured` is the staff pick, else the newest published story; it is left out of `data` and of `pagination.total`. `counts` count every story, the featured one included. `stats` are the live platform figures (the same cached numbers as `GET /platform/numbers`), `null` when they cannot be read.",
        "parameters": [
          {
            "name": "filter",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "fully_funded",
                "ended",
                "closed"
              ],
              "default": "all"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "recent",
                "raised"
              ],
              "default": "recent"
            },
            "description": "`recent` orders by `finished_at`, newest first; `raised` by raised, most first."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 48,
              "default": 24
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            },
            "description": "Titles in this language where a translation exists. Falls back to the language cookie, then Accept-Language."
          }
        ],
        "responses": {
          "200": {
            "description": "One page of stories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/StoryCard"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        }
                      }
                    },
                    "counts": {
                      "type": "object",
                      "properties": {
                        "all": {
                          "type": "integer"
                        },
                        "fully_funded": {
                          "type": "integer"
                        },
                        "ended": {
                          "type": "integer"
                        },
                        "closed": {
                          "type": "integer"
                        }
                      }
                    },
                    "featured": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/StoryCard"
                        }
                      ],
                      "nullable": true
                    },
                    "stats": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "raised_cents": {
                          "type": "integer",
                          "description": "Money credited to the causes, all time."
                        },
                        "donations": {
                          "type": "integer",
                          "description": "Settled gifts, all time."
                        },
                        "fundlies": {
                          "type": "integer",
                          "description": "Fundlies that passed approval, all time."
                        },
                        "cities": {
                          "type": "integer",
                          "description": "Distinct donor cities seen."
                        },
                        "as_of": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown `filter` or `sort`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/success-stories/{slug}": {
      "get": {
        "tags": [
          "Success Stories"
        ],
        "summary": "Get one success story",
        "operationId": "getSuccessStory",
        "description": "One Fundly's success story page. `404` unless the Fundly is a success story right now (the same gates as the list) and staff have not hidden it. The Fundly's own slug is accepted too; `card.slug` is the canonical one. `story` is `null` until the organizer-approved story is published; the record is always there, computed live. Anonymous donors are shown as `Anonymous`.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The story",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessStoryPage"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{id}/success-story": {
      "get": {
        "tags": [
          "Success Stories"
        ],
        "summary": "Get my Fundly's success story, any status",
        "operationId": "getMySuccessStory",
        "description": "The owner's view of their Fundly's success story: the whole row in any status, draft text included, and what they may do. Creates the draft row on first read when the Fundly is eligible and the pipeline has not made it yet. Owner only: anyone else gets `403` with `code: NOT_OWNER`, no session `401 UNAUTHORIZED`, no story `404 NOT_FOUND`. Every refusal on these three operations is `{ error, code }`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The Fundly (fundraiser) id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The story",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessStoryOwnerView"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller does not own the Fundly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such Fundly, or it has no success story and is not eligible for one.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Success Stories"
        ],
        "summary": "Edit my Fundly's success story",
        "operationId": "updateMySuccessStory",
        "description": "The owner edits their story directly, in every status but `hidden` (`409 INVALID_STATUS`). `headline`, `dek` and `ask_excerpt` may change only before publish (`409 PUBLISHED_FIELD_LOCKED` after; sending the unchanged value is fine). Before publish, any change clears `organizer_approved_at` (an `approved` story goes back to `organizer_review`). On a published story the edit is live at once, audit-logged with the old and new values, and staff are notified.\n\n`photo_url` must be an image uploaded through `POST /storage/upload` (bucket `fundraiser-images`), the same check the campaign media uses. `ask_excerpt` must be quoted word for word from the Fundly's own story (`400 VALIDATION_ERROR`). Send only the fields that change; `null` or an empty string clears a text field.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "headline": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 200
                  },
                  "dek": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 400
                  },
                  "ask_excerpt": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 1000
                  },
                  "money_text": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 5000
                  },
                  "breakdown": {
                    "type": "array",
                    "maxItems": 20,
                    "items": {
                      "$ref": "#/components/schemas/SuccessStoryBreakdownRow"
                    }
                  },
                  "photo_url": {
                    "type": "string",
                    "nullable": true
                  },
                  "photo_caption": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 300
                  },
                  "now_text": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 5000
                  },
                  "gifts_purpose": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 200
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The story after the edit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessStoryOwnerView"
                }
              }
            }
          },
          "400": {
            "description": "A field is too long, the breakdown is malformed, the photo was not uploaded through FundlyHub, or the excerpt is not verbatim (`code` says which).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller does not own the Fundly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "`INVALID_STATUS` (hidden) or `PUBLISHED_FIELD_LOCKED`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{id}/success-story/approve": {
      "post": {
        "tags": [
          "Success Stories"
        ],
        "summary": "Approve my Fundly's success story",
        "operationId": "approveMySuccessStory",
        "description": "The organizer approves the words: sets `organizer_approved_at` and `written_with_user_id`, the status becomes `approved`, and staff are notified. Allowed from `draft` and `organizer_review`; approving an approved story again is a no-op; `409 NOT_IN_REVIEW` once published or hidden. Nothing is published without this approval. Owner only.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The approved story",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessStoryOwnerView"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller does not own the Fundly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "`NOT_IN_REVIEW`: the story is published or hidden.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{id}/outcome-report": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Get a campaign's outcome report",
        "operationId": "getFundraiserOutcomeReport",
        "description": "The creator's published account of what the money did. Returns `{ \"report\": null }` (not `404`) when there is no report, when it is still a draft, and when FundlyHub has hidden it; the three cases are deliberately indistinguishable. Authentication is accepted and does not change the report; owners read their draft from `/mine`. The campaign itself is readable exactly when `GET /fundraisers/{id}` is: a campaign that is not `active`, `paused` or `ended`, is `private`, or has been deleted answers `404` to everyone but its owner.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The published report, or null",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/OutcomeReport"
                        }
                      ],
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Save or publish the outcome report",
        "operationId": "saveFundraiserOutcomeReport",
        "description": "Creates or replaces the campaign's single outcome report, and with `publish: true` publishes it in the same call. Publishing is one-way: a published report stays published on later saves, and `publishedAt` keeps its first value. Only the campaign's owner may write it. The body is sanitised as rich text; the title is plain text. Shares the media-upload rate limit (30 per 15 minutes). Audit-logged.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "body"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 200
                  },
                  "body": {
                    "type": "string",
                    "maxLength": 20000,
                    "description": "Rich text (HTML). Required after trimming."
                  },
                  "attachments": {
                    "type": "array",
                    "maxItems": 12,
                    "description": "Photos uploaded through `POST /storage/upload`; every URL must be one of the platform's own upload URLs. Duplicates are rejected.",
                    "items": {
                      "$ref": "#/components/schemas/OutcomeReportAttachment"
                    }
                  },
                  "invoice_count": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Self-reported. A numeric string is accepted; omitted means 0."
                  },
                  "publish": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The saved report",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "$ref": "#/components/schemas/OutcomeReport"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`body` missing or too long, `title` too long, invalid attachments, or invalid `invoice_count`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller does not own the campaign.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{id}/outcome-report/mine": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Get my campaign's outcome report, draft included",
        "operationId": "getMyFundraiserOutcomeReport",
        "description": "The owner's view of the outcome report: a draft is returned, and a hidden report is returned with `hiddenAt` set. `{ \"report\": null }` when none has been written. Campaign owner only.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The report, or null",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/OutcomeReport"
                        }
                      ],
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller does not own the campaign.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/fundraisers/{id}/endorsements": {
      "get": {
        "tags": [
          "Endorsements"
        ],
        "summary": "List a campaign's endorsers",
        "operationId": "listFundraiserEndorsers",
        "description": "Who stands behind a campaign: everyone who endorsed it, plus everyone whose share link for it recorded a visit, minus the organizer and profiles set to private. Ordered by impressions (human visits through their link). Authentication is optional; with a session, `viewerHasEndorsed` says whether the caller is on the list. A deleted campaign returns an empty list.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID; anything else answers `400`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Endorsers (unwrapped)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "endorsers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CampaignEndorser"
                      }
                    },
                    "viewerHasEndorsed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{id}/endorse": {
      "post": {
        "tags": [
          "Endorsements"
        ],
        "summary": "Endorse a campaign",
        "operationId": "endorseFundraiser",
        "description": "Publicly vouches for a campaign as the signed-in user, with an optional note. Idempotent: endorsing again updates the note and answers `200` with `created: false`; a new endorsement answers `201` and notifies the campaign owner.\nOnly public campaigns that are `active`, `paused` or `ended` can be endorsed, and not your own.\n**Requires permission:** `endorse_campaigns`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID; anything else answers `400`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "note": {
                    "type": "string",
                    "maxLength": 280,
                    "description": "Trimmed; blank is stored as null."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing endorsement updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EndorsementResult"
                }
              }
            }
          },
          "201": {
            "description": "Endorsement created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EndorsementResult"
                }
              }
            }
          },
          "400": {
            "description": "`id` is not a UUID, or the note is over 280 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Campaign not found (`code: not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EndorsementError"
                }
              }
            }
          },
          "409": {
            "description": "The campaign is not public or not in an endorsable status (`code: not_endorsable`), or it is your own (`code: self_endorsement`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EndorsementError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Endorsements"
        ],
        "summary": "Withdraw an endorsement",
        "operationId": "unendorseFundraiser",
        "description": "Revokes the caller's live endorsement of the campaign and notifies the owner.\n**Requires permission:** `endorse_campaigns`",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID; anything else answers `400`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Revoked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "revoked": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "The caller has no live endorsement of this campaign.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{id}/endorsement-requests": {
      "post": {
        "tags": [
          "Endorsements"
        ],
        "summary": "Ask ambassadors to promote a campaign",
        "operationId": "createEndorsementRequests",
        "description": "Asks up to 12 ambassadors at once to promote the caller's campaign. Campaign owner only; no special permission is needed. Requires a verified email address.\nIds that are not current ambassadors (and the caller's own id) are dropped and listed in `rejected`. When the campaign is public and `active`, the ambassadors are emailed now (`status: \"sent\"`); otherwise the requests are queued and sent when the campaign is approved (`status: \"queued\"`). Asking the same ambassador again refreshes the request rather than duplicating it.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID; anything else answers `400`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ambassadorIds"
                ],
                "properties": {
                  "ambassadorIds": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 12,
                    "description": "Profile ids, deduplicated before the cap is applied. Any malformed id rejects the whole call.",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Requests recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "requests": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EndorsementRequest"
                      }
                    },
                    "notified": {
                      "type": "integer",
                      "description": "Emails sent by this call. Can exceed this call's rows when earlier queued requests were drained too."
                    },
                    "queued": {
                      "type": "integer",
                      "description": "This call's requests still waiting."
                    },
                    "rejected": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "format": "uuid"
                      }
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "sent",
                        "queued"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid campaign id, `ambassadorIds` not an array of UUIDs, empty, over 12, or none of them an available ambassador (that body also carries `rejected`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller does not own the campaign, or their email is not verified.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "Endorsements"
        ],
        "summary": "List a campaign's endorsement requests",
        "operationId": "listEndorsementRequests",
        "description": "Who the owner has asked to promote the campaign, newest first, and whether each has been emailed yet. Campaign owner only.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The campaign's UUID; anything else answers `400`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Requests (unwrapped)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "requests": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EndorsementRequest"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The caller does not own the campaign.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/images/proxy": {
      "get": {
        "tags": [
          "Images"
        ],
        "summary": "Proxy an allowlisted image",
        "operationId": "proxyImage",
        "description": "Streams an image from the platform's CDN or `images.unsplash.com`, for local development. Public. The upstream body and `Content-Type` are passed through with a 24-hour cache header; the upstream status code is not, so an upstream error page also arrives as `200`.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The upstream image",
            "content": {
              "image/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "`url` missing or not a valid URL.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The host is not on the allowlist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The upstream fetch failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/images/features": {
      "get": {
        "tags": [
          "Images"
        ],
        "summary": "Which image features are available",
        "operationId": "getImageFeatures",
        "description": "Whether stock-photo search and AI image generation are configured on this deployment. Public.",
        "responses": {
          "200": {
            "description": "Feature availability",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "stockPhotos": {
                      "type": "boolean"
                    },
                    "aiGeneration": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/images/search": {
      "get": {
        "tags": [
          "Images"
        ],
        "summary": "Search stock photos",
        "operationId": "searchStockPhotos",
        "description": "Searches Unsplash for landscape photos. Requires a bearer session. When a photo is chosen, call `POST /images/track-download` with its `downloadLocation`, as Unsplash's terms require.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 30,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/StockPhoto"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "totalPages": {
                      "type": "integer"
                    },
                    "page": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`q` is missing or blank.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "503": {
            "description": "Unsplash is not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "An Unsplash error, answered with Unsplash's own status code (`403` means its rate limit).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/images/generate": {
      "post": {
        "tags": [
          "Images"
        ],
        "summary": "Generate a cover image with AI",
        "operationId": "generateAiCoverImage",
        "description": "Generates a landscape campaign cover from a prompt (the first 500 characters are used, wrapped in a fixed style prompt). Requires a bearer session.\nWith the default `gpt-image-*` model the image is stored on the platform CDN immediately and `persisted` is true; that path is also gated by `features.image_uploads` and answers `403` when the flag is off. With a `dall-e-*` model the URL is OpenAI's temporary one (`persisted: false`) and should be copied with `POST /images/save-from-url`.\nLimited to 10 generations an hour and 30 a day per user; past either limit the answer is `429` with `Retry-After`. Errors from the image provider are not passed through: a prompt the provider refuses answers `400`, a temporarily unavailable provider `503`, and any other provider failure `502`, each with a generic message.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "prompt"
                ],
                "properties": {
                  "prompt": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated image",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "revisedPrompt": {
                      "type": "string"
                    },
                    "persisted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`prompt` missing or blank, or the prompt could not be used to generate an image (try a different description).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Image uploads are disabled (`features.image_uploads`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "No image came back, or storing it failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Image generation failed. The message is generic.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "AI image generation is not configured, or is busy right now; try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/images/fit-square": {
      "post": {
        "tags": [
          "Images"
        ],
        "summary": "Make a photo square with AI",
        "operationId": "fitImageToSquare",
        "description": "Re-renders a photo as a square without cutting anyone out of it: the people and the setting are kept and the rest of the frame is composed to fill the square. A photo that is already square is rendered again, so calling twice gives a second rendering. Requires a bearer session.\nThe square comes back as base64 and nothing is stored. Upload it through the normal image upload to use it as a cover.\nShares the limits of `POST /images/generate`: 10 an hour and 30 a day per user; past either limit the answer is `429` with `Retry-After`. Errors from the image provider are not passed through: a photo the provider refuses answers `400`, a temporarily unavailable provider `503`, and any other provider failure `502`, each with a generic message.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "imageBase64"
                ],
                "properties": {
                  "imageBase64": {
                    "type": "string",
                    "format": "byte",
                    "description": "The photo, base64-encoded. JPEG, PNG or WebP, at most 6 MB."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The square photo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "imageBase64": {
                      "type": "string",
                      "format": "byte",
                      "description": "A 1024×1024 image, base64-encoded."
                    },
                    "contentType": {
                      "type": "string",
                      "example": "image/png"
                    },
                    "changed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`imageBase64` missing, not a JPEG, PNG or WebP, larger than 6 MB or unreadable, or the photo could not be fitted (try another one).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Fitting the photo failed unexpectedly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Photo fitting failed, or no image came back. The message is generic.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "AI photo fitting is not configured, or is busy right now; try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/images/track-download": {
      "post": {
        "tags": [
          "Images"
        ],
        "summary": "Record a stock-photo selection",
        "operationId": "trackStockPhotoDownload",
        "description": "Tells Unsplash a photo was chosen, as its API guidelines require. Pass the `downloadLocation` from `GET /images/search`. Never fails the caller's action: a failed ping answers `200` with `tracked: false`. Requires a bearer session.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "downloadLocation"
                ],
                "properties": {
                  "downloadLocation": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tracking outcome",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tracked": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`downloadLocation` missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "503": {
            "description": "Unsplash is not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/images/save-from-url": {
      "post": {
        "tags": [
          "Images"
        ],
        "summary": "Copy a generated image to the CDN",
        "operationId": "saveImageFromUrl",
        "description": "Downloads an AI-generated image from OpenAI's image storage and stores it on the platform CDN, returning the permanent URL. A URL already on the platform CDN is returned unchanged. Requires a bearer session and the `features.image_uploads` flag.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "bucket": {
                    "type": "string",
                    "default": "fundraiser-images",
                    "description": "Upload folder the copy is stored under."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stored image",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "fileName": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`url` missing, or not from a trusted image host.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Image uploads are disabled (`features.image_uploads`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Storing failed, or `url` could not be parsed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The source image could not be downloaded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{id}/media": {
      "get": {
        "tags": [
          "Media"
        ],
        "summary": "List a campaign's media",
        "operationId": "listFundraiserMedia",
        "description": "The campaign's photos and videos in gallery order. Every reader sees the public list (DMCA-taken-down items removed); the owner also sees processing and taken-down items. Answers `403` for everyone while `features.fundraiser_video` is off. Readable exactly when `GET /fundraisers/{id}` is: a campaign that is not `active`, `paused` or `ended`, is `private`, or has been deleted answers `404` to everyone but its owner.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Media items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "media": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FundraiserMedia"
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The `features.fundraiser_video` flag is off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "description": "Query failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Media"
        ],
        "summary": "Add media to a campaign",
        "operationId": "createFundraiserMedia",
        "description": "Adds one item, by `kind`:\n- `image` — a URL from `POST /storage/upload` (other hosts are\n  rejected). The first image becomes the cover unless `isCover` says\n  otherwise. At most 10 images per campaign.\n- `video_link` — a YouTube, Vimeo, Wistia, Loom, Instagram, Facebook\n  or TikTok URL. At most 3 videos per campaign.\n- `video_upload` — reserves a direct upload to the video host and\n  returns its one-time `uploadURL`. Counts toward the 3 videos.\n\nCampaign owner only. Behind `features.fundraiser_video` and the media-upload rate limit (30 per 15 minutes). Audit-logged.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "kind"
                ],
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "image",
                      "video_link",
                      "video_upload"
                    ]
                  },
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Required for `image` and `video_link`."
                  },
                  "position": {
                    "type": "integer",
                    "description": "Defaults to the end of the gallery."
                  },
                  "isCover": {
                    "type": "boolean",
                    "description": "`image` only."
                  },
                  "title": {
                    "type": "string",
                    "description": "`video_upload` only."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Item created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "media": {
                      "$ref": "#/components/schemas/FundraiserMedia"
                    },
                    "uploadURL": {
                      "type": "string",
                      "format": "uri",
                      "description": "`video_upload` only: where the client uploads the file."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown `kind`, missing `url`, an image URL not from platform storage, or an unsupported video provider.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FundraiserMediaError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not the owner, or `features.fundraiser_video` is off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FundraiserMediaError"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The image or video cap is reached (`code: CAP_EXCEEDED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FundraiserMediaError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "The video host failed (`code: UPSTREAM_FAILED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FundraiserMediaError"
                }
              }
            }
          },
          "503": {
            "description": "Video uploads are not configured (`code: STREAM_NOT_CONFIGURED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FundraiserMediaError"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/media/preview": {
      "post": {
        "tags": [
          "Media"
        ],
        "summary": "Preview a video link before saving a campaign",
        "operationId": "previewDraftFundraiserMediaLink",
        "description": "Parses a video URL and returns what the gallery would embed, for the builder's preview card. Nothing is saved. Thumbnail and title come from the provider's oEmbed and may be null. Authenticated callers; behind `features.fundraiser_video` and the authenticated request limiter. No campaign data is read or written.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Parsed link",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "provider": {
                      "type": "string"
                    },
                    "providerVideoId": {
                      "type": "string"
                    },
                    "embedUrl": {
                      "type": "string"
                    },
                    "aspectRatio": {
                      "type": "string",
                      "description": "Width:height, from provider metadata or the provider fallback."
                    },
                    "thumbnailUrl": {
                      "type": "string",
                      "nullable": true
                    },
                    "title": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`url` missing, or not a supported provider (`code: UNSUPPORTED_PROVIDER`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FundraiserMediaError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Video feature disabled."
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{id}/media/preview": {
      "post": {
        "tags": [
          "Media"
        ],
        "summary": "Preview a video link",
        "operationId": "previewFundraiserMediaLink",
        "description": "Parses a video URL and returns what the gallery would embed, for the builder's preview card. Nothing is saved. Thumbnail and title come from the provider's oEmbed and may be null. Campaign owner only; behind `features.fundraiser_video`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Parsed link",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "provider": {
                      "type": "string"
                    },
                    "providerVideoId": {
                      "type": "string"
                    },
                    "embedUrl": {
                      "type": "string"
                    },
                    "aspectRatio": {
                      "type": "string",
                      "enum": [
                        "16:9",
                        "9:16",
                        "4:5"
                      ]
                    },
                    "thumbnailUrl": {
                      "type": "string",
                      "nullable": true
                    },
                    "title": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`url` missing, or not a supported provider (`code: UNSUPPORTED_PROVIDER`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FundraiserMediaError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/fundraisers/{id}/media/reorder": {
      "patch": {
        "tags": [
          "Media"
        ],
        "summary": "Reorder a campaign's media",
        "operationId": "reorderFundraiserMedia",
        "description": "Sets the gallery order to the order of `ids`. Every id must belong to this campaign. Campaign owner only; behind `features.fundraiser_video`. Audit-logged.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ids"
                ],
                "properties": {
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reordered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`ids` is not an array of strings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not the owner, the flag is off, or an id belongs to another campaign (`code: FORBIDDEN`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FundraiserMediaError"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/fundraisers/{id}/media/{mid}/cover": {
      "patch": {
        "tags": [
          "Media"
        ],
        "summary": "Set the cover media",
        "operationId": "setFundraiserMediaCover",
        "description": "Makes one ready, visible image or video the campaign's cover (clearing the previous one). Processing, errored and taken-down media are rejected. Campaign owner or staff admin only; behind `features.fundraiser_video`. Audit-logged.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "mid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The new cover",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "media": {
                      "$ref": "#/components/schemas/FundraiserMedia"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The item is unavailable or taken down (`code: INVALID_URL`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FundraiserMediaError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Campaign or media item not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FundraiserMediaError"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{id}/media/{mid}": {
      "delete": {
        "tags": [
          "Media"
        ],
        "summary": "Remove a media item",
        "operationId": "deleteFundraiserMedia",
        "description": "Removes one item from the gallery. Campaign owner only; behind `features.fundraiser_video`. Audit-logged.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "mid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Removed"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Campaign or media item not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FundraiserMediaError"
                }
              }
            }
          }
        }
      }
    },
    "/achievements": {
      "get": {
        "tags": [
          "Achievements"
        ],
        "summary": "Get the badge catalogue",
        "operationId": "getAchievementCatalogue",
        "description": "Every badge on the platform with its copy, tier ladder, holder counts and rarity, plus header totals, series and the grid's slots, in the reader's language (`?lang=`, then `Accept-Language`, then the `i18next` cookie). The payload is the same for every reader; a token is accepted and ignored. Cached per language.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Reader language; falls back to `Accept-Language`, then the `i18next` cookie, then English.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Catalogue (bare object)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AchievementView"
                      }
                    },
                    "totals": {
                      "type": "object",
                      "properties": {
                        "achievements": {
                          "type": "integer"
                        },
                        "earned_total": {
                          "type": "integer"
                        },
                        "collectors": {
                          "type": "integer"
                        },
                        "rarest": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "slug": {
                              "type": "string"
                            },
                            "title": {
                              "type": "string",
                              "nullable": true
                            },
                            "key": {
                              "type": "string"
                            },
                            "label": {
                              "type": "string"
                            },
                            "holders": {
                              "type": "integer"
                            }
                          }
                        },
                        "computed_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        }
                      }
                    },
                    "language": {
                      "type": "string"
                    },
                    "vocabulary": {
                      "$ref": "#/components/schemas/AchievementVocabulary"
                    },
                    "series": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "description": "A numbered series: `id`, `number`, `status`, `listed`, `size`, `name`, `subtitle`, `totals`, `window` (its issuance window), labels and blurbs, and `numbered` (its capped badges). `window.volume_cents` is the platform's Raised in integer USD cents: what reached the creators of public campaigns, after the Stripe fee, the same figure as `raised_for_causes_cents` on `GET /platform/numbers`; the window closes when it first reaches `window.cutoff_cents`. Null while the series is a draft."
                      }
                    },
                    "slots": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "series_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "series_number": {
                            "type": "integer"
                          },
                          "state": {
                            "type": "string",
                            "enum": [
                              "card",
                              "reserved",
                              "retired"
                            ]
                          },
                          "slug": {
                            "type": "string"
                          },
                          "track": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "default_series_id": {
                      "type": "string",
                      "format": "uuid",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/achievements/art-sheets/{id}": {
      "get": {
        "tags": [
          "Achievements"
        ],
        "summary": "Get an achievement art sheet image",
        "operationId": "getAchievementArtSheetImage",
        "description": "The image of one badge art sheet, served immutably (one year) under its version token `?v=`. A request without the current token is redirected (`302`, uncached) to the current versioned URL. Public.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "description": "Anything else is the full sheet.",
            "schema": {
              "type": "string",
              "enum": [
                "full",
                "small",
                "cutout",
                "cutout_small"
              ],
              "default": "full"
            }
          },
          {
            "name": "v",
            "in": "query",
            "required": false,
            "description": "Version token. Cut-out sizes append `-c`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The image (its stored content type)",
            "content": {
              "image/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "302": {
            "description": "Redirect to the current versioned URL."
          },
          "404": {
            "description": "No such sheet, or no cut-out for it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AchievementError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/achievements/art-images/{id}": {
      "get": {
        "tags": [
          "Achievements"
        ],
        "summary": "Get an achievement library image",
        "operationId": "getAchievementArtImageFile",
        "description": "One image from the badge art library, served immutably under its version token `?v=`; a request without the current token is redirected (`302`) to it. Public.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "full",
                "small"
              ],
              "default": "full"
            }
          },
          {
            "name": "v",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The image (its stored content type)",
            "content": {
              "image/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "302": {
            "description": "Redirect to the current versioned URL."
          },
          "404": {
            "description": "No such image.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AchievementError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/achievements/vocabulary": {
      "get": {
        "tags": [
          "Achievements"
        ],
        "summary": "Get the achievement vocabulary",
        "operationId": "getAchievementVocabulary",
        "description": "The labels and colours every badge card is drawn with (tiers, tracks, rarity frames and so on), in the reader's language. Public.",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Reader language; falls back to `Accept-Language`, then the `i18next` cookie, then English.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Vocabulary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "vocabulary": {
                      "$ref": "#/components/schemas/AchievementVocabulary"
                    },
                    "language": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/achievements/feed": {
      "get": {
        "tags": [
          "Achievements"
        ],
        "summary": "Get the \"just earned\" feed",
        "operationId": "getAchievementFeed",
        "description": "The most recent cards issued or upgraded, platform-wide or for one badge (`species`). The size, maximum age and suggested refresh interval come from platform settings. An unknown, hidden or private badge answers an empty list. Public; sent with `Cache-Control: no-store`.",
        "parameters": [
          {
            "name": "species",
            "in": "query",
            "required": false,
            "description": "A badge slug. Repeating the parameter answers an empty list.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Reader language; falls back to `Accept-Language`, then the `i18next` cookie, then English.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Feed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AchievementFeedRow"
                      }
                    },
                    "refresh_seconds": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/achievements/{slug}": {
      "get": {
        "tags": [
          "Achievements"
        ],
        "summary": "Get one badge",
        "operationId": "getAchievementCard",
        "description": "One badge with its copy, ladder and rarity. Authentication is optional: a signed-in reader also gets their own standing (earned, tier, progress). With `holder_type` and `holder_id`, the badge is answered for that holder instead (a profile's or organization's badge); both must be given together.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "holder_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "user",
                "organization"
              ]
            }
          },
          {
            "name": "holder_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Reader language; falls back to `Accept-Language`, then the `i18next` cookie, then English.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The badge",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AchievementView"
                    },
                    "vocabulary": {
                      "$ref": "#/components/schemas/AchievementVocabulary"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Half a holder scope, or an invalid `holder_type` / `holder_id`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AchievementError"
                }
              }
            }
          },
          "404": {
            "description": "No such badge, or not visible to this reader.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AchievementError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/achievements/{slug}/share/{asset}": {
      "get": {
        "tags": [
          "Achievements"
        ],
        "summary": "Get a badge share picture",
        "operationId": "getAchievementShareAsset",
        "description": "A PNG of the badge for sharing: `og` 1200×630, `post` 1080×1080, `story` and `reel` 1080×1920. A trailing `.png` on `asset` is accepted. `?tier=` draws it at that tier when the tier exists. Drafts and private badges answer `404`. Public; cached for 5 minutes.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "asset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "og",
                "post",
                "story",
                "reel",
                "og.png",
                "post.png",
                "story.png",
                "reel.png"
              ]
            }
          },
          {
            "name": "tier",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Reader language; falls back to `Accept-Language`, then the `i18next` cookie, then English.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "PNG image",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Unknown asset or badge.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AchievementError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "description": "The renderer is busy (`code: RENDER_BUSY`); retry after the `Retry-After` seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AchievementError"
                }
              }
            }
          }
        }
      }
    },
    "/cards/{code}": {
      "get": {
        "tags": [
          "Achievements"
        ],
        "summary": "Get an earned card",
        "operationId": "getAchievementCardByCode",
        "description": "One earned card by its short code, as the card's public page shows it: the badge, holder, tier, dates, serial, evidence, ladder, rarity, the verify URL and share links. Authentication is optional; the holder's own session adds an `owner` block. Sent `private, no-store`.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "The card's short code.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Reader language; falls back to `Accept-Language`, then the `i18next` cookie, then English.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The card",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AchievementEarnedCard"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No readable card with this code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AchievementError"
                }
              }
            }
          },
          "410": {
            "description": "The card was withdrawn by FundlyHub (`code: WITHDRAWN`, with `data.code`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AchievementError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/cards/{code}/share/{asset}": {
      "get": {
        "tags": [
          "Achievements"
        ],
        "summary": "Get an earned card's share picture",
        "operationId": "getAchievementCardShareAsset",
        "description": "A PNG of one earned card: `og` 1200×630, `post` 1080×1080, `story` 1080×1920 (a trailing `.png` is accepted). Served only when the card is readable by a stranger. When the card's own picture is not rendered yet, the badge's generic picture is served with `X-Card-Render: pending` and `no-store`. Supports `If-None-Match` (`304`). Public; a per-IP limit (120 per minute by default) applies in addition to the public browsing limit.",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "The card's short code.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "asset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "og",
                "post",
                "story",
                "og.png",
                "post.png",
                "story.png"
              ]
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "PNG image. `Content-Language` names the language it was drawn in.",
            "headers": {
              "X-Card-Render": {
                "description": "`pending` when a placeholder was served.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "304": {
            "description": "Not modified."
          },
          "404": {
            "description": "Unknown asset, or no readable card with this code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AchievementError"
                }
              }
            }
          },
          "410": {
            "description": "The card was withdrawn (`code: WITHDRAWN`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AchievementError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "description": "The renderer is busy (`code: RENDER_BUSY`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AchievementError"
                }
              }
            }
          }
        }
      }
    },
    "/cards/{code}/qr.svg": {
      "get": {
        "tags": [
          "Achievements"
        ],
        "summary": "Get an earned card's verify QR code",
        "operationId": "getAchievementCardQr",
        "description": "An SVG QR code pointing at the card's verify URL. Only for cards readable by a stranger. Public; same per-IP limit as the share pictures. Cached for 60 seconds.",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "The card's short code.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SVG image",
            "content": {
              "image/svg+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No readable card with this code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AchievementError"
                }
              }
            }
          },
          "410": {
            "description": "The card was withdrawn (`code: WITHDRAWN`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AchievementError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/wallet/status": {
      "get": {
        "tags": [
          "Wallet"
        ],
        "summary": "Whether Apple Wallet passes are available",
        "operationId": "getWalletStatus",
        "description": "`available` is true once the platform's Pass Type ID certificate is configured. Until then every other Wallet endpoint answers `503` with `code: wallet_unavailable`, so a client shows no \"Add to Apple Wallet\" button. Public, the same answer for everyone, cached for five minutes.",
        "responses": {
          "200": {
            "description": "Availability",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletStatus"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/wallet/cards/{code}/link": {
      "post": {
        "tags": [
          "Wallet"
        ],
        "summary": "Get a download link for your card's Apple Wallet pass",
        "operationId": "createWalletCardPassLink",
        "description": "For the holder of the card only (the signed-in person, or an organization they administer). Answers a link to `GET /wallet/passes/{token}` that works for ten minutes, for one download of this card's pass, in the request's language (`?lang=`, the language cookie, then `Accept-Language`). The pass is a generic Wallet pass in the colours of the card's tier: the series number, the species, the tier, when the current tier was reached, the holder's public name, the series, the rarity and, for a card earned by a verified donation, the proof, with the card's verify QR code. It shows only what the public card page shows. Writes nothing.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "The card's code, e.g. `WH-2318`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "The pass's language.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The download link",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletPassLink"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The card is someone else's (`code: NOT_CARD_HOLDER`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletError"
                }
              }
            }
          },
          "404": {
            "description": "No card with this code that the caller can open (the card page's own 404).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AchievementError"
                }
              }
            }
          },
          "410": {
            "description": "The card's species was withdrawn (`code: WITHDRAWN`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AchievementError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/WalletUnavailable"
          }
        }
      }
    },
    "/wallet/passes/{token}": {
      "get": {
        "tags": [
          "Wallet"
        ],
        "summary": "Download your card's Apple Wallet pass",
        "operationId": "getWalletCardPass",
        "description": "The link `POST /wallet/cards/{code}/link` answers, opened within ten minutes. The card is checked again; a card revoked or no longer the requester's in the meantime answers `404`. Every download is a new pass with its own serial number. The pass stays current through the PassKit web service: when the card reaches a new tier, Wallet is told and fetches it. `private, no-store`: the file carries the pass's own authentication token.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "The signed download token from the link.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The signed pass, sent as an attachment named `FundlyHub-<code>.pkpass`",
            "content": {
              "application/vnd.apple.pkpass": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "The link expired or is not one (`code: LINK_EXPIRED`), or the card is gone (`code: NOT_FOUND`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletError"
                }
              }
            }
          },
          "410": {
            "description": "The card's species was withdrawn (`code: WITHDRAWN`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AchievementError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/WalletUnavailable"
          }
        }
      }
    },
    "/wallet/fundraisers/{id}/pass": {
      "get": {
        "tags": [
          "Wallet"
        ],
        "summary": "Download a fundraiser's Apple Wallet pass",
        "operationId": "getWalletFundraiserPass",
        "description": "A store card for any fundraiser that can be opened by its link (live, ended or paused, not private, not deleted): the amount raised, the percent of the goal, the title and the donor count, the same figures and money formatting as the fundraiser's page, over its cover photo. The QR code opens the fundraiser's page (`?utm_source=wallet`), or, when `ref` is a referral code for this fundraiser, that sharer's `/r/<code>` link, so their link keeps counting what it brings. Any other `ref` is ignored. Each download is a new pass that updates as gifts come in. Language: `?lang=`, the language cookie, then `Accept-Language`; without one the labels are English and the title is the fundraiser's own.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "ref",
            "in": "query",
            "required": false,
            "description": "A referral code for this fundraiser.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The signed pass, sent as an attachment named `FundlyHub-<slug>.pkpass`",
            "content": {
              "application/vnd.apple.pkpass": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "No fundraiser with this id that can be opened by its link.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/WalletUnavailable"
          }
        }
      }
    },
    "/passkit/v1/devices/{deviceLibraryIdentifier}/registrations/{passTypeIdentifier}/{serialNumber}": {
      "post": {
        "tags": [
          "Wallet"
        ],
        "summary": "Register a device for a pass's updates (PassKit web service)",
        "operationId": "registerWalletPassDevice",
        "description": "Apple's PassKit web service, called by Wallet itself under the pass's `webServiceURL`. Authenticated by the pass's own token. `201` for a new registration, `200` when the device was already registered (its push token is updated).",
        "security": [
          {
            "ApplePassAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/PassKitDeviceLibraryIdentifier"
          },
          {
            "$ref": "#/components/parameters/PassKitPassTypeIdentifier"
          },
          {
            "$ref": "#/components/parameters/PassKitSerialNumber"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "pushToken"
                ],
                "properties": {
                  "pushToken": {
                    "type": "string",
                    "description": "The device's APNs token (hex)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Already registered: the device's push token is updated. The body is the plain-text status line `OK`.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "OK"
                }
              }
            }
          },
          "201": {
            "description": "Registered. The body is the plain-text status line `Created`.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "Created"
                }
              }
            }
          },
          "400": {
            "description": "No usable `pushToken` (`code: INVALID_PUSH_TOKEN`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletError"
                }
              }
            }
          },
          "401": {
            "description": "Not this pass's token, no such pass, or a malformed device identifier (`code: UNAUTHORIZED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletError"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/WalletUnavailable"
          }
        }
      },
      "delete": {
        "tags": [
          "Wallet"
        ],
        "summary": "Unregister a device from a pass's updates (PassKit web service)",
        "operationId": "unregisterWalletPassDevice",
        "description": "Called by Wallet when the pass is removed from the device. Authenticated by the pass's own token.",
        "security": [
          {
            "ApplePassAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/PassKitDeviceLibraryIdentifier"
          },
          {
            "$ref": "#/components/parameters/PassKitPassTypeIdentifier"
          },
          {
            "$ref": "#/components/parameters/PassKitSerialNumber"
          }
        ],
        "responses": {
          "200": {
            "description": "Unregistered, also when the device was not registered for this pass. The body is the plain-text status line `OK`.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "OK"
                }
              }
            }
          },
          "401": {
            "description": "Not this pass's token, no such pass, or a malformed device identifier (`code: UNAUTHORIZED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletError"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/WalletUnavailable"
          }
        }
      }
    },
    "/passkit/v1/devices/{deviceLibraryIdentifier}/registrations/{passTypeIdentifier}": {
      "get": {
        "tags": [
          "Wallet"
        ],
        "summary": "List a device's passes that changed (PassKit web service)",
        "operationId": "listWalletPassUpdates",
        "description": "The serial numbers of the passes this device registered for that changed after `passesUpdatedSince` (a `lastUpdated` value this endpoint answered before; all of them without it), and the `lastUpdated` value to send next time. A pass can be listed again; fetching it then answers `304`. No authentication, as Apple specifies.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PassKitDeviceLibraryIdentifier"
          },
          {
            "$ref": "#/components/parameters/PassKitPassTypeIdentifier"
          },
          {
            "name": "passesUpdatedSince",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Changed passes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PassKitSerialNumbers"
                }
              }
            }
          },
          "204": {
            "description": "Nothing changed"
          },
          "503": {
            "$ref": "#/components/responses/WalletUnavailable"
          }
        }
      }
    },
    "/passkit/v1/passes/{passTypeIdentifier}/{serialNumber}": {
      "get": {
        "tags": [
          "Wallet"
        ],
        "summary": "Get the current version of a pass (PassKit web service)",
        "operationId": "getWalletPassLatest",
        "description": "The pass as it is now, rebuilt from the card or the fundraiser, with `Last-Modified`. `304` when it has not changed since `If-Modified-Since`. A card that was revoked or withdrawn, or is no longer its holder's, and a fundraiser that can no longer be opened, come back as a voided pass. Authenticated by the pass's own token.",
        "security": [
          {
            "ApplePassAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/PassKitPassTypeIdentifier"
          },
          {
            "$ref": "#/components/parameters/PassKitSerialNumber"
          },
          {
            "name": "If-Modified-Since",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The signed pass",
            "headers": {
              "Last-Modified": {
                "description": "When the pass last changed.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/vnd.apple.pkpass": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "304": {
            "description": "Not changed"
          },
          "401": {
            "description": "Not this pass's token, or no such pass (`code: UNAUTHORIZED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/WalletUnavailable"
          }
        }
      }
    },
    "/passkit/v1/log": {
      "post": {
        "tags": [
          "Wallet"
        ],
        "summary": "Report Wallet's errors (PassKit web service)",
        "operationId": "logWalletPassErrors",
        "description": "Wallet's own error messages about the web service. Logged, never stored.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "logs": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Received. The body is the plain-text status line `OK`.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "OK"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/WalletUnavailable"
          }
        }
      }
    },
    "/storage/upload": {
      "post": {
        "tags": [
          "Storage"
        ],
        "summary": "Upload an image",
        "operationId": "uploadStorageFile",
        "description": "Stores a base64-encoded raster image on the platform CDN and returns its public URL, which the media gallery, outcome reports and the campaign form accept. Requires a bearer session. Only raster image types are accepted (no SVG or HTML), into one of the `StorageBucket` folders. Omit `path` and the server stores the file under a new unique path beginning with the caller's user id, returned as `path`. A supplied `path` must begin with the caller's own user id, profile id or Cognito sub, the same rule `POST /storage/delete` applies. An upload never replaces an existing file. A file may be up to 15 MB (the original of a cropped photo).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "bucket",
                  "fileBase64",
                  "contentType"
                ],
                "properties": {
                  "bucket": {
                    "$ref": "#/components/schemas/StorageBucket"
                  },
                  "path": {
                    "type": "string",
                    "maxLength": 256,
                    "description": "Optional. Relative path of letters, digits, `.`, `_`, `-` and single `/` separators; no `..`, leading slash or backslash. The first segment must be the caller's own id, followed by at least one more segment. Omit it to let the server choose a unique path.",
                    "example": "3f6c1b9e-7d2a-4c8e-9b1f-2a4d6e8f0c13/cover-1717171717.jpg"
                  },
                  "fileBase64": {
                    "type": "string",
                    "format": "byte"
                  },
                  "contentType": {
                    "type": "string",
                    "enum": [
                      "image/jpeg",
                      "image/png",
                      "image/webp",
                      "image/gif",
                      "image/heic",
                      "image/heif"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stored",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "path": {
                      "type": "string",
                      "description": "Where the file was stored; pass it to `POST /storage/delete`."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A field is missing, or the bucket, content type or path is not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The supplied `path` does not begin with the caller's own id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "A file already exists at the supplied `path`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "The file is larger than 15 MB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The storage write failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/image-crops": {
      "post": {
        "tags": [
          "Storage"
        ],
        "summary": "Record the original and the crop behind a cropped image",
        "operationId": "saveImageCrop",
        "description": "Every image upload and edit goes through one crop dialog, which uploads the untouched original next to the cropped output and then records here where the crop sits on the original, keyed by the output's URL, so editing the image later reopens the dialog on the original with the crop restored. Both URLs must be images on the FundlyHub CDN: the original an upload into one of the `StorageBucket` folders, the output that or a processed avatar, organization logo or banner. The caller must own the output: its path begins with their id (an upload or their own avatar), or they may manage that user or organization. Saving again for the same output replaces the record, but only its own author can do that. Requires a bearer session.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "output_url",
                  "original_url",
                  "crop"
                ],
                "properties": {
                  "output_url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 2048,
                    "description": "The cropped image the surface stores and shows.",
                    "example": "https://fundlyhub.org/uploads/community-photos/3f6c1b9e-7d2a-4c8e-9b1f-2a4d6e8f0c13/1717171717-crop.jpg"
                  },
                  "original_url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 2048,
                    "description": "The uploaded original, with unchanged pixels. Must differ from `output_url`.",
                    "example": "https://fundlyhub.org/uploads/community-photos/3f6c1b9e-7d2a-4c8e-9b1f-2a4d6e8f0c13/1717171716-original.jpg"
                  },
                  "crop": {
                    "$ref": "#/components/schemas/ImageCropState"
                  },
                  "secondary_crop": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/ImageCropState"
                      }
                    ],
                    "nullable": true,
                    "description": "A derived frame inside the main one, such as the avatar square inside a community card, on the same original."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "output_url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "original_url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "crop": {
                          "$ref": "#/components/schemas/ImageCropState"
                        },
                        "secondary_crop": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/ImageCropState"
                            }
                          ],
                          "nullable": true
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A URL is not a FundlyHub image (`INVALID_URL`), or a crop is not valid (`INVALID_CROP`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The output is not the caller's image.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Another account already recorded a crop for this output.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "Storage"
        ],
        "summary": "Read the original and the crop behind a cropped image",
        "operationId": "getImageCrop",
        "description": "The record `POST /image-crops` saved for a cropped image, so the crop dialog can reopen on the original. The original holds whatever the crop cut away, so only the record's author, the image's owner (as `POST /image-crops` judges it) and staff who edit other people's images can read it; anybody else gets the same 404 as an image with no record, and the dialog then edits the image itself. Requires a bearer session.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "The cropped image's URL (`output_url`).",
            "schema": {
              "type": "string",
              "format": "uri",
              "maxLength": 2048
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The original and the crops",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "original_url",
                    "crop",
                    "secondary_crop"
                  ],
                  "properties": {
                    "original_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "crop": {
                      "$ref": "#/components/schemas/ImageCropState"
                    },
                    "secondary_crop": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/ImageCropState"
                        }
                      ],
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`url` is missing, or not a FundlyHub image.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No crop is recorded for this image that the caller may read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/storage/delete": {
      "post": {
        "tags": [
          "Storage"
        ],
        "summary": "Delete an uploaded image",
        "operationId": "deleteStorageFile",
        "description": "Deletes one uploaded file. The path's first segment must be the caller's own user id, profile id or Cognito sub; files uploaded under any other prefix cannot be deleted through this endpoint. Requires a bearer session.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "bucket",
                  "path"
                ],
                "properties": {
                  "bucket": {
                    "$ref": "#/components/schemas/StorageBucket"
                  },
                  "path": {
                    "type": "string",
                    "maxLength": 256
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A field is missing, or the bucket or path is not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The path does not start with the caller's id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The storage delete failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api-keys": {
      "post": {
        "tags": [
          "API Keys"
        ],
        "summary": "Create an API key",
        "operationId": "createApiKey",
        "description": "Mints a new API key for the authenticated user. The full key is returned **once**, in `api_key`, and cannot be retrieved again. `key.prefix` (the first 12 characters) is what later listings show.\n\nRequires a signed-in session (the session cookies, or a Cognito JWT in the `Authorization` header). A request authenticated with an API key, or made while an administrator is viewing the account as its owner, answers `403`.\n\nEvery new key expires: one year after creation unless `expires_at` asks for sooner. A key stops working early if it is revoked, if its owner's account is suspended, banned or deactivated, or if an administrator signs the owner out of every device (which revokes all of the owner's keys).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 100,
                    "description": "A label for the key. Trimmed; must not be blank.",
                    "example": "CI deploy bot"
                  },
                  "expires_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true,
                    "description": "When the key stops working, as an ISO 8601 timestamp. Must be in the future and no more than 365 days from now. Omit or `null` for the default, 365 days from now. A key that never expires cannot be created."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Key created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "api_key": {
                      "type": "string",
                      "description": "The full secret key. Shown only in this response.",
                      "example": "fh_live_3f9c2a1b0e7d4c5a8b6f1e2d3c4b5a69788766554433221100ffeeddccbbaa99"
                    },
                    "key": {
                      "$ref": "#/components/schemas/ApiKey"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`name` missing, blank, or longer than 100 characters; or `expires_at` not a date-time, not in the future, or more than 365 days from now.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/SessionCredentialRequired"
          },
          "500": {
            "description": "Key could not be created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "API Keys"
        ],
        "summary": "List my API keys",
        "operationId": "listApiKeys",
        "description": "The authenticated user's keys, newest first. Never includes the secret. Revoked keys are excluded unless `include_revoked=true`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "include_revoked",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The caller's keys",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ApiKey"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Keys could not be listed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api-keys/{id}": {
      "delete": {
        "tags": [
          "API Keys"
        ],
        "summary": "Revoke an API key",
        "operationId": "revokeApiKey",
        "description": "Revokes one of the caller's own keys. Takes effect immediately. A key that belongs to someone else, does not exist, or is already revoked answers `404`.\n\nRequires a signed-in session: a request authenticated with an API key, or made while an administrator is viewing the account as its owner, answers `403`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Key revoked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/SessionCredentialRequired"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "description": "Revocation failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/cognito/change-password": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Change password",
        "operationId": "changePassword",
        "description": "Changes the password of an email/password account, given the current one.\n\n**Cookie session only.** A request authenticated with an `Authorization: Bearer` header or an API key answers `401 Not authenticated`. Google and Apple accounts have no password to change.\n\nRate limited at 10 requests/minute per IP (authentication bucket).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "currentPassword",
                  "newPassword"
                ],
                "properties": {
                  "currentPassword": {
                    "type": "string",
                    "format": "password"
                  },
                  "newPassword": {
                    "type": "string",
                    "format": "password",
                    "minLength": 8,
                    "description": "Must also satisfy the Cognito pool policy (upper, lower, digit and symbol)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Password changed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A field is missing, the new password is shorter than 8 characters or fails the pool policy, or the current password is wrong.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Either the authentication rate limit, or Cognito's own `LimitExceededException`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Cognito rejected the change for another reason",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/cognito/resend-verification": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Resend the email-verification link",
        "operationId": "resendVerificationEmail",
        "description": "Sends a fresh verification link to the account registered under `email` (matched case-insensitively against the **login** address, not the private contact address — for that use `POST /users/me/private-contact/resend`).\n\nAlways answers `200` with the same message, whether or not the address has an account and even when sending fails, so it cannot be used to discover accounts.\n\nNo authentication. Rate limited at 5 requests/minute, keyed by user when a session is present and by IP otherwise.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Accepted (sent if the address is known)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "If this email exists, a verification link has been sent."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`email` missing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/cognito/verify-email": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Verify an email address (link target)",
        "operationId": "verifyEmailLink",
        "description": "The URL in verification emails. Consumes the token and **always redirects** to the frontend with the outcome in a query parameter; it never returns JSON.\n\n`?verification=` is one of: `success`; `invalid` (no token); `failed` (an unknown token); `used` (the link was already used); `expired` (the link has expired); `contact_taken` (the link proved a private contact address another account already holds); `error` (unexpected failure).\n\nWhen the link proved the account's **login** address, the Cognito `email_verified` attribute is updated too, and any pending ambassador invitation for that address is settled.\n\nNo authentication. Rate limited at 300 requests/minute per IP.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to `{FRONTEND_URL}/verify-email?verification=<outcome>`",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/cognito/oauth/callback": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "OAuth callback (Google / Apple)",
        "operationId": "handleOAuthCallback",
        "description": "The Cognito Hosted UI's `redirect_uri` after a Google or Apple sign-in, started at `GET /cognito/oauth/{provider}`. Not called by API clients directly.\n\nExchanges `code` for tokens, provisions or links the profile, sets the `access_token`, `id_token` and `refresh_token` httpOnly cookies, and redirects to the `redirect` path given when the flow was started (carried in the `oauth_flow` cookie, not in `state`), or the frontend root.\n\nEvery failure is also a redirect, to `{FRONTEND_URL}/auth?error=…`: `state_mismatch` (no `oauth_flow` cookie in this browser, or `state` does not match it), `unverified_account_exists` (a provider identity linked to a native account whose address was never verified), `blocked_email_domain` (the address fails the sign-up email policy), `email_linked_elsewhere` (a profile at this address belongs to another sign-in, and this one has not proven the address), `missing_code`, `token_exchange_failed`, `invalid_token`, `oauth_error` (with a `message`), or the provider's own `error` with a `message`.",
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "required": false,
            "description": "Authorization code from Cognito.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "The sign-in's one-time nonce, which must match the `oauth_flow` cookie that `GET /cognito/oauth/{provider}` set in this browser.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "error",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "error_description",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect — on success to the `redirect` path the sign-in was started with (or `/`) on the frontend, with the session cookies set; on failure to `/auth?error=…` on the frontend.",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "Set-Cookie": {
                "description": "`access_token`, `id_token`, `refresh_token` (httpOnly) on success.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/users/{id}/badges": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Get a profile's trust badges",
        "operationId": "getUserBadges",
        "description": "The trust badges (e.g. identity verified, brand ambassador) on a profile, newest first. `id` is a UUID or a profile slug.\n\nA **private** profile answers `{ \"badges\": [] }` to everyone but its owner — the same answer as a profile with no badges, so the response does not confirm that the profile is private.\n\nAuthentication is optional; it only matters for the owner.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Profile UUID or profile slug.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The badges (bare object, not the `data` envelope)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "badges": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "badgeType": {
                            "type": "string"
                          },
                          "metadata": {
                            "type": "object",
                            "nullable": true,
                            "additionalProperties": true,
                            "description": "Free-form, per badge type."
                          },
                          "awardedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users/{id}/campaigns": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "List a profile's campaigns",
        "operationId": "getUserCampaigns",
        "description": "The campaigns shown on a profile: those the person runs, those they have endorsed (`is_endorsed: true`), and public active/ended campaigns naming them as an accepted beneficiary (`is_beneficiary: true`), newest activity first. `id` is a UUID or a profile slug.\n\nA visitor sees public campaigns in `active` or `ended` status. The profile's owner, identified by the **session** (there is no query flag for it), additionally sees their own `draft`, `pending` and `paused` campaigns and their unlisted and private ones. A private profile shows only its public owned campaigns to visitors; endorsements and beneficiary relationships stay hidden.\n\nTitles and summaries are returned in the reader's language when a translation exists (`?lang=`, then the language cookie, then `Accept-Language`).\n\nRate limited at 300 requests/minute per IP.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Profile UUID or profile slug.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 60
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The profile's campaign cards",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ProfileCampaignCard"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users/{id}/og-image": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Get a profile's share image",
        "operationId": "getUserOgImage",
        "description": "The 1200×630 PNG a shared profile link unfurls into: name, avatar, account kind, location, join date and campaign count. Intended for social crawlers. `id` is a UUID or a profile slug. The name is the profile's `display_name`: the name, else `@handle`, else `FundlyHub member`, never an email address.\n\nA private profile, like a missing one, is a `404`. Cached for five minutes, server-side and via `Cache-Control`.\n\nNo authentication. Rate limited at 300 requests/minute per IP.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Profile UUID or profile slug.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The image",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "example": "public, max-age=300, s-maxage=300"
                }
              }
            },
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Image generation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users/me/private-contact/resend": {
      "post": {
        "tags": [
          "Users"
        ],
        "summary": "Resend the private-contact verification email",
        "operationId": "resendPrivateContactVerification",
        "description": "Sends a new verification link to the caller's private contact email (set with `PUT /users/me/private-contact`). Links last 24 hours; a verified private contact email is required before publishing a campaign. If the address is already verified, nothing is sent and the response says so.\n\nRate limited at 5 requests/minute per user, a bucket shared with `PUT /users/me/private-contact`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Sent, or already verified",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "alreadyVerified": {
                      "type": "boolean"
                    },
                    "email": {
                      "type": "string",
                      "format": "email"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "No private contact email on file",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The email could not be sent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users/{id}/recalculate-counts": {
      "post": {
        "tags": [
          "Social"
        ],
        "summary": "Recalculate follower counts",
        "operationId": "recalculateFollowCounts",
        "description": "Recounts the caller's followers and followings, stores `follower_count` / `following_count` on the profile, and returns them. `id` must be the caller's own profile UUID; any other profile answers `403`. The counts are also refreshed whenever a follow is created or removed, so this is only a manual resync. Requires a bearer session.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The recounted figures",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "follower_count": {
                          "type": "integer"
                        },
                        "following_count": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "description": "Recount failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/marketplace/creators": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "List top creators",
        "operationId": "listMarketplaceCreators",
        "description": "Public profiles ranked by money raised, then followers. Cached server- side; `cached` says whether this answer came from the cache.\n\n**`fundsRaised` is in DOLLARS** (a decimal), unlike the rest of the API, which uses integer cents.\n\nNo authentication.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The creators (bare object with `data`, not paginated)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string",
                            "description": "`Anonymous User` when the profile has no name."
                          },
                          "avatar": {
                            "type": "string",
                            "nullable": true
                          },
                          "location": {
                            "type": "string",
                            "description": "Empty string when unset."
                          },
                          "bio": {
                            "type": "string",
                            "description": "Empty string when unset."
                          },
                          "profileType": {
                            "type": "string",
                            "enum": [
                              "individual",
                              "organization"
                            ],
                            "description": "`organization` when the person belongs to any organization."
                          },
                          "fundsRaised": {
                            "type": "number",
                            "description": "Money raised across their campaigns, in DOLLARS."
                          },
                          "campaignsCompleted": {
                            "type": "integer"
                          },
                          "followersCount": {
                            "type": "integer"
                          },
                          "sharesCount": {
                            "type": "integer"
                          },
                          "badges": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Badge types, newest first."
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "executionTimeMs": {
                      "type": "integer"
                    },
                    "cached": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/system-settings/features": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "Get feature flags",
        "operationId": "getPublicFeatureFlags",
        "description": "The `features.*` flags, read-only, for the signed-in caller — so the client can hide what the server will refuse. Flags that only concern FundlyHub's own operations are omitted. Each value is reduced to the three gating fields.\n\nThe server treats a flag that has no row as enabled, so a flag absent from this list is not necessarily off.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The flags",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "setting_key": {
                            "type": "string",
                            "example": "features.comments"
                          },
                          "setting_value": {
                            "type": "object",
                            "properties": {
                              "enabled": {
                                "type": "boolean"
                              },
                              "allowed_roles": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                },
                                "description": "Roles that may use the feature while it is disabled. Only operator roles are honoured."
                              },
                              "disabled_message": {
                                "type": "string"
                              }
                            }
                          },
                          "category": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Flags could not be loaded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/platform/numbers": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "Get the platform's published numbers",
        "operationId": "getPlatformNumbers",
        "description": "The figures FundlyHub publishes about itself on `/@fundlyhub`. The same answer for every reader, cached for five minutes; `computed_at` says how old it is. `GET /stats` is unchanged and still served.\n\nNo authentication. Rate limited at 300 requests/minute per IP.",
        "responses": {
          "200": {
            "description": "The numbers (bare object)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformNumbers"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The numbers could not be computed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/platform/team": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "List the FundlyHub team",
        "operationId": "getPlatformTeam",
        "description": "The FundlyHub team members shown on `/@fundlyhub`: staff with a public, slugged profile and an account in good standing — at most 48, ordered by role then name. An empty list is a normal `200`.\n\nNo authentication. Rate limited at 300 requests/minute per IP.",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Cache key for future localised fields. Anything else is treated as `en`.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The roster",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "members": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PlatformTeamMember"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The roster could not be loaded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/platform/ambassadors": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "List platform ambassadors with impact",
        "operationId": "getPlatformAmbassadors",
        "description": "Every holder of the `ambassador` role who is not banned (at most 100), ranked by impact. `total` counts all of them; `members` lists only those with a public, slugged profile, so `total` can exceed `members.length`.\n\nNo authentication. Rate limited at 300 requests/minute per IP.",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The ambassador rail",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "members": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PlatformAmbassador"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The rail could not be loaded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/platform/tips": {
      "post": {
        "tags": [
          "Platform"
        ],
        "summary": "Tip FundlyHub",
        "operationId": "createPlatformTip",
        "description": "Starts a tip to FundlyHub itself — not a donation to a cause, and not tax-deductible. Creates a pending tip row and a Stripe Checkout Session (`payment` mode for `one_time`, monthly `subscription` mode for `recurring`) and returns its `url`; send the browser there. Stripe returns the payer to `/tip/{tip_id}` on the site. The tip is settled by the Stripe webhook, not by this call.\n\nAuthentication is optional. With a session the tip is attributed to the account, and the account's name and email are used when the body does not give them. Currency is always USD.\n\nRate limited at 10 requests/minute per IP (authentication bucket).",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "amount_cents",
                  "kind"
                ],
                "properties": {
                  "amount_cents": {
                    "type": "integer",
                    "minimum": 100,
                    "maximum": 10000000,
                    "description": "Whole cents. `25.5` is rejected, not rounded."
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "one_time",
                      "recurring"
                    ]
                  },
                  "donor_email": {
                    "type": "string",
                    "format": "email",
                    "description": "For the receipt; never published. Prefills Stripe's email field."
                  },
                  "donor_name": {
                    "type": "string"
                  },
                  "is_anonymous": {
                    "type": "boolean",
                    "default": false,
                    "description": "Keeps the name off the public receipt."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Checkout started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tip_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "one_time",
                        "recurring"
                      ]
                    },
                    "amount_cents": {
                      "type": "integer"
                    },
                    "currency": {
                      "type": "string",
                      "example": "usd"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "description": "Stripe-hosted Checkout page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`amount_cents` or `kind` invalid",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "INVALID_AMOUNT",
                        "INVALID_KIND"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The tip or the Stripe session could not be created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/platform/tips/{id}": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "Get a tip receipt",
        "operationId": "getPlatformTipReceipt",
        "description": "The public receipt for one tip: amount, cadence, status and dates, and the signed-in tipper's profile name unless they tipped anonymously. Never an email or a Stripe identifier.\n\nA tip that has not settled yet is a `200` with `status: pending` — the payer often arrives from Stripe before the webhook does. A monthly tip also carries `subscription`; its next charge date is read from Stripe once the tip is paid.\n\nNo authentication: the tip id is the capability. Rate limited at 300 requests/minute per IP.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The receipt (bare object)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformTipReceipt"
                }
              }
            }
          },
          "404": {
            "description": "No such tip, or the id is not a UUID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The receipt could not be loaded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/platform/tips/{id}/receipt/email": {
      "post": {
        "tags": [
          "Platform"
        ],
        "summary": "Email a tip receipt",
        "operationId": "emailPlatformTipReceipt",
        "description": "Emails the receipt for one **paid** tip to any address — every figure comes from the tip row, so the caller controls only the recipient. Capped at **5 sends per tip**, after which this answers `429` for that tip permanently. A missing and an unpaid tip get the same `404`.\n\nThe mail queue is processed immediately; `message` says whether the email was sent or only queued.\n\nAuthentication is optional. Rate limited at 5 requests/minute per IP.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "recipient_email"
                ],
                "properties": {
                  "recipient_email": {
                    "type": "string",
                    "format": "email",
                    "description": "Lowercased before use."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sent or queued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string",
                      "enum": [
                        "Receipt email sent successfully",
                        "Receipt email queued"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Tip id not a UUID, or `recipient_email` missing or malformed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No paid tip with that id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Either the shared limit (5 requests per minute per IP), or this tip has already been emailed 5 times.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Sending failed unexpectedly",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The email provider rejected the message",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/home/activity": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "Get the homepage live-activity feed",
        "operationId": "getHomeActivity",
        "description": "The homepage hero's live chips, newest first: gifts, referral-link views and clicks, people viewing a campaign right now, campaigns submitted for review (never named), and achievements earned. Every event passes the same public gates as the surface it comes from — only public, active or ended campaigns are named, and anonymous donors are not.\n\n`events` is a discriminated union on `kind`. The same answer for every reader of a language; publicly cached for 15 seconds.\n\nNo authentication. Rate limited at 300 requests/minute per IP.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 40,
              "default": 24
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Campaign titles in this language when translated.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The feed",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "example": "public, max-age=15, s-maxage=15"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "events": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/HeroActivityEvent"
                          }
                        },
                        "generated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The feed could not be built",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "INTERNAL_ERROR"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/presence/fundraisers/{id}": {
      "post": {
        "tags": [
          "Platform"
        ],
        "summary": "Send a campaign-page presence heartbeat",
        "operationId": "postFundraiserPresence",
        "description": "Records that a visitor has a campaign page open; feeds the \"N people viewing\" chip in `GET /home/activity`. Designed for `navigator.sendBeacon` — no body. The visitor is the `visitor_id` cookie, or the per-tab `v` query parameter when there is no cookie; only a one-way hash of it is stored, and it expires on its own.\n\nThe same heartbeat feeds the organizer's page views (`GET /fundraisers/{id}/owner-stats`): a visitor counts once per Fundly per UTC day, and only when the `User-Agent` reads as a browser (bots, link previews and unknown agents never count).\n\nNo authentication. Rate limited at **4 requests/minute per IP and campaign**, then the 300/minute public bucket.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Fundraiser UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "v",
            "in": "query",
            "required": false,
            "description": "Per-tab visitor id, used only when there is no `visitor_id` cookie.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{8,64}$"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Recorded (no body)"
          },
          "400": {
            "description": "`id` is not a UUID, or there is no usable visitor id",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "BAD_REQUEST"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/analytics/campaigns/aggregate": {
      "get": {
        "tags": [
          "Fundraisers"
        ],
        "summary": "Get aggregate campaign stats",
        "operationId": "getAggregateCampaignStats",
        "description": "Counters for the `/causes` stat tiles. The counts (`total_campaigns`, active, closed, the goals, the completion average and each top category's `campaign_count`) are over public, non-deleted campaigns in `active` or `ended` status, filtered the same way as the listing. \"Closed\" means ended, or active with a past `end_date`. The money and the donors are over the **counted campaigns** (approved, public, not deleted) that match the same filters: `total_raised_cents` is the sum of their cards (net of the Stripe fee, tips excluded), so the causes and projects totals add up to the platform's raised.\n\n**Counts and sums are returned as numeric strings.**\n\nNo authentication.",
        "parameters": [
          {
            "name": "is_project",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false",
                "1",
                "0"
              ]
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Category slug, id or name.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The aggregates (bare object)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total_campaigns": {
                      "type": "string",
                      "example": "128"
                    },
                    "active_campaigns": {
                      "type": "string"
                    },
                    "closed_campaigns": {
                      "type": "string"
                    },
                    "total_raised_cents": {
                      "type": "string",
                      "description": "Cents. The sum of the counted campaigns' cards."
                    },
                    "total_goal": {
                      "type": "string",
                      "nullable": true,
                      "description": "Sum of goals, in cents."
                    },
                    "avg_completion_percent": {
                      "type": "string",
                      "nullable": true,
                      "description": "Mean of raised / goal × 100."
                    },
                    "total_donors": {
                      "type": "string",
                      "description": "Distinct donors of the counted gifts to the counted campaigns, each person once however many campaigns they gave to."
                    },
                    "topCategories": {
                      "type": "array",
                      "description": "Top five categories by money raised over the filtered campaigns. A category with no matching campaign can appear with zero counts.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "campaign_count": {
                            "type": "string"
                          },
                          "total_raised_cents": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Aggregation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/meta/llms.txt": {
      "get": {
        "tags": [
          "Meta"
        ],
        "summary": "Get llms.txt",
        "operationId": "getLlmsTxt",
        "description": "The AI-crawler discovery file served at `https://fundlyhub.org/llms.txt`: live platform statistics, categories, trending campaigns, key pages and localised versions, in Markdown. Cached for an hour. No authentication.",
        "responses": {
          "200": {
            "description": "The file",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Generation failed",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/meta/llms-full.txt": {
      "get": {
        "tags": [
          "Meta"
        ],
        "summary": "Get llms-full.txt",
        "operationId": "getLlmsFullTxt",
        "description": "The long form of `llms.txt`: active campaigns, how the platform works, the money and trust model, FAQ, glossary and site structure. Cached for an hour. No authentication.",
        "responses": {
          "200": {
            "description": "The file",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Generation failed",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/meta/sitemap-index": {
      "get": {
        "tags": [
          "Meta"
        ],
        "summary": "Get the sitemap index",
        "operationId": "getSitemapIndex",
        "description": "The `<sitemapindex>` served at `https://fundlyhub.org/sitemap.xml`: every sitemap file of every language, one per page type (`/sitemaps/{locale}/{type}.xml` on the site, `{type}-{n}.xml` once a type outgrows one file), each with the newest `<lastmod>` in it. A type with no pages is left out. Cached for five minutes. No authentication.",
        "responses": {
          "200": {
            "description": "Sitemap index XML",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Generation failed",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/meta/sitemaps/{locale}": {
      "get": {
        "tags": [
          "Meta"
        ],
        "summary": "Get a locale's sitemap index",
        "operationId": "getLocaleSitemap",
        "description": "The `<sitemapindex>` of one locale's sitemap files (`/sitemaps/{locale}.xml` on the site), one per page type. Accepts the bare locale or the locale with `.xml`. Cached for five minutes. No authentication.",
        "parameters": [
          {
            "name": "locale",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es",
                "en.xml",
                "ru.xml",
                "uk.xml",
                "es.xml"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sitemap index XML",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Unknown locale",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Generation failed",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/meta/sitemaps/{locale}/{file}": {
      "get": {
        "tags": [
          "Meta"
        ],
        "summary": "Get one sitemap file",
        "operationId": "getSitemapFile",
        "description": "One `<urlset>` of one page type in one locale (`/sitemaps/{locale}/{file}` on the site), with `hreflang` alternates for every locale and `image:image` entries for the photos a page shows. The types are `pages` (the static pages), `fundraisers`, `nonprofits`, `churches`, `cities`, `communities`, `sponsors`, `providers`, `stories` and `profiles`. A file holds at most 45,000 URLs; a larger type continues in `{type}-2`, `{type}-3` and so on. A type with no pages answers an empty set. Cached for five minutes. No authentication.",
        "parameters": [
          {
            "name": "locale",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          },
          {
            "name": "file",
            "in": "path",
            "required": true,
            "description": "The type, then `-{n}` from the second file on, with or without `.xml`.",
            "schema": {
              "type": "string",
              "pattern": "^(pages|fundraisers|nonprofits|churches|cities|communities|sponsors|providers|stories|profiles)(-[1-9][0-9]{0,4})?(\\.xml)?$"
            },
            "example": "fundraisers.xml"
          }
        ],
        "responses": {
          "200": {
            "description": "Sitemap XML",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Unknown locale, type or file",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Generation failed",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/donations/recent": {
      "get": {
        "tags": [
          "Donations"
        ],
        "summary": "List recent gifts (public feed)",
        "operationId": "getRecentDonations",
        "description": "Paid gifts for the homepage hero, newest first, in one of two modes:\n\n- **Unscoped** (no `slugs`): the newest `limit` gifts platform-wide.\n- **Per campaign** (`slugs`): the newest `perCampaign` gifts for\n  *each* named campaign, ranked within that campaign.\n\n\nOnly gifts to public campaigns in `active` or `ended` status appear, and gifts a moderator pulled from the feed never do. An anonymous gift has its name, avatar, city and ordinal nulled. `amount_cents` is the **net** amount (after the Stripe fee) — the same figure the campaign page shows. Campaign titles are localised as for `GET /users/{id}/campaigns`.\n\nPublicly cached for 15 seconds. No authentication. Rate limited at 300 requests/minute per IP.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Unscoped mode only.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 24,
              "default": 12
            }
          },
          {
            "name": "slugs",
            "in": "query",
            "required": false,
            "description": "Comma-separated campaign slugs (or a repeated parameter). At most 6 are used; extras are ignored.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "perCampaign",
            "in": "query",
            "required": false,
            "description": "Per-campaign mode only.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 40,
              "default": 3
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The gifts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RecentGift"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/donations/receipt/{receiptId}/note": {
      "post": {
        "tags": [
          "Donations"
        ],
        "summary": "Post, edit or retract the donor's note",
        "operationId": "postDonationNote",
        "description": "Writes the note a donor leaves after payment, authorized by the **receipt id** because guest donors have no session. The donation must be paid and target a campaign or a nonprofit/church general fund. A missing, unpaid or person-targeted donation gets the same `404`.\nCampaign notes retain their public comments and creator email behavior. A direct general-fund note has a null fundraiser_id, stays on the private receipt and authorized admin note/moderation surfaces, and does not create a public organization thread or campaign email.\n\nEach donation allows **3 writes in total** (post, edits and retract combined); after that every write is `429`. Read the current note with the `GET` first so a reload does not spend one. The note is attributed to an account only when the caller is signed in as the donor.\n\nAuthentication is optional. Behind `features.comments`. Rate limited at 5 requests/minute per IP.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "receiptId",
            "in": "path",
            "required": true,
            "description": "The receipt id, or the donation's Stripe PaymentIntent id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Required unless `retract` is `true`."
                  },
                  "retract": {
                    "type": "boolean",
                    "description": "`true` withdraws the note instead of writing one."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Note retracted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "retracted": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Note written",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "fundraiser_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true,
                          "description": "Null for a direct nonprofit/church general-fund note."
                        },
                        "edits_remaining": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 2
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing receipt id, empty content, or content over 2000 characters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`features.comments` is disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No paid campaign or nonprofit general-fund donation for that receipt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Either the shared limit (5 per minute per IP), or this note has used its 3 writes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The note could not be saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Donations"
        ],
        "summary": "Get the donor's note",
        "operationId": "getDonationNote",
        "description": "The note already on a paid donation, so the composer can show it and its remaining writes (3 − `note_edit_count`). `data` is `null` when there is no note.\n\nNo authentication: the receipt id is the capability. Rate limited at 300 requests/minute per IP. Direct nonprofit/church notes remain private to this capability read and authorized admin surfaces; no donor identity is included in this response.",
        "parameters": [
          {
            "name": "receiptId",
            "in": "path",
            "required": true,
            "description": "The receipt id, or the donation's Stripe PaymentIntent id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The note, or null",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "content": {
                          "type": "string"
                        },
                        "gif": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/Gif"
                            }
                          ],
                          "nullable": true,
                          "description": "Always null — a receipt note cannot carry a GIF (#1963)."
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "note_edit_count": {
                          "type": "integer"
                        },
                        "retracted": {
                          "type": "boolean"
                        },
                        "hidden": {
                          "type": "boolean",
                          "description": "Hidden by a moderator."
                        },
                        "campaign_slug": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing receipt id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/creators/{user_id}/tiers": {
      "get": {
        "tags": [
          "Creator Subscriptions"
        ],
        "summary": "List a creator's tiers",
        "operationId": "listCreatorTiers",
        "description": "A creator's active tiers, by `sort_order` then price. Empty for a private profile, except to its owner.\n\nAuthentication is optional; it only matters for the owner.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "description": "The creator's profile UUID (slugs are not accepted).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Active tiers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CreatorTier"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`user_id` is not a UUID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/tiers": {
      "get": {
        "tags": [
          "Creator Subscriptions"
        ],
        "summary": "List my tiers",
        "operationId": "listMyCreatorTiers",
        "description": "The caller's tiers, archived ones included (active first). Empty for someone who has never created one.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The caller's tiers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CreatorTier"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Creator Subscriptions"
        ],
        "summary": "Create a tier",
        "operationId": "createMyCreatorTier",
        "description": "Creates a tier and its Stripe Product with a monthly Price (and an annual one when `annual_amount_cents` is given). Creating a first tier **grants the caller the `creator` role**; there is no separate \"become a creator\" step. Receiving payouts still needs Stripe Connect onboarding — fans can subscribe before then, and the money is held.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatorTierInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Tier created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CreatorTier"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A field failed validation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "The caller's profile was not found while granting the creator role",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The caller already has an active tier with that name",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Creation failed (including a Stripe error, e.g. an unsupported currency)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/tiers/{tier_id}": {
      "patch": {
        "tags": [
          "Creator Subscriptions"
        ],
        "summary": "Update a tier",
        "operationId": "updateMyCreatorTier",
        "description": "Partial update of one of the caller's tiers. Changing a price mints a new Stripe Price and deactivates the old one; existing subscribers keep their original price until renewal. Setting `annual_amount_cents` to `null` withdraws annual billing. Currency cannot be changed. A tier that is not the caller's is a `404`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "tier_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 1000,
                    "nullable": true
                  },
                  "amount_cents": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "annual_amount_cents": {
                    "type": "integer",
                    "minimum": 1,
                    "nullable": true
                  },
                  "benefits": {
                    "type": "array",
                    "maxItems": 20,
                    "items": {
                      "type": "string",
                      "maxLength": 200
                    }
                  },
                  "cover_image": {
                    "type": "string",
                    "maxLength": 2048,
                    "nullable": true
                  },
                  "sort_order": {
                    "type": "integer"
                  },
                  "subscriber_limit": {
                    "type": "integer",
                    "minimum": 1,
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated tier",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CreatorTier"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A field failed validation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such tier for this caller, or `tier_id` is not a UUID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Another of the caller's tiers already has that name",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Update failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Creator Subscriptions"
        ],
        "summary": "Archive a tier",
        "operationId": "archiveMyCreatorTier",
        "description": "Archives one of the caller's tiers (`is_active: false`), hiding it from the public list. Reversible, and safe for tiers with subscribers. To remove a tier for good, use `DELETE /me/tiers/{tier_id}/permanent`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "tier_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Archived"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such tier for this caller, or `tier_id` is not a UUID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Archive failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/tiers/{tier_id}/permanent": {
      "delete": {
        "tags": [
          "Creator Subscriptions"
        ],
        "summary": "Delete a tier permanently",
        "operationId": "deleteMyCreatorTier",
        "description": "Deletes one of the caller's tiers outright. Only possible for a tier nobody has ever subscribed to — a cancelled subscription is still a billing record — otherwise `409` with `code: TIER_HAS_SUBSCRIBERS`; archive it instead.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "tier_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such tier for this caller, or `tier_id` is not a UUID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The tier has subscription history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "TIER_HAS_SUBSCRIBERS"
                      ]
                    },
                    "subscriber_count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Deletion failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/subscriptions": {
      "post": {
        "tags": [
          "Creator Subscriptions"
        ],
        "summary": "Subscribe to a creator tier",
        "operationId": "createCreatorSubscription",
        "description": "Creates a Stripe Subscription to an active tier, recorded locally as `incomplete`. Confirm the first payment in the browser with Stripe Elements using `client_secret`; the webhook then moves it to `active`.\n\nCalling again while a previous attempt for the same tier is still `incomplete` or `past_due` resumes it — the same subscription and `client_secret` — rather than creating a second one. An `active` or `trialing` subscription to the tier is a `409`. Subscribing to a different tier of the same creator is allowed.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tier_id",
                  "interval"
                ],
                "properties": {
                  "tier_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "interval": {
                    "type": "string",
                    "enum": [
                      "month",
                      "year"
                    ],
                    "description": "`year` only when the tier has an annual price."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Subscription created or resumed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "subscription_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "stripe_subscription_id": {
                          "type": "string"
                        },
                        "client_secret": {
                          "type": "string",
                          "nullable": true,
                          "description": "For confirming the first invoice's PaymentIntent."
                        },
                        "status": {
                          "$ref": "#/components/schemas/CreatorSubscriptionStatus"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`tier_id` not a UUID, bad `interval`, tier missing or archived, the caller owns the tier, or the tier has no price for that interval.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "description": "Already subscribed to this tier, the tier is at its subscriber limit, or the creator's account deletion is due (past its grace period) and the tier takes no new members",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Stripe rejected the subscription; `error` is Stripe's message",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Creation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Creator Subscriptions"
        ],
        "summary": "List my creator subscriptions",
        "operationId": "listMyCreatorSubscriptions",
        "description": "Every subscription the caller holds, ended ones included, with tier and creator display fields. Active and trialing first, then past due, paused, and the rest; newest first within each.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The caller's subscriptions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CreatorSubscription"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/subscriptions/{id}/cancel": {
      "post": {
        "tags": [
          "Creator Subscriptions"
        ],
        "summary": "Cancel a creator subscription",
        "operationId": "cancelCreatorSubscription",
        "description": "An `active` or `trialing` subscription is set to cancel at the end of the paid period. One that is `incomplete`, `past_due`, `unpaid` or `paused` is cancelled immediately. Already cancelled or already scheduled is a no-op. A subscription that is not the caller's is a `404`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The local subscription id (`subscription_id`), not the Stripe id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Cancelled or scheduled"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such subscription for this caller",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Cancellation failed (including a Stripe error)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/subscriptions/{id}/resume": {
      "post": {
        "tags": [
          "Creator Subscriptions"
        ],
        "summary": "Resume a creator subscription",
        "operationId": "resumeCreatorSubscription",
        "description": "Undoes a scheduled cancellation while the subscription is still running. A no-op when nothing is scheduled. A subscription that has already ended cannot be resumed — subscribe again.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Resumed (or nothing to undo)"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such subscription for this caller",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The subscription has already ended",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Resume failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/unsubscribe/preview": {
      "get": {
        "tags": [
          "Email Preferences"
        ],
        "summary": "Preview an unsubscribe link",
        "operationId": "previewUnsubscribe",
        "description": "Validates the signed token from an email's unsubscribe link and says which (masked) address and which scope it would silence. Changes nothing.\n\nNo authentication: the signed token is the authorisation. Rate limited at 300 requests/minute per IP.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The token is valid",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/UnsubscribeResult"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The token is missing, invalid or malformed. `error` is an i18n key: `unsubscribe.error_stale_link` when the link still carries an unrendered `{{unsubscribe_token}}` placeholder (request a fresh link with `POST /unsubscribe/request`), else `unsubscribe.error_invalid`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "unsubscribe.error_stale_link",
                        "unsubscribe.error_invalid"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The link could not be checked because the database was unavailable (`error` is `unsubscribe.error_generic`). The link itself may be fine; try again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/unsubscribe": {
      "post": {
        "tags": [
          "Email Preferences"
        ],
        "summary": "Unsubscribe",
        "operationId": "unsubscribe",
        "description": "Suppresses mail to the token's address for the token's scope, or for everything when `all` is `true`. Idempotent.\n\nNo authentication: the signed token is the authorisation. No feature flag can switch this off. Rate limited at 10 requests/minute per IP.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UnsubscribeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Unsubscribed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/UnsubscribeResult"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The token is missing, invalid or malformed. `error` is an i18n key: `unsubscribe.error_stale_link` when the link still carries an unrendered `{{unsubscribe_token}}` placeholder (request a fresh link with `POST /unsubscribe/request`), else `unsubscribe.error_invalid`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "unsubscribe.error_stale_link",
                        "unsubscribe.error_invalid"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The suppression could not be saved (`error` is an i18n key)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/unsubscribe/resubscribe": {
      "post": {
        "tags": [
          "Email Preferences"
        ],
        "summary": "Resubscribe",
        "operationId": "resubscribe",
        "description": "Lifts the suppression for the token's address and scope (or for `all`). The undo for `POST /unsubscribe`.\n\nNo authentication: the signed token is the authorisation. Rate limited at 10 requests/minute per IP.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UnsubscribeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resubscribed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/UnsubscribeResult"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The token is missing, invalid or malformed. `error` is an i18n key: `unsubscribe.error_stale_link` when the link still carries an unrendered `{{unsubscribe_token}}` placeholder (request a fresh link with `POST /unsubscribe/request`), else `unsubscribe.error_invalid`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "unsubscribe.error_stale_link",
                        "unsubscribe.error_invalid"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The change could not be saved (`error` is an i18n key)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/unsubscribe/request": {
      "post": {
        "tags": [
          "Email Preferences"
        ],
        "summary": "Request a fresh unsubscribe link",
        "operationId": "requestUnsubscribeLink",
        "description": "Mails a new signed unsubscribe link to `email` — the repair path for old emails whose link carried no token. Sent only to an address FundlyHub has previously mailed, at most once per address per hour.\n\n**Always answers `{ \"data\": { \"sent\": true } }`**, whatever happened, so it cannot be used to test whether an address is known.\n\nNo authentication. Rate limited at 10 requests/minute per IP.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "sent": {
                          "type": "boolean",
                          "enum": [
                            true
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/ambassador-invites/redeem": {
      "post": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "Redeem an ambassador invitation",
        "operationId": "redeemAmbassadorInvite",
        "description": "Accepts an ambassador invitation for the signed-in account — the path for Google and Apple sign-ups, which cannot carry the token through `POST /cognito/signup`. The invitation is matched against the account's own registered email address; someone else's token is declined with `email_mismatch`.\n\nA declined redemption is still a **`200`** with `granted: false` and a `reason`, so a client can always call this after sign-up even when the token was already spent. No special permission is needed.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "token"
                ],
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "The `ambassador_invite` token from the invitation link."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Granted, or declined with a reason",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "granted": {
                      "type": "boolean"
                    },
                    "reason": {
                      "type": "string",
                      "description": "Present only when `granted` is false.",
                      "enum": [
                        "no_token",
                        "not_found",
                        "used",
                        "revoked",
                        "expired",
                        "email_mismatch",
                        "role_missing"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`token` missing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Redemption failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/ambassador-applications": {
      "post": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "Apply to be an ambassador",
        "operationId": "createAmbassadorApplication",
        "description": "Files an application to the ambassador programme for review by FundlyHub. Works signed out; when a session is present, the application records which account filed it.\n\nOne pending application per address: a second is `409`, as is an address that already holds the ambassador role.\n\nAuthentication is optional. Rate limited at 5 requests/minute per IP.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "fullName",
                  "email",
                  "location",
                  "experience",
                  "motivation"
                ],
                "properties": {
                  "fullName": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 120
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 254
                  },
                  "location": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 160
                  },
                  "socialMedia": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "A URL, or an empty string."
                  },
                  "experience": {
                    "type": "string",
                    "minLength": 50,
                    "maxLength": 5000
                  },
                  "motivation": {
                    "type": "string",
                    "minLength": 50,
                    "maxLength": 5000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Application received",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "received": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A field failed validation; `error` names it (e.g. `motivation:` …)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "A pending application exists for this address, or it already belongs to an ambassador",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "The application could not be recorded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/ambassadors": {
      "get": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "List ambassadors (public directory)",
        "operationId": "listAmbassadors",
        "description": "Ambassador role-holders with a public profile, ordered by the money their referral links have driven — what those gifts raised, net of fees, tips excluded (the amounts themselves are not returned). Feeds the front-page rail.\n\nNo authentication. Rate limited at 300 requests/minute per IP.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 60,
              "default": 24
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The directory",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ambassadors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "userId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string",
                            "nullable": true
                          },
                          "avatar": {
                            "type": "string",
                            "nullable": true
                          },
                          "href": {
                            "type": "string",
                            "description": "Profile path — by slug when there is one, by id otherwise."
                          },
                          "location": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/ambassadors/selectable": {
      "get": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "List ambassadors for the endorsement picker",
        "operationId": "listSelectableAmbassadors",
        "description": "Ambassadors a campaign creator may ask to endorse their campaign: role-holders with a public profile, excluding the caller, with the lifetime money each has driven in cents — what those gifts raised, net of fees, tips excluded. Authenticated because it carries those amounts.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 60,
              "default": 24
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Literal, case-insensitive substring of the ambassador name; trimmed and matched before the result limit. Blank returns the default ranked list.",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The picker list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ambassadors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "userId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string",
                            "nullable": true
                          },
                          "avatar": {
                            "type": "string",
                            "nullable": true
                          },
                          "referredCents": {
                            "type": "integer",
                            "description": "What gifts through this ambassador's links raised, net of fees, tips excluded."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Search is not a string or exceeds 120 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/ambassadors/{id}/analytics": {
      "get": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "Get an ambassador's referral analytics",
        "operationId": "getAmbassadorAnalytics",
        "description": "All-time referral analytics for one ambassador: clicks by traffic type, conversions, attributed funds per currency, and breakdowns by campaign, UTM source and day.\n\nCallers may read their **own** analytics; anyone else's answers `403`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The ambassador's profile UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The analytics (bare object)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralAnalytics"
                }
              }
            }
          },
          "400": {
            "description": "`id` is not a UUID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/referrals/codes": {
      "post": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "Get or create my referral code",
        "operationId": "getOrCreateReferralCode",
        "description": "Returns the caller's referral code — the profile-level one, or the one for `fundraiser_id` — creating it on first use. Idempotent. Share links take the form `/r/{code}` on the site. Every signed-in user can hold a code; the ambassador role is not required.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "fundraiser_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true,
                    "description": "Omit or `null` for the profile-level code."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The code",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "example": "aB3dE5fG7h"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`fundraiser_id` is not a UUID",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "invalid_body"
                      ]
                    },
                    "details": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "The code could not be created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/referrals/clicks": {
      "post": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "Record a referral-link click",
        "operationId": "recordReferralClick",
        "description": "Called by the FundlyHub web app when a visitor opens a referral link (`/r/{code}`); not for third-party clients. Returns where to redirect and the visitor id to set as a cookie. Records a click classified as human, bot or unknown, and stamps the code into `utm_content`. When the visitor is signed in, the code is also remembered on their profile for attribution.\n\nAn unknown code still answers `200` with `resolved: false` and a `target_path` of the home page.\n\nAuthentication is optional. Rate limited per caller: 120 requests/minute, on top of the global per-IP limiter. Past the limit the answer is `429` with `Retry-After`.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 64
                  },
                  "user_agent": {
                    "type": "string",
                    "nullable": true
                  },
                  "request_method": {
                    "type": "string",
                    "maxLength": 8,
                    "default": "GET"
                  },
                  "referer": {
                    "type": "string",
                    "nullable": true
                  },
                  "visitor_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true,
                    "description": "Generated when absent."
                  },
                  "ip": {
                    "type": "string",
                    "nullable": true,
                    "description": "The visitor's address. Stored only as a hash."
                  },
                  "utm_source": {
                    "type": "string",
                    "nullable": true
                  },
                  "utm_medium": {
                    "type": "string",
                    "nullable": true
                  },
                  "utm_campaign": {
                    "type": "string",
                    "nullable": true
                  },
                  "utm_content": {
                    "type": "string",
                    "nullable": true
                  },
                  "entry_point": {
                    "type": "string",
                    "enum": [
                      "redirect",
                      "landing"
                    ],
                    "default": "redirect"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Click processed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralClickResult"
                }
              }
            }
          },
          "400": {
            "description": "Body failed validation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "invalid_body"
                      ]
                    },
                    "details": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Recording failed. The body still carries a safe fallback (`target_path: \"/\"`) so the caller can redirect.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ReferralClickResult"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string",
                          "enum": [
                            "internal_error"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/me/referrals/summary": {
      "get": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "Get my referral summary",
        "operationId": "getMyReferralSummary",
        "description": "The ambassador portal's headline: totals, the click-to-gift funnel and a daily series for the caller's own referral links over a window (default: the 28 days ending `to`). Every portal route reads only the session's own rows.\n\n**Requires permission:** `view_own_referral_portal`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start. Defaults to 28 days before `to`. Must be before `to` and not earlier than 2020-01-01.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end. Defaults to now.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AmbassadorPortalSummary"
                    },
                    "range": {
                      "$ref": "#/components/schemas/AmbassadorPortalRange"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`from` or `to` is not a date, out of order, or before 2020-01-01",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "from must be before to"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "invalid_range"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/referrals/campaigns": {
      "get": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "List campaigns I referred to",
        "operationId": "getMyReferredCampaigns",
        "description": "Per-campaign clicks, visitors, driven gifts and money raised from the caller's referral links in the window.\n\n**Requires permission:** `view_own_referral_portal`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start. Defaults to 28 days before `to`. Must be before `to` and not earlier than 2020-01-01.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end. Defaults to now.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The campaigns",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "fundraiser_id": {
                            "type": "string",
                            "format": "uuid",
                            "nullable": true
                          },
                          "fundraiser_title": {
                            "type": "string",
                            "nullable": true
                          },
                          "fundraiser_slug": {
                            "type": "string",
                            "nullable": true
                          },
                          "clicks_human": {
                            "type": "integer"
                          },
                          "clicks_bot": {
                            "type": "integer"
                          },
                          "clicks_unknown": {
                            "type": "integer"
                          },
                          "distinct_human_visitors": {
                            "type": "integer"
                          },
                          "driven_gifts": {
                            "type": "integer"
                          },
                          "raised_cents": {
                            "type": "integer"
                          },
                          "last_click_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "range": {
                      "$ref": "#/components/schemas/AmbassadorPortalRange"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`from` or `to` is not a date, out of order, or before 2020-01-01",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "from must be before to"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "invalid_range"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/referrals/campaigns/{fundraiserId}": {
      "get": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "Get what my referral link did for one campaign",
        "operationId": "getMyCampaignReferralStats",
        "description": "All-time figures for the caller's own referral link on one campaign: impressions (visits not identified as a bot), clicks by traffic type, distinct human visitors, driven gifts (paid, not self-referred), distinct donors, and the value of those gifts (donation + tip) per currency in cents. The same definitions as the per-campaign rows of the ambassador analytics. Also returns the caller's referral code and link for the campaign when one exists; this read never creates one. Feeds the ambassador bar on the campaign page.\n\nA campaign the caller may not open (draft, pending, private or deleted, and not their own) is a 404, as its page is.\n\n**Requires permission:** `view_own_referral_portal`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "fundraiserId",
            "in": "path",
            "required": true,
            "description": "The campaign's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The caller's figures for the campaign",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "fundraiser_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "impressions": {
                          "type": "integer",
                          "description": "Visits through the link that were not identified as a bot."
                        },
                        "clicks_by_traffic_type": {
                          "type": "object",
                          "properties": {
                            "human": {
                              "type": "integer"
                            },
                            "bot": {
                              "type": "integer"
                            },
                            "unknown": {
                              "type": "integer"
                            }
                          }
                        },
                        "distinct_human_visitors": {
                          "type": "integer"
                        },
                        "driven_gifts": {
                          "type": "integer"
                        },
                        "distinct_donors": {
                          "type": "integer"
                        },
                        "funds_attributed": {
                          "type": "array",
                          "description": "Donation + tip per currency, in cents, largest first.",
                          "items": {
                            "type": "object",
                            "properties": {
                              "currency": {
                                "type": "string"
                              },
                              "amount_cents": {
                                "type": "integer"
                              }
                            }
                          }
                        },
                        "referral_code": {
                          "type": "string",
                          "nullable": true
                        },
                        "referral_url": {
                          "type": "string",
                          "nullable": true,
                          "example": "https://fundlyhub.org/r/AbC123xYz0"
                        },
                        "last_click_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "last_gift_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "as_of": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the figures were read."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`fundraiserId` is not a uuid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/referrals/traffic": {
      "get": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "Get my referral traffic breakdown",
        "operationId": "getMyReferralTraffic",
        "description": "Where the caller's referral clicks came from — by UTM source, referer and medium — plus traffic type, and country and device splits from Google Analytics when it is configured (`ga_note` says why those are `null` otherwise).\n\n**Requires permission:** `view_own_referral_portal`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start. Defaults to 28 days before `to`. Must be before `to` and not earlier than 2020-01-01.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end. Defaults to now.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The breakdown",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AmbassadorPortalTraffic"
                    },
                    "range": {
                      "$ref": "#/components/schemas/AmbassadorPortalRange"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`from` or `to` is not a date, out of order, or before 2020-01-01",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "from must be before to"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "invalid_range"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/referrals/gifts": {
      "get": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "List gifts I drove",
        "operationId": "getMyReferredGifts",
        "description": "The donations attributed to the caller's referral links in the window, refunded, failed and self-referred gifts included. Each row carries exactly the fields of `AmbassadorGift`: no donor email, card details or receipt reference, and no donor name on an anonymous gift.\n\n**Requires permission:** `view_own_referral_portal`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start. Defaults to 28 days before `to`. Must be before `to` and not earlier than 2020-01-01.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end. Defaults to now.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of gifts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AmbassadorGift"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "drivenTotal": {
                      "type": "integer"
                    },
                    "range": {
                      "$ref": "#/components/schemas/AmbassadorPortalRange"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`from` or `to` is not a date, out of order, or before 2020-01-01",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "from must be before to"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "invalid_range"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/referrals/standing": {
      "get": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "Get my ambassador standing",
        "operationId": "getMyReferralStanding",
        "description": "The caller's rank among ambassadors by money raised in the window — what gifts through their links raised, net of fees, tips excluded — and the leaderboard (up to 200 rows; `truncated` when there are more). Other ambassadors with private profiles appear without name or avatar.\n\n**Requires permission:** `view_own_referral_portal`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start. Defaults to 28 days before `to`. Must be before `to` and not earlier than 2020-01-01.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end. Defaults to now.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The standing",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "rank": {
                          "type": "integer",
                          "nullable": true,
                          "description": "Null when the caller has no ranked activity in the window."
                        },
                        "total_ambassadors": {
                          "type": "integer"
                        },
                        "leaderboard": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "rank": {
                                "type": "integer"
                              },
                              "ambassador_user_id": {
                                "type": "string",
                                "format": "uuid",
                                "nullable": true
                              },
                              "display_name": {
                                "type": "string",
                                "nullable": true
                              },
                              "avatar_url": {
                                "type": "string",
                                "nullable": true
                              },
                              "raised_cents": {
                                "type": "integer"
                              },
                              "driven_gifts": {
                                "type": "integer"
                              },
                              "is_me": {
                                "type": "boolean"
                              }
                            }
                          }
                        },
                        "truncated": {
                          "type": "boolean"
                        }
                      }
                    },
                    "range": {
                      "$ref": "#/components/schemas/AmbassadorPortalRange"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`from` or `to` is not a date, out of order, or before 2020-01-01",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "from must be before to"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "invalid_range"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/referrals/businesses": {
      "get": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "Get the businesses I invited to become sponsors",
        "operationId": "getMyReferralBusinesses",
        "description": "The businesses the caller brought to FundlyHub, newest first: the ones that started Become a sponsor through the caller's link (`/sponsors/join?ref=CODE`, `code` below), and the ones the caller emailed an invite that haven't started yet (`kind: invite`, stage `invited`). A business that starts a page is listed by its page, matched by the email its creator signs in with. Each says how far it has got, in neutral words: `invited` (`opened` once it followed the email's link), `started` (setting up its page; `step` while a draft), `submitted` (with FundlyHub), `live` (live or paused; `slug` is its page) or `not_live` (never which, nor why: an ambassador never sees what a reviewer found). `send` (an invite) and `reminder` (a page being set up) say when the caller can email it again: three emails per address at most, three days apart. Perks used are counts from the sponsor's impact, shown for the businesses that went live; never who used them. Answers `403` while sponsors are switched off.\n\n**Requires permission:** `view_own_referral_portal`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The businesses",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "description": "The caller's referral code, for the invite link and its QR."
                    },
                    "totals": {
                      "type": "object",
                      "properties": {
                        "businesses": {
                          "type": "integer"
                        },
                        "live": {
                          "type": "integer"
                        },
                        "inProgress": {
                          "type": "integer",
                          "description": "Invited, started or submitted."
                        },
                        "perksUsedAtLive": {
                          "type": "integer"
                        }
                      }
                    },
                    "businesses": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "kind": {
                            "type": "string",
                            "enum": [
                              "sponsor",
                              "invite"
                            ]
                          },
                          "id": {
                            "type": "string",
                            "format": "uuid",
                            "description": "The sponsor's id, or the invite's."
                          },
                          "name": {
                            "type": "string"
                          },
                          "categoryId": {
                            "type": "string",
                            "nullable": true
                          },
                          "logoUrl": {
                            "type": "string",
                            "nullable": true,
                            "description": "A live business's logo."
                          },
                          "home": {
                            "type": "object",
                            "nullable": true,
                            "description": "Its home location's name and city; for an invite, the area the caller typed.",
                            "properties": {
                              "label": {
                                "type": "string",
                                "nullable": true
                              },
                              "city": {
                                "type": "string",
                                "nullable": true
                              }
                            }
                          },
                          "locationKinds": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": [
                                "premises",
                                "service_area",
                                "online"
                              ]
                            }
                          },
                          "stage": {
                            "type": "string",
                            "enum": [
                              "invited",
                              "started",
                              "submitted",
                              "live",
                              "not_live"
                            ]
                          },
                          "step": {
                            "type": "integer",
                            "nullable": true,
                            "minimum": 1,
                            "maximum": 5
                          },
                          "slug": {
                            "type": "string",
                            "nullable": true
                          },
                          "email": {
                            "type": "string",
                            "description": "An invite only, the address the caller typed."
                          },
                          "opened": {
                            "type": "boolean",
                            "description": "An invite only, whether its link was followed."
                          },
                          "startedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "sponsorSince": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "perksUsed": {
                            "type": "integer",
                            "nullable": true
                          },
                          "send": {
                            "$ref": "#/components/schemas/AmbassadorSendState"
                          },
                          "reminder": {
                            "allOf": [
                              {
                                "$ref": "#/components/schemas/AmbassadorSendState"
                              }
                            ],
                            "nullable": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Not signed in"
          },
          "403": {
            "description": "Not an ambassador, or sponsors are switched off"
          }
        }
      }
    },
    "/me/referrals/businesses/invites": {
      "post": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "Invite a business by email",
        "operationId": "inviteMyReferralBusiness",
        "description": "Emails a business an invite from the caller: what being a sponsor is, and a link of its own that marks the invite opened and lands on For businesses with the caller's ref. One invite per address; twenty new addresses a day. The link's token is only ever in the email.\n\n**Requires permission:** `view_own_referral_portal`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "businessName",
                  "email"
                ],
                "properties": {
                  "businessName": {
                    "type": "string",
                    "maxLength": 80
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "categoryId": {
                    "type": "string",
                    "description": "The kind of business, from the sponsor categories. Optional."
                  },
                  "area": {
                    "type": "string",
                    "maxLength": 60,
                    "description": "A neighborhood or street, in the caller's words. Optional."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Sent",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A field is missing or wrong (`details.field`)"
          },
          "401": {
            "description": "Not signed in"
          },
          "403": {
            "description": "Not an ambassador, or sponsors are switched off"
          },
          "409": {
            "description": "`already_invited`, or `already_started` (it started a page with the caller's link)"
          },
          "429": {
            "description": "`too_many_invites`: twenty a day"
          },
          "503": {
            "description": "`email_failed`: nothing was sent; try again"
          }
        }
      }
    },
    "/me/referrals/businesses/invites/{inviteId}/send-again": {
      "post": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "Send an invite again",
        "operationId": "sendMyReferralBusinessInviteAgain",
        "description": "The invite again, with a fresh link (the earlier one stops working): three emails per address at most, three days apart.\n\n**Requires permission:** `view_own_referral_portal`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "inviteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sent"
          },
          "401": {
            "description": "Not signed in"
          },
          "403": {
            "description": "Not an ambassador, or sponsors are switched off"
          },
          "404": {
            "description": "Not one of the caller's invites"
          },
          "409": {
            "description": "`too_many_sends`: the address had its three emails"
          },
          "429": {
            "description": "`too_soon`: `details.nextAt` says when"
          },
          "503": {
            "description": "`email_failed`"
          }
        }
      }
    },
    "/me/referrals/businesses/{sponsorId}/remind": {
      "post": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "Remind a business that started its page",
        "operationId": "remindMyReferralBusiness",
        "description": "A reminder to a business that started Become a sponsor with the caller's link and stopped (a draft, or one sent back for changes): an email to the address its creator signs in with, with a link back to where it was left. Counts toward that address's three emails, three days apart.\n\n**Requires permission:** `view_own_referral_portal`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "sponsorId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sent"
          },
          "401": {
            "description": "Not signed in"
          },
          "403": {
            "description": "Not an ambassador, or sponsors are switched off"
          },
          "404": {
            "description": "Not one of the caller's businesses"
          },
          "409": {
            "description": "`not_started` (it is past setting up), `no_email`, or `too_many_sends`"
          },
          "429": {
            "description": "`too_soon`: `details.nextAt` says when"
          },
          "503": {
            "description": "`email_failed`"
          }
        }
      }
    },
    "/sponsors/join/invites/{token}": {
      "get": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "Follow an ambassador's invite link",
        "operationId": "openAmbassadorInvite",
        "description": "The link in an ambassador's invite email. Marks the invite opened the first time, then redirects to For businesses with the ambassador's ref (`/sponsors/join?ref=CODE`). A link that was replaced or never existed still redirects there, without a ref.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "To For businesses on the site"
          }
        }
      }
    },
    "/me/campaigns": {
      "get": {
        "tags": [
          "Ambassadors"
        ],
        "summary": "List my own campaigns (ambassador portal)",
        "operationId": "getMyOwnedCampaignsForPortal",
        "description": "The campaigns the caller owns, with totals and how many clicks on their own referral links led to them (self-referrals, which do not count as driven). Takes no date range.\n\n**Requires permission:** `view_own_referral_portal`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The caller's campaigns",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "title": {
                            "type": "string",
                            "nullable": true
                          },
                          "slug": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string",
                            "nullable": true
                          },
                          "goal_amount_cents": {
                            "type": "integer"
                          },
                          "total_raised_cents": {
                            "type": "integer"
                          },
                          "donation_count": {
                            "type": "integer"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "self_referred_clicks": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/dmca/notice": {
      "post": {
        "tags": [
          "DMCA"
        ],
        "summary": "File a DMCA takedown notice",
        "operationId": "submitDmcaNotice",
        "description": "Files a §512(c) takedown notice against a campaign or one of its media files. No account is needed to file. Both attestations must be `true`, and either `mediaId` or `fundraiserId` is required. Returns only a reference id; the claimant is emailed a confirmation and updates.\n\nNo authentication. Behind `features.dmca_workflow`, which is **currently disabled** (`403`). Rate limited at 5 requests/minute per IP.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "claimantName",
                  "claimantEmail",
                  "claimantAddress",
                  "infringingUrl",
                  "copyrightedWorkDescription",
                  "electronicSignature",
                  "goodFaithStatement",
                  "authorityStatement"
                ],
                "properties": {
                  "claimantName": {
                    "type": "string"
                  },
                  "claimantOrganization": {
                    "type": "string",
                    "nullable": true
                  },
                  "claimantEmail": {
                    "type": "string",
                    "format": "email"
                  },
                  "claimantPhone": {
                    "type": "string",
                    "nullable": true
                  },
                  "claimantAddress": {
                    "type": "string"
                  },
                  "mediaId": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true,
                    "description": "The media file. When given, the campaign is derived from it."
                  },
                  "fundraiserId": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                  },
                  "infringingUrl": {
                    "type": "string"
                  },
                  "copyrightedWorkDescription": {
                    "type": "string"
                  },
                  "copyrightedWorkUrl": {
                    "type": "string",
                    "nullable": true
                  },
                  "goodFaithStatement": {
                    "type": "boolean",
                    "description": "Must be `true` (§512(c)(3)(A)(v))."
                  },
                  "authorityStatement": {
                    "type": "boolean",
                    "description": "Must be `true` (§512(c)(3)(A)(vi))."
                  },
                  "electronicSignature": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Notice received",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "complaintId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "submittedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A required field is missing, an attestation is false, no target was given, or `mediaId` / `fundraiserId` is not a valid id (`code: INVALID_INPUT`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DmcaError"
                }
              }
            }
          },
          "403": {
            "description": "`features.dmca_workflow` is disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`mediaId` does not match a media file",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DmcaError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error (`Internal server error`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/dmca/complaints/{id}/counter-notice": {
      "post": {
        "tags": [
          "DMCA"
        ],
        "summary": "File a DMCA counter-notice",
        "operationId": "submitDmcaCounterNotice",
        "description": "The uploader of media taken down under a notice files a §512(g) counter-notice. Only the media's original uploader may file, and only against a complaint in `valid` status. All three statements must be `true`. FundlyHub forwards it to the claimant.\n\nBehind `features.dmca_workflow`, which is **currently disabled** (`403`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The complaint id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "goodFaithStatement",
                  "consentToJurisdiction",
                  "perjuryStatement",
                  "electronicSignature",
                  "contactName",
                  "contactAddress",
                  "contactPhone",
                  "contactEmail"
                ],
                "properties": {
                  "goodFaithStatement": {
                    "type": "boolean",
                    "description": "Must be `true` (§512(g)(3)(C))."
                  },
                  "consentToJurisdiction": {
                    "type": "boolean",
                    "description": "Must be `true` (§512(g)(3)(D))."
                  },
                  "perjuryStatement": {
                    "type": "boolean",
                    "description": "Must be `true` (§512(g)(3)(A))."
                  },
                  "electronicSignature": {
                    "type": "string"
                  },
                  "contactName": {
                    "type": "string"
                  },
                  "contactAddress": {
                    "type": "string"
                  },
                  "contactPhone": {
                    "type": "string"
                  },
                  "contactEmail": {
                    "type": "string",
                    "format": "email"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Counter-notice received",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "counterNoticeId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "submittedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A field is missing or false, or the complaint has no media attached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DmcaError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The feature flag is off, or the caller did not upload the media",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DmcaError"
                }
              }
            }
          },
          "404": {
            "description": "No such complaint (including an `id` that is not a valid id), or its media no longer exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DmcaError"
                }
              }
            }
          },
          "409": {
            "description": "The complaint is not in `valid` status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DmcaError"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error (`Internal server error`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users/{id}/achievements": {
      "get": {
        "tags": [
          "Achievements"
        ],
        "summary": "Get a profile's achievements",
        "operationId": "getUserAchievements",
        "description": "The achievements section of a profile: the badges the person has earned that visitors may see, each with its card, plus a public holder block, a summary counted over the returned rows, the profile's pinned card and the label vocabulary. `id` is a UUID or a profile slug.\n\nThe answer is the same for everyone, the owner included, except that the owner's own rows carry their counts (`stats`). A private or inactive profile read by anyone but its owner answers `{ \"data\": [], \"withheld\": true, \"vocabulary\": … }`.\n\nAuthentication is optional. Rate limited at 300 requests/minute per IP.",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Profile UUID or profile slug.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Locale for titles and labels; unsupported locales fall back to English.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The collection, or a withheld answer",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AchievementView"
                      }
                    },
                    "withheld": {
                      "type": "boolean",
                      "description": "Present (true) only when the profile is private or inactive."
                    },
                    "holder": {
                      "$ref": "#/components/schemas/AchievementHolder"
                    },
                    "summary": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "Counts over `data` (by tier, rarity and series). Shape is dynamic."
                    },
                    "pin": {
                      "$ref": "#/components/schemas/AchievementPin"
                    },
                    "vocabulary": {
                      "$ref": "#/components/schemas/AchievementVocabulary"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/achievements": {
      "get": {
        "tags": [
          "Achievements"
        ],
        "summary": "Get my achievements",
        "operationId": "getMyAchievements",
        "description": "The owner view: every achievement the caller holds — themselves and through organizations they administer — including those set to \"only me\", with private stats and progress; `next_up`, the closest badges not yet earned; the caller's pin; and how many new cards are waiting to be revealed.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The owner collection",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AchievementView"
                      }
                    },
                    "holder": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/AchievementHolder"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "full_name": {
                              "type": "string",
                              "nullable": true
                            }
                          }
                        }
                      ]
                    },
                    "summary": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "next_up": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "pin": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/AchievementPin"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "publicly_readable": {
                              "type": "boolean",
                              "nullable": true,
                              "description": "Whether visitors can open the pinned card; null for the automatic choice."
                            }
                          }
                        }
                      ]
                    },
                    "pin_writable": {
                      "type": "boolean"
                    },
                    "unrevealed_count": {
                      "type": "integer"
                    },
                    "vocabulary": {
                      "$ref": "#/components/schemas/AchievementVocabulary"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/achievements/pin": {
      "put": {
        "tags": [
          "Achievements"
        ],
        "summary": "Pin an achievement card",
        "operationId": "pinMyAchievementCard",
        "description": "Pins one of the caller's own live cards (theirs, or an organization's they administer) to that holder's profile. A malformed, unknown, void or someone else's card all get the **same** `404` body, so the answer never says whether a code exists. Responses are `private, no-store`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "card_code"
                ],
                "properties": {
                  "card_code": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Pinned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "pin": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/AchievementPin"
                            },
                            {
                              "type": "object",
                              "properties": {
                                "publicly_readable": {
                                  "type": "boolean"
                                }
                              }
                            }
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`card_code` missing or not a string",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodedError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Card not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodedError"
                }
              }
            }
          },
          "500": {
            "description": "Pin failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Achievements"
        ],
        "summary": "Unpin an achievement card",
        "operationId": "unpinMyAchievementCard",
        "description": "Clears the caller's pin, or with `organization` that organization's pin when the caller administers it. Idempotent. The profile then shows the automatic choice.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "organization",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Unpinned"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "The caller does not administer that organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodedError"
                }
              }
            }
          },
          "500": {
            "description": "Unpin failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/achievements/reveals": {
      "get": {
        "tags": [
          "Achievements"
        ],
        "summary": "Get my reveal pack",
        "operationId": "getMyAchievementReveals",
        "description": "Cards waiting to be \"opened\": with `receipt`, the ones a particular donation earned (the thank-you page — `status: pending` while the award is still being computed); with `all=true`, every unrevealed card. Pass exactly one. Someone else's receipt answers like a donation that earned nothing (`status: none`). Responses are `private, no-store`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "receipt",
            "in": "query",
            "required": false,
            "description": "A Stripe PaymentIntent id.",
            "schema": {
              "type": "string",
              "pattern": "^pi_[A-Za-z0-9_]{1,255}$"
            }
          },
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The pack",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "ready",
                            "none"
                          ]
                        },
                        "events": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "integer"
                              },
                              "event_ids": {
                                "type": "array",
                                "items": {
                                  "type": "integer"
                                },
                                "description": "Pass these to `POST /me/achievements/reveals/ack`."
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "issued",
                                  "upgraded",
                                  "reawarded"
                                ]
                              },
                              "tier": {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string"
                                  },
                                  "label": {
                                    "type": "string"
                                  }
                                }
                              },
                              "from_tier": {
                                "type": "object",
                                "nullable": true,
                                "properties": {
                                  "key": {
                                    "type": "string"
                                  },
                                  "label": {
                                    "type": "string"
                                  }
                                }
                              },
                              "revealed": {
                                "type": "boolean"
                              },
                              "card": {
                                "type": "object",
                                "additionalProperties": true,
                                "description": "The card as drawn (code, art, numbering, dates)."
                              },
                              "tierup_line": {
                                "type": "string",
                                "nullable": true
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Neither or both of `receipt` and `all`, or a malformed `receipt`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodedError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/achievements/reveals/ack": {
      "post": {
        "tags": [
          "Achievements"
        ],
        "summary": "Mark reveal events as opened",
        "operationId": "ackMyAchievementReveals",
        "description": "Marks the caller's own reveal events as revealed. Ids that are not the caller's are ignored silently; the answer is `204` either way.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "event_ids"
                ],
                "properties": {
                  "event_ids": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 200,
                    "items": {
                      "type": "integer",
                      "minimum": 1
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Acknowledged"
          },
          "400": {
            "description": "`event_ids` is not 1–200 positive integers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodedError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Acknowledgement failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/me/achievements/{slug}": {
      "patch": {
        "tags": [
          "Achievements"
        ],
        "summary": "Set an achievement's visibility",
        "operationId": "updateMyAchievementVisibility",
        "description": "The holder's \"Visible to: Everyone / Only me\" control for one badge. `default` follows the badge's own visibility. When the caller wears the badge both personally and through an organization (or through two organizations), `holder` must say which; otherwise `409` with the list of `holders`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The achievement's slug.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "visibility_override"
                ],
                "properties": {
                  "visibility_override": {
                    "type": "string",
                    "enum": [
                      "default",
                      "public",
                      "private"
                    ]
                  },
                  "holder": {
                    "type": "object",
                    "description": "A malformed value is ignored rather than rejected.",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "user",
                          "organization"
                        ]
                      },
                      "id": {
                        "type": "string",
                        "format": "uuid"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated award",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AchievementView"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`visibility_override` missing or invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodedError"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "The caller does not hold this achievement (as that holder)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodedError"
                }
              }
            }
          },
          "409": {
            "description": "Several of the caller's holders wear it; name one",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/CodedError"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "holders": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": [
                                  "user",
                                  "organization"
                                ]
                              },
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Update failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/chatwoot/identity-hash": {
      "get": {
        "tags": [
          "Support"
        ],
        "summary": "Get the live-chat identity hash",
        "operationId": "getChatwootIdentityHash",
        "description": "The caller's identity hash for the support chat widget's `setUser(…, { identifier_hash })`, so the chat knows which signed-in user it is talking to.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The hash",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "identifier_hash": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Hashing failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Identity validation is not configured on this deployment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/join": {
      "get": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "For businesses",
        "operationId": "getSponsorJoinLanding",
        "description": "What /sponsors/join shows beyond its own words, all of it real: the ambassador whose link brought the visitor (`ref`); the visitor's city (where the edge says they are, else their own city; the nearest with sponsors within 30 miles, else the one with the most) with its sponsor count and its most used sponsors' logos; and a sponsor's quote, shown only with consent once staff approved it. No city or no quote: null.",
        "parameters": [
          {
            "name": "ref",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "An ambassador's code, from /sponsors/join?ref=."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "inviter": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "name": {
                          "type": "string",
                          "description": "First name and last initial (\"Elena V.\")."
                        },
                        "initials": {
                          "type": "string"
                        }
                      }
                    },
                    "city": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "slug": {
                          "type": "string",
                          "nullable": true
                        },
                        "name": {
                          "type": "string"
                        },
                        "label": {
                          "type": "string"
                        },
                        "sponsors": {
                          "type": "integer"
                        },
                        "more": {
                          "type": "integer",
                          "description": "Sponsors past the logo tiles."
                        },
                        "logos": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "slug": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "logo_url": {
                                "type": "string",
                                "nullable": true
                              }
                            }
                          }
                        }
                      }
                    },
                    "quote": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "text": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "initials": {
                          "type": "string"
                        },
                        "role": {
                          "type": "string",
                          "enum": [
                            "owner",
                            "admin",
                            "manager",
                            "cashier",
                            "member"
                          ]
                        },
                        "title": {
                          "type": "string",
                          "nullable": true
                        },
                        "sponsor": {
                          "type": "object",
                          "properties": {
                            "slug": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/map/place": {
      "get": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "The small map of a place",
        "operationId": "getSponsorPlaceMap",
        "description": "Redirects (302) to a signed Apple Maps snapshot of the street around a pin. 404 when no signing key is configured, and the page shows its pin tile instead.",
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lng",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "s",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 32,
              "maximum": 192
            },
            "description": "The tile's side in CSS pixels."
          },
          {
            "name": "scheme",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "light",
                "dark"
              ]
            }
          }
        ],
        "responses": {
          "302": {
            "description": "The snapshot."
          },
          "404": {
            "description": "No map for that place here.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/new/waitlist": {
      "post": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Tell me when sponsors open in my country",
        "operationId": "joinSponsorCountryWaitlist",
        "description": "For a business outside the US. The person and the country; the message goes to their own email when sponsors open there, and nothing else.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "country_code": {
                    "type": "string",
                    "description": "ISO 3166-1 alpha-2, not US."
                  }
                },
                "required": [
                  "country_code"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "country_code": {
                      "type": "string"
                    },
                    "waiting": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "description": "`invalid`, `open` (the US).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/new": {
      "get": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "What the Become a sponsor forms need",
        "operationId": "getSponsorJoinOptions",
        "description": "The categories with whether each may join, the Sponsor Terms version and the most unfinished drafts one person may have.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorJoinOptions"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/sponsors/drafts": {
      "get": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "My unfinished sponsors",
        "operationId": "listMySponsorDrafts",
        "description": "Drafts and sponsors sent back for changes that the person started, newest first.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "drafts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/sponsors/find": {
      "get": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Is this business already on FundlyHub?",
        "operationId": "findSponsorBusiness",
        "description": "Sponsors that may already be the business: the same Apple Maps place, the same website, or a close name; with whether the person is on its team, asked to join or claimed it. Apple Maps itself is searched in the browser. Drafts and sponsors under review are never shown to others.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "apple_place_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "website",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "matches": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "drafts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/sponsors/{key}/join-requests": {
      "post": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Ask to join a sponsor's team",
        "operationId": "requestToJoinSponsor",
        "description": "The owner or an admin decides. Needs a verified email.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "message": {
                    "type": "string",
                    "maxLength": 500
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "pending"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`already_member`, `already_asked`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/claims": {
      "post": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "It's my business — tell us",
        "operationId": "claimSponsor",
        "description": "An ownership question a person at FundlyHub looks into, with proof the person runs the business (a document kept privately with the claim, never one of the sponsor's own). Needs a verified email.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "note": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "doc_type": {
                    "type": "string",
                    "enum": [
                      "business_license",
                      "state_filing",
                      "ein_letter",
                      "dba_filing",
                      "seller_permit",
                      "other"
                    ]
                  },
                  "file_name": {
                    "type": "string"
                  },
                  "file_base64": {
                    "type": "string",
                    "description": "A PDF, JPG, PNG or HEIC file, up to 7 MB, base64."
                  }
                },
                "required": [
                  "doc_type",
                  "file_base64"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "open"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`already_claimed`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/onboarding": {
      "get": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "The draft, as the five steps read it",
        "operationId": "getSponsorOnboarding",
        "description": "Its page, locations, proof, owners, first perk and terms, and what still blocks submitting.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorJoinDraft"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Save a step",
        "operationId": "patchSponsorOnboarding",
        "description": "The step the person is on; step 2's title, 25%-owners answer and statement; and any page fields (as PATCH /sponsors/{key}/manage/page). One request saves a step whole. A draft follows its name to a new address; a new legal name clears the statement.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/SponsorManagePageInput"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "step": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 5
                      },
                      "title": {
                        "type": "string",
                        "maxLength": 80
                      },
                      "owners": {
                        "type": "array",
                        "maxItems": 4,
                        "description": "As PUT /sponsors/{key}/owners takes it.",
                        "items": {
                          "$ref": "#/components/schemas/SponsorOwnerInput"
                        }
                      },
                      "authority_statement": {
                        "type": "boolean",
                        "description": "true confirms the statement in its current wording; false takes it back."
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorJoinDraft"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`submitted`, `legal_locked`, `name_in_use`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`unsafe` (a link flagged by Web Risk) and field errors.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Delete a draft",
        "operationId": "deleteSponsorDraft",
        "description": "Only a draft that never went to review; only the person who started it (or staff for one staff added).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "204": {
            "description": "Done"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`owner_only`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`not_a_draft`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/onboarding/checks": {
      "post": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Run the automatic checks before submitting",
        "operationId": "runSponsorOnboardingChecks",
        "description": "The state registry (California's at launch) and the sanctions lists, run while the review step is open so it can show them. They only add evidence; submitting runs them again.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorJoinDraft"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`submitted`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "429": {
            "description": "Too many in a short while.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/verify/email-code": {
      "post": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Show you run it: send a code to your work email",
        "operationId": "sendSponsorWorkEmailCode",
        "description": "The address must be at the domain of the business's own website (`website` saves it first). Free email domains, and a website on another company's platform, can't prove it. 15 minutes, 5 tries.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string"
                  },
                  "website": {
                    "type": "string"
                  }
                },
                "required": [
                  "email"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SponsorCodeSent"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "domain": {
                          "type": "string"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`not_a_draft`, `staff_evidence`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`free_email_domain`, `email_domain_mismatch`, `website_required`, `website_not_own_domain`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited` (5 codes an hour).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/verify/email": {
      "post": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Show you run it: enter the code",
        "operationId": "verifySponsorWorkEmail",
        "description": "A right code records the proof (a sponsor_checks pass).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string"
                  },
                  "code": {
                    "type": "string",
                    "pattern": "^[0-9]{6}$",
                    "description": "The 6-digit code emailed to the person (POST /sponsors/{key}/manage/codes)."
                  }
                },
                "required": [
                  "email",
                  "code"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorJoinDraft"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`code_required`, `bad_code` (with `attempts_left`), `expired`, `too_many_attempts`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/verify/documents": {
      "post": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Show you run it: upload a document",
        "operationId": "uploadSponsorDocument",
        "description": "A business license, a state filing naming you, the IRS EIN letter... Kept private; a person reads it (about 2 business days). PDF, JPG, PNG or HEIC up to 7 MB, as base64; the type is read from the file.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "doc_type": {
                    "type": "string",
                    "enum": [
                      "business_license",
                      "state_filing",
                      "ein_letter",
                      "dba_filing",
                      "seller_permit",
                      "other"
                    ]
                  },
                  "file_name": {
                    "type": "string"
                  },
                  "file_base64": {
                    "type": "string"
                  }
                },
                "required": [
                  "doc_type",
                  "file_base64"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorJoinDraft"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`too_many_documents`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`file_type`, `too_large`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/verify/documents/{docId}": {
      "delete": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Take back a document",
        "operationId": "deleteSponsorDocument",
        "description": "Only one nobody has read yet.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "docId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The document."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorJoinDraft"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`document_decided`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/owners": {
      "put": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Who owns 25% or more",
        "operationId": "putSponsorOwners",
        "description": "Everyone who owns 25% or more, screened against the U.S. Treasury's sanctions list; an empty list says no one does. Four at most.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "owners": {
                    "type": "array",
                    "maxItems": 4,
                    "items": {
                      "$ref": "#/components/schemas/SponsorOwnerInput"
                    }
                  }
                },
                "required": [
                  "owners"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorJoinDraft"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/submit": {
      "post": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Submit for review",
        "operationId": "submitSponsor",
        "description": "The owner accepts the Sponsor Terms; the authority statement is the one confirmed on step 2, or `authority_statement` confirms it now. The application and the first perk go to a FundlyHub reviewer. Publishes sponsor.application_submitted.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "terms_version": {
                    "type": "string"
                  },
                  "authority_statement": {
                    "type": "boolean",
                    "enum": [
                      true
                    ],
                    "description": "Not needed when the statement was confirmed on step 2."
                  }
                },
                "required": [
                  "terms_version"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorJoinDraft"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`owner_only`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`already_submitted`, `staff_draft`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`incomplete` (with `missing`), `terms_required`, `statement_required`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/withdraw": {
      "post": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Take the application back",
        "operationId": "withdrawSponsor",
        "description": "While it waits for review; it becomes a draft again.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorJoinDraft"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`owner_only`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`not_under_review`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsor-invites/{token}": {
      "get": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "A team or owner invite",
        "operationId": "getSponsorInvite",
        "description": "What the invite page shows, for the caller: the sponsor, the role and locations, and whether accepting will work.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The invite token from the email link."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorInviteView"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such invite.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsor-invites/{token}/accept": {
      "post": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Accept an invite",
        "operationId": "acceptSponsorInvite",
        "description": "One of the person's verified emails must be the invited one. An owner invite also takes the 25%-owners answer, the Sponsor Terms and the authority statement, and sends the sponsor to review. Publishes sponsor.member_joined.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The invite token from the email link."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "owners": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "full_name": {
                          "type": "string"
                        },
                        "me": {
                          "type": "boolean"
                        }
                      }
                    }
                  },
                  "terms_version": {
                    "type": "string"
                  },
                  "authority_statement": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "sponsor_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "role": {
                      "type": "string"
                    },
                    "joined": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`email_mismatch`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such invite.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`expired`, `revoked`, `declined`, `not_waiting`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`terms_required`, `statement_required` (owner invites).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsor-invites/{token}/decline": {
      "post": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Decline an invite",
        "operationId": "declineSponsorInvite",
        "description": "Declining an owner invite hands the sponsor back to staff as a draft.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The invite token from the email link."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "declined": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`email_mismatch`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such invite.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`expired`, `revoked`, `accepted`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/me/sponsor-invites": {
      "get": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "My business invites",
        "operationId": "listMySponsorInvites",
        "description": "The team and owner invites waiting for the signed-in person, so they can join or decline in the app and not only from the email's link. An invite sent to their sign-in email while it is unconfirmed is listed under `unconfirmed` by address alone.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorMyInvites"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/me/sponsor-invites/{inviteId}/accept": {
      "post": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Accept one of my business invites",
        "operationId": "acceptMySponsorInvite",
        "description": "The invite page's accept, by the invite's id. A team invite takes nothing; an owner invite takes the 25%-owners answer, the Sponsor Terms and the authority statement, and sends the sponsor to review. Publishes sponsor.member_joined.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "inviteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "owners": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "full_name": {
                          "type": "string"
                        },
                        "me": {
                          "type": "boolean"
                        }
                      }
                    }
                  },
                  "terms_version": {
                    "type": "string"
                  },
                  "authority_statement": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "sponsor_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "role": {
                      "type": "string"
                    },
                    "joined": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such invite, or not one sent to this person.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`expired`, `revoked`, `declined`, `closed`, `not_waiting`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`terms_required`, `statement_required` (owner invites).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/me/sponsor-invites/{inviteId}/decline": {
      "post": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Decline one of my business invites",
        "operationId": "declineMySponsorInvite",
        "description": "The invite page's decline, by the invite's id. Declining an owner invite hands the sponsor back to staff as a draft.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "inviteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "declined": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such invite, or not one sent to this person.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`expired`, `revoked`, `accepted`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/finish-joining": {
      "get": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Does the owner still have to finish joining",
        "operationId": "getSponsorFinishJoining",
        "description": "When a super admin accepted the owner invite for this person, the sponsor waits for the owner's own answers. Pending while the sponsor is waiting for its owner, the caller is its owner, and nobody accepted its terms.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's page link or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorFinishJoining"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or the caller is not on its team.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Finish joining as the owner",
        "operationId": "finishSponsorJoining",
        "description": "The rest of the owner invite, from the owner a super admin seated. Records who owns 25% or more, the Sponsor Terms and the authority statement, and sends the sponsor to review with a second reviewer. Publishes sponsor.application_submitted.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's page link or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "owners": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "full_name": {
                          "type": "string"
                        },
                        "me": {
                          "type": "boolean"
                        }
                      }
                    }
                  },
                  "terms_version": {
                    "type": "string"
                  },
                  "authority_statement": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "sponsor_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "under_review"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`owner_only`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such sponsor, or the caller is not on its team.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`not_waiting`: nothing to finish.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`terms_required`, `statement_required`, `owners`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage": {
      "get": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Overview",
        "operationId": "getSponsorWorkspace",
        "description": "What needs the team, the numbers (a manager's are their locations'), the locations, recent perks used (never who) and the person's row of the access table.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageOverview"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/codes": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Email a code to confirm a sensitive move",
        "operationId": "sendSponsorStepUpCode",
        "description": "Before handing over ownership, leaving FundlyHub, adding an admin or pairing a counter device, a 6-digit code goes to the person's own sign-in address (FundlyHub has no 2-step sign-in). 15 minutes, 5 tries, one use. Staff never need one.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "purpose": {
                    "type": "string",
                    "enum": [
                      "transfer_ownership",
                      "leave",
                      "add_admin",
                      "pair_device"
                    ]
                  }
                },
                "required": [
                  "purpose"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SponsorCodeSent"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "purpose": {
                          "type": "string"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`not_allowed`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`staff_no_code`, `no_email`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/page": {
      "get": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "The page",
        "operationId": "getSponsorPageSettings",
        "description": "Owner and admins.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManagePage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Edit the page",
        "operationId": "patchSponsorPageSettings",
        "description": "Owner and admins. The legal name and registration lock once the state's record matches; the category is set before review.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SponsorManagePageInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManagePage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`category_locked`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`legal_locked`, `name_in_use`, `closed`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`unsafe` and field errors.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/perks": {
      "get": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Perks",
        "operationId": "listSponsorPerksForTeam",
        "description": "Every perk with its draft, the change with a reviewer, a change scheduled and the last decision; and how many are live of 10.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "perks": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SponsorManagePerk"
                      }
                    },
                    "live": {
                      "type": "integer"
                    },
                    "max_live": {
                      "type": "integer"
                    },
                    "fine_print": {
                      "type": "array",
                      "description": "\"Fine print for every perk\", in its order (PUT /sponsors/{key}/manage/fine-print).",
                      "items": {
                        "type": "string"
                      }
                    },
                    "website_host": {
                      "type": "string",
                      "nullable": true,
                      "description": "The sponsor's website, which an online perk's one-time codes are for."
                    },
                    "achievements": {
                      "type": "object",
                      "description": "The achievements the perks are for, by id, titled in the reader's language (`?lang=`, the language cookie, Accept-Language).",
                      "additionalProperties": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Add a perk (a draft)",
        "operationId": "createSponsorPerk",
        "description": "Owner and admins.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "terms": {
                    "$ref": "#/components/schemas/SponsorManagePerkTerms"
                  }
                },
                "required": [
                  "terms"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManagePerk"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`too_many_perks`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "Field errors: `achievement_id` `not_allowed` or `paused`, `in_store` `no_locations`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/fine-print": {
      "put": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Fine print for every perk",
        "operationId": "setSponsorFinePrint",
        "description": "Owner, admins and staff. Up to five lines the sponsor sets once for all its perks; the sponsor page shows them on its Perks tab, and a perk's own fine print adds to them. Each line is plain text, up to 100 characters, with its spaces folded; a line can't name a charity, a cause or a Fundly, offer a chance to win, or mention alcohol, tobacco, vapes or cannabis (the words that send a perk's fine print to a reviewer). An empty list clears them. Logged in the audit trail.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "lines"
                ],
                "properties": {
                  "lines": {
                    "type": "array",
                    "maxItems": 5,
                    "items": {
                      "type": "string",
                      "maxLength": 100
                    }
                  }
                }
              },
              "example": {
                "lines": [
                  "One perk per visit, unless it says otherwise.",
                  "Show your code before you pay."
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The lines now in force.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "lines": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`not_allowed`: only the owner, admins and staff set the fine print.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`closed`: the sponsor has left FundlyHub.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`invalid`, `too_long`, `too_many`, `duplicate` or `not_allowed` (with `details.flags`), naming the line in `details.field` (`lines.2`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/perks/preview": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "What sending a perk's terms would do",
        "operationId": "previewSponsorPerk",
        "description": "Owner, admins and staff. Nothing is written. The outcome submit would reach for these terms: `live` (now), `scheduled` (a change that takes something from givers waits 14 days; `smaller` says why, and `told` how many givers hear of it today: the sponsor's followers and the perk's users in 90 days, null under 10 with `fewer_than: 10`), `in_review` (a person reads it first, with the `flags`; staff's perks always), or `draft` while the sponsor isn't live. The terms are checked as on save (422 naming the field).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "terms"
                ],
                "properties": {
                  "terms": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The terms as POST /sponsors/{key}/manage/perks takes them."
                  },
                  "perk_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true,
                    "description": "The perk being changed; omit for a new perk."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "outcome": {
                      "type": "string",
                      "enum": [
                        "live",
                        "scheduled",
                        "in_review",
                        "draft"
                      ]
                    },
                    "effective_at": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "smaller": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "achievement",
                          "tier",
                          "value",
                          "in_store",
                          "online",
                          "locations",
                          "frequency",
                          "cap",
                          "hours",
                          "starts",
                          "ends",
                          "fine_print"
                        ]
                      }
                    },
                    "flags": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "told": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "count": {
                          "type": "integer",
                          "nullable": true
                        },
                        "fewer_than": {
                          "type": "integer",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor or perk.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "The terms aren't valid; `details.field` names the field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/perks/{perkId}/history": {
      "get": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "A perk's history",
        "operationId": "getSponsorPerkHistory",
        "description": "Anyone on the team who sees perks. What happened to the perk, oldest first: `created`, `changed` (a new version started), `submitted`, `approved` (by FundlyHub after a review), `live`, `scheduled` (a change or an `ending` that waits), `changes_requested`, `not_approved`, `withdrawn`, `paused` (now, until when and why) and `stopped`. `by` names a team member, or is `{staff: true}` for FundlyHub. `audience` is who a change that waits is told to: the followers and the perk's users in 90 days (under 10: `fewer_than: 10`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "kind": {
                            "type": "string"
                          },
                          "by": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "name": {
                                "type": "string",
                                "nullable": true
                              },
                              "staff": {
                                "type": "boolean"
                              }
                            }
                          },
                          "title": {
                            "type": "string",
                            "nullable": true
                          },
                          "previous_title": {
                            "type": "string",
                            "nullable": true
                          },
                          "effective_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "until": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "reason": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "audience": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer",
                          "nullable": true
                        },
                        "fewer_than": {
                          "type": "integer",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor or perk.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/perks/options": {
      "get": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "The perk builder's options",
        "operationId": "getSponsorPerkOptions",
        "description": "The achievements perks may be for, giving achievements first (the tracks in the vocabulary's order), with their tiers and thresholds, optional canonical `art` (AchievementArt), what a threshold counts (`unit`, and the noun by plural form in `units`, as in \"10 donations\") and, in the reader's language, their title, tagline and how to earn them; the open locations (a storefront with its `street`, each with its `city`), the category and the rules (10 live, 14 days, $25).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "achievements": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "slug": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "art": {
                            "nullable": true,
                            "allOf": [
                              {
                                "$ref": "#/components/schemas/AchievementArt"
                              }
                            ]
                          }
                        }
                      }
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/perks/estimate": {
      "get": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "How many people could use it",
        "operationId": "getSponsorPerkEstimate",
        "description": "People whose city is the sponsor's home city holding the tier or higher. Fewer than 10 is never a number.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "achievement_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "tier_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "city": {
                      "type": "object",
                      "nullable": true,
                      "additionalProperties": true
                    },
                    "holders": {
                      "type": "integer",
                      "nullable": true
                    },
                    "fewer_than": {
                      "type": "integer",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/perks/order": {
      "put": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Reorder the perks",
        "operationId": "orderSponsorPerks",
        "description": "Perks not named keep their order after these.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "perk_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                },
                "required": [
                  "perk_ids"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "perk_ids": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "format": "uuid"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/perks/{perkId}/draft": {
      "put": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Start or edit a change",
        "operationId": "saveSponsorPerkDraft",
        "description": "A draft of new terms for the perk.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The perk."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "terms": {
                    "$ref": "#/components/schemas/SponsorManagePerkTerms"
                  }
                },
                "required": [
                  "terms"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManagePerk"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`in_review` (withdraw it first), `stopped`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Discard the draft",
        "operationId": "discardSponsorPerkDraft",
        "description": "A perk that was only a draft goes with it.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The perk."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted_perk": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`no_draft`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/perks/{perkId}/submit": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Send the change",
        "operationId": "submitSponsorPerk",
        "description": "A person reviews a perk worth more than $25 a use, \"something else\", flagged wording, and anything staff wrote. Otherwise it is approved now: at once when it is at least as good in every way, in 14 days when anything got smaller (givers are told). Publishes sponsor.perk_live or sponsor.perk_change_scheduled.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The perk."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "outcome": {
                      "type": "string",
                      "enum": [
                        "in_review",
                        "live",
                        "scheduled"
                      ]
                    },
                    "effective_at": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "flags": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "perk": {
                      "$ref": "#/components/schemas/SponsorManagePerk"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`not_live` (the first perk goes with the application), `no_draft`, `too_many_perks`, `stopped`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/perks/{perkId}/withdraw": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Take a change back",
        "operationId": "withdrawSponsorPerkChange",
        "description": "From a reviewer (it becomes the draft again) or a change still scheduled.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The perk."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManagePerk"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`nothing_to_withdraw`, `with_application`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/perks/{perkId}/pause": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Pause a perk",
        "operationId": "pauseSponsorPerk",
        "description": "Starts now and ends on its own, at most 14 days out; givers see the reason. The owner, admins and staff pause any perk; a manager pauses a perk that runs in store at their own locations and nowhere else, since a pause stops it everywhere it runs.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The perk."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "until": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "reason": {
                    "type": "string",
                    "maxLength": 80
                  }
                },
                "required": [
                  "until",
                  "reason"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManagePerk"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`not_your_location`: a manager, and the perk runs somewhere else too.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`not_live`, `stopped`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`too_long`, `in_the_past`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Resume a perk",
        "operationId": "resumeSponsorPerk",
        "description": "Back now. Whoever may pause the perk may end its pause.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The perk."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManagePerk"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`not_your_location`: a manager, and the perk runs somewhere else too.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/perks/{perkId}/end": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "End a perk",
        "operationId": "endSponsorPerk",
        "description": "It ends in 14 days, so the givers who count on it are told first; a change in progress is dropped. Publishes sponsor.perk_change_scheduled.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The perk."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManagePerk"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`not_live`, `already_ending`, `stopped`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/updates": {
      "get": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Updates",
        "operationId": "listSponsorUpdatesForTeam",
        "description": "The page's updates, newest first, with when the next one reaches followers' bells.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManagePosts"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Post an update",
        "operationId": "createSponsorUpdate",
        "description": "Up to 600 characters, one photo (sponsor-photos bucket) and the locations it is about. One update a week reaches followers' bells. Updates can't name a charity, a cause or a Fundly, or promote alcohol, tobacco, vapes or cannabis. Publishes sponsor.post_published.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string",
                    "maxLength": 600
                  },
                  "photo_url": {
                    "type": "string",
                    "nullable": true
                  },
                  "location_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                },
                "required": [
                  "body"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManagePosts"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`not_live`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`not_allowed` (with `flags`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/updates/{postId}": {
      "patch": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Edit an update",
        "operationId": "editSponsorUpdate",
        "description": "Shows on the page at once; bells are not sent again.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "postId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The update."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string"
                  },
                  "photo_url": {
                    "type": "string",
                    "nullable": true
                  },
                  "location_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                },
                "required": [
                  "body"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManagePosts"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`removed`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Delete an update",
        "operationId": "deleteSponsorUpdate",
        "description": "",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "postId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The update."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManagePosts"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/locations": {
      "get": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Locations",
        "operationId": "listSponsorLocationsForTeam",
        "description": "The locations the person works with (a manager's own), with their stickers and counter devices.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "locations": {
                      "type": "array",
                      "description": "Each with its stickers and counter devices and (#2361, board WsLocations) its state as the overview's locations carry it (time_zone, now, closure), pickup_only and dba_name.",
                      "items": {
                        "allOf": [
                          {
                            "$ref": "#/components/schemas/SponsorManageLocation"
                          },
                          {
                            "type": "object",
                            "properties": {
                              "time_zone": {
                                "type": "string"
                              },
                              "now": {
                                "type": "object",
                                "description": "state: open (closesAt), closed (opens: weekday, time; or null), temporarily_closed (until, reason) or no_hours.",
                                "additionalProperties": true
                              },
                              "closure": {
                                "type": "object",
                                "nullable": true,
                                "description": "The closure covering today, or the next within 30 days (startsOn, endsOn, reason).",
                                "additionalProperties": true
                              },
                              "pickup_only": {
                                "type": "boolean",
                                "description": "A storefront that is a pickup point."
                              },
                              "dba_name": {
                                "type": "string",
                                "nullable": true,
                                "description": "The name it trades under there."
                              }
                            }
                          }
                        ]
                      }
                    },
                    "max_open": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Add a location",
        "operationId": "createSponsorLocation",
        "description": "A place customers visit (pinned on the map), \"We come to customers\" (ZIP codes served) or \"Online only\". US addresses; the first is the main one. A live sponsor's new location gets its free sticker kit.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "premises",
                      "service_area",
                      "online"
                    ]
                  },
                  "label": {
                    "type": "string",
                    "maxLength": 60
                  },
                  "address": {
                    "type": "object",
                    "properties": {
                      "line1": {
                        "type": "string"
                      },
                      "line2": {
                        "type": "string",
                        "nullable": true
                      },
                      "city": {
                        "type": "string"
                      },
                      "region": {
                        "type": "string",
                        "description": "The state, as its code or name."
                      },
                      "postal_code": {
                        "type": "string",
                        "description": "A US ZIP or ZIP+4."
                      },
                      "country": {
                        "type": "string",
                        "description": "US only at launch; leave it out."
                      }
                    },
                    "required": [
                      "line1",
                      "city",
                      "region",
                      "postal_code"
                    ]
                  },
                  "point": {
                    "type": "object",
                    "properties": {
                      "lat": {
                        "type": "number"
                      },
                      "lng": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "lat",
                      "lng"
                    ],
                    "description": "The street-level point of the Apple Maps place. Required for a place customers visit."
                  },
                  "apple_place_id": {
                    "type": "string"
                  },
                  "dba_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                  },
                  "pickup_only": {
                    "type": "boolean",
                    "description": "Customers only pick up here (a storefront only); its weekly hours are pickup hours."
                  },
                  "is_primary": {
                    "type": "boolean"
                  },
                  "hours": {
                    "type": "array",
                    "maxItems": 21,
                    "items": {
                      "type": "object",
                      "properties": {
                        "weekday": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 7,
                          "description": "ISO weekday, 1 = Monday."
                        },
                        "opens_at": {
                          "type": "string",
                          "example": "06:30"
                        },
                        "closes_at": {
                          "type": "string",
                          "example": "18:00",
                          "description": "At or before opens_at runs past midnight; equal = open 24 hours."
                        }
                      },
                      "required": [
                        "weekday",
                        "opens_at",
                        "closes_at"
                      ]
                    }
                  },
                  "zips": {
                    "type": "array",
                    "maxItems": 60,
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "kind",
                  "address"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageLocation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`too_many_locations`, `closed`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`point_required`, `us_only`, `address_unknown_postal_code`, `address_unknown_city`, `address_lookup_failed`, `unknown_postal_code` (zips).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/locations/{locationId}": {
      "patch": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Edit a location",
        "operationId": "updateSponsorLocation",
        "description": "Another address or Apple Maps place ends the address confirmation; a live sponsor's moved location gets a new kit and its old stickers stop.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The location."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string"
                  },
                  "address": {
                    "type": "object",
                    "properties": {
                      "line1": {
                        "type": "string"
                      },
                      "line2": {
                        "type": "string",
                        "nullable": true
                      },
                      "city": {
                        "type": "string"
                      },
                      "region": {
                        "type": "string",
                        "description": "The state, as its code or name."
                      },
                      "postal_code": {
                        "type": "string",
                        "description": "A US ZIP or ZIP+4."
                      },
                      "country": {
                        "type": "string",
                        "description": "US only at launch; leave it out."
                      }
                    },
                    "required": [
                      "line1",
                      "city",
                      "region",
                      "postal_code"
                    ]
                  },
                  "point": {
                    "type": "object",
                    "properties": {
                      "lat": {
                        "type": "number"
                      },
                      "lng": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "lat",
                      "lng"
                    ],
                    "description": "The street-level point of the Apple Maps place. Required for a place customers visit."
                  },
                  "apple_place_id": {
                    "type": "string"
                  },
                  "dba_id": {
                    "type": "string",
                    "nullable": true
                  },
                  "zips": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "kit_ship_to_location_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true,
                    "description": "Another open location to mail its sticker kit to; null for here."
                  },
                  "pickup_only": {
                    "type": "boolean",
                    "description": "Customers only pick up here (a storefront only); its weekly hours are pickup hours."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageLocation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`location_closed`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`point_required` and address errors.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/locations/{locationId}/primary": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Make it the main location",
        "operationId": "makeSponsorLocationPrimary",
        "description": "Its city is the sponsor's home city.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The location."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "locations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SponsorManageLocation"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/locations/{locationId}/close": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Close a location for good",
        "operationId": "closeSponsorLocation",
        "description": "Off the map, history kept; its stickers and counter devices stop.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The location."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "locations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SponsorManageLocation"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`primary_location`, `perk_needs_location` (with `perk_ids`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/locations/{locationId}/hours": {
      "put": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Weekly hours",
        "operationId": "putSponsorLocationHours",
        "description": "The week, replaced. A manager at their own locations. Overlapping hours answer `location_hours_no_overlap`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The location."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "hours": {
                    "type": "array",
                    "maxItems": 21,
                    "items": {
                      "type": "object",
                      "properties": {
                        "weekday": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 7,
                          "description": "ISO weekday, 1 = Monday."
                        },
                        "opens_at": {
                          "type": "string",
                          "example": "06:30"
                        },
                        "closes_at": {
                          "type": "string",
                          "example": "18:00",
                          "description": "At or before opens_at runs past midnight; equal = open 24 hours."
                        }
                      },
                      "required": [
                        "weekday",
                        "opens_at",
                        "closes_at"
                      ]
                    }
                  }
                },
                "required": [
                  "hours"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageLocation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`not_your_location`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`location_hours_no_overlap`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/locations/{locationId}/exceptions": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Special hours or a temporary closure",
        "operationId": "addSponsorSpecialHours",
        "description": "A closure of a live sponsor's location tells its followers and recent givers there (sponsor.location_closure).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The location."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "starts_on": {
                    "type": "string",
                    "format": "date"
                  },
                  "ends_on": {
                    "type": "string",
                    "format": "date"
                  },
                  "opens_at": {
                    "type": "string",
                    "nullable": true
                  },
                  "closes_at": {
                    "type": "string",
                    "nullable": true
                  },
                  "reason": {
                    "type": "string",
                    "maxLength": 140,
                    "nullable": true
                  },
                  "closed": {
                    "type": "boolean",
                    "description": "Closed those days (no hours); a reason is required, givers see it."
                  }
                },
                "required": [
                  "starts_on"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageLocation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`in_the_past`, `location_hours_exceptions_no_overlap`, field errors.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/locations/{locationId}/exceptions/{exceptionId}": {
      "patch": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Edit special hours",
        "operationId": "updateSponsorSpecialHours",
        "description": "",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The location."
          },
          {
            "name": "exceptionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The special hours."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "starts_on": {
                    "type": "string",
                    "format": "date"
                  },
                  "ends_on": {
                    "type": "string",
                    "format": "date"
                  },
                  "opens_at": {
                    "type": "string",
                    "nullable": true
                  },
                  "closes_at": {
                    "type": "string",
                    "nullable": true
                  },
                  "reason": {
                    "type": "string",
                    "maxLength": 140,
                    "nullable": true
                  },
                  "closed": {
                    "type": "boolean",
                    "description": "Closed those days (no hours); a reason is required, givers see it."
                  }
                },
                "required": [
                  "starts_on"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageLocation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Remove special hours",
        "operationId": "deleteSponsorSpecialHours",
        "description": "",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The location."
          },
          {
            "name": "exceptionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The special hours."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageLocation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/team": {
      "get": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Team",
        "operationId": "getSponsorTeam",
        "description": "The people, invites waiting, requests to join and an offer of ownership.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageTeam"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/team/invites": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Invite someone",
        "operationId": "inviteToSponsorTeam",
        "description": "Owners and admins invite admins and managers; a manager invites cashiers at their own locations. An admin invite needs the emailed code (add_admin). The link lasts 30 days. Publishes sponsor.invite_sent.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string"
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "admin",
                      "manager",
                      "cashier"
                    ]
                  },
                  "title": {
                    "type": "string"
                  },
                  "location_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "code": {
                    "type": "string",
                    "pattern": "^[0-9]{6}$",
                    "description": "The 6-digit code emailed to the person (POST /sponsors/{key}/manage/codes)."
                  }
                },
                "required": [
                  "email",
                  "role"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "invite": {
                      "$ref": "#/components/schemas/SponsorManageInvite"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`not_allowed`, `not_your_location`, `owner_only`: the role can't do that.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`already_member`, `already_invited`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`code_required`, `bad_code` and field errors.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/team/invites/{inviteId}/resend": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Resend an invite",
        "operationId": "resendSponsorTeamInvite",
        "description": "A fresh link (the old one stops) and 30 more days; five sends at most.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "inviteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The invite."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "invite": {
                      "$ref": "#/components/schemas/SponsorManageInvite"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`too_many_sends`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/team/invites/{inviteId}": {
      "delete": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Cancel an invite",
        "operationId": "cancelSponsorTeamInvite",
        "description": "The link stops working.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "inviteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The invite."
          }
        ],
        "responses": {
          "204": {
            "description": "Done"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/team/members/{memberId}": {
      "patch": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Change a team member",
        "operationId": "updateSponsorTeamMember",
        "description": "Role, locations, title, whether they show on the page. A promotion to admin needs the emailed code. The owner's role changes only by handing over ownership; anyone may change their own title.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "memberId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The team member (sponsor_members.id)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "role": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  },
                  "show_on_page": {
                    "type": "boolean"
                  },
                  "location_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "code": {
                    "type": "string",
                    "pattern": "^[0-9]{6}$",
                    "description": "The 6-digit code emailed to the person (POST /sponsors/{key}/manage/codes)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageTeam"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`not_allowed`, `not_your_location`, `owner_only`: the role can't do that.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`owner_role`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`code_required`, `transfer_instead`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Remove a team member",
        "operationId": "removeSponsorTeamMember",
        "description": "Never the owner.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "memberId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The team member (sponsor_members.id)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageTeam"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`not_allowed`, `not_your_location`, `owner_only`: the role can't do that.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`owner_role`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/team/leave": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Leave the team",
        "operationId": "leaveSponsorTeam",
        "description": "Anyone on the team but the owner, who hands over first.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "left": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`owner_role`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/team/requests/{requestId}/approve": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Let someone join",
        "operationId": "approveSponsorJoinRequest",
        "description": "With the role chosen here. Publishes sponsor.member_joined.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The request to join."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "role": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  },
                  "location_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "code": {
                    "type": "string",
                    "pattern": "^[0-9]{6}$",
                    "description": "The 6-digit code emailed to the person (POST /sponsors/{key}/manage/codes)."
                  }
                },
                "required": [
                  "role"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageTeam"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`not_allowed`, `not_your_location`, `owner_only`: the role can't do that.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`already_member`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/team/requests/{requestId}/decline": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Decline a request to join",
        "operationId": "declineSponsorJoinRequest",
        "description": "",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The request to join."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageTeam"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/team/transfer": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Hand over ownership",
        "operationId": "offerSponsorOwnership",
        "description": "The owner offers the sponsor to one of its admins, confirmed with the emailed code; the admin has 7 days to accept. Publishes sponsor.ownership_offered.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "member_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "code": {
                    "type": "string",
                    "pattern": "^[0-9]{6}$",
                    "description": "The 6-digit code emailed to the person (POST /sponsors/{key}/manage/codes)."
                  }
                },
                "required": [
                  "member_id",
                  "code"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageTeam"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`owner_only`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`transfer_pending`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`not_an_admin`, `code_required`, `bad_code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Cancel the offer",
        "operationId": "cancelSponsorOwnershipOffer",
        "description": "The owner takes it back.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageTeam"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/team/transfer/accept": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Accept ownership",
        "operationId": "acceptSponsorOwnership",
        "description": "The admin it was offered to becomes the owner; the old owner becomes an admin. Publishes sponsor.ownership_transferred.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accepted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`expired`, `owner_changed`, `not_an_admin`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/team/transfer/decline": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Decline ownership",
        "operationId": "declineSponsorOwnership",
        "description": "",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "declined": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/devices": {
      "get": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Counter devices",
        "operationId": "listSponsorDevices",
        "description": "At the locations the person manages.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "devices": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SponsorManageDevice"
                      }
                    },
                    "code_ttl_minutes": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Add a counter device",
        "operationId": "addSponsorDevice",
        "description": "A device for one location, with a 6-digit pairing code shown once (10 minutes) and its QR. Confirmed with the emailed code (pair_device). Publishes sponsor.sensitive_action.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "location_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 60
                  },
                  "code": {
                    "type": "string",
                    "pattern": "^[0-9]{6}$",
                    "description": "The 6-digit code emailed to the person (POST /sponsors/{key}/manage/codes)."
                  }
                },
                "required": [
                  "location_id",
                  "name",
                  "code"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManagePairing"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`not_your_location`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`not_live`, `too_many_devices`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`code_required`, `online`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/devices/{deviceId}/code": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "A new pairing code",
        "operationId": "renewSponsorDevicePairingCode",
        "description": "For a device that has not paired; the old code stops working.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The counter device."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string",
                    "pattern": "^[0-9]{6}$",
                    "description": "The 6-digit code emailed to the person (POST /sponsors/{key}/manage/codes)."
                  }
                },
                "required": [
                  "code"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManagePairing"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`paired`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/devices/{deviceId}": {
      "patch": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Rename a device",
        "operationId": "renameSponsorDevice",
        "description": "",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The counter device."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageDevice"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Remove a device",
        "operationId": "removeSponsorDevice",
        "description": "It stops working at once; past perks used keep pointing at it.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          },
          {
            "name": "deviceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The counter device."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "removed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/stickers": {
      "get": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Stickers and badge",
        "operationId": "getSponsorStickers",
        "description": "Each location's kits, stickers and address confirmation, the formats, and the web badge's embed code.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageStickers"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/stickers/reorder": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Reorder stickers",
        "operationId": "reorderSponsorStickers",
        "description": "Replace lost or damaged stickers (their codes stop working now) or send extra ones. Free; three kits a location in 30 days.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "location_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "reason": {
                    "type": "string",
                    "enum": [
                      "lost",
                      "damaged",
                      "extra"
                    ]
                  },
                  "sticker_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "formats": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "door",
                        "round",
                        "counter"
                      ]
                    }
                  },
                  "ship_to_location_id": {
                    "type": "string",
                    "nullable": true
                  }
                },
                "required": [
                  "location_id",
                  "reason"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageStickers"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`not_live`, `location_closed`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "429": {
            "description": "`too_many_kits`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/settings": {
      "get": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Settings",
        "operationId": "getSponsorSettings",
        "description": "Contact details, the business details on record, pausing every perk and leaving FundlyHub.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageSettings"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Edit the contact details",
        "operationId": "patchSponsorSettings",
        "description": "",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contact_email": {
                    "type": "string",
                    "nullable": true
                  },
                  "phone": {
                    "type": "string",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageSettings"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/settings/pause": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Pause every perk",
        "operationId": "pauseAllSponsorPerks",
        "description": "Starts now and comes back on the date picked, up to 60 days out; while paused, moves the date. With `from` more than a minute ahead (up to 90 days), the pause is planned instead and the hourly sponsor run starts it on the day; pausing now drops a plan. Publishes sponsor.status_changed when a pause starts.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "until": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "from": {
                    "type": "string",
                    "format": "date-time",
                    "description": "When a planned pause starts; omitted (or now) pauses at once."
                  },
                  "message": {
                    "type": "string",
                    "nullable": true,
                    "description": "What givers see after the date (\"Perks paused until Jan 3 - back after the holidays\"), trimmed, up to 80 characters."
                  }
                },
                "required": [
                  "until"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageSettings"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`not_live`, `closing`, `already_paused` (a plan while paused).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`required`, `invalid`, `too_long`, `in_the_past`, `too_far` (a message over 80 characters is `too_long` on `message`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Turn perks back on",
        "operationId": "resumeAllSponsorPerks",
        "description": "Perks are back now; when they are not paused, calls off a planned pause.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageSettings"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`not_paused`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/settings/emails": {
      "patch": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "My team emails",
        "operationId": "patchSponsorTeamEmails",
        "description": "The viewer's own switches for the team emails (Weekly summary, A giver reports a perk, Online codes running low). Off stops the email; the bell still comes. Owner and admins.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "weekly_summary": {
                    "type": "boolean"
                  },
                  "reports": {
                    "type": "boolean"
                  },
                  "low_codes": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageSettings"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`not_a_member`: staff off the team have no team emails.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`invalid`: each switch is true or false.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/settings/leave": {
      "post": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Leave FundlyHub",
        "operationId": "leaveFundlyHubAsSponsor",
        "description": "The owner gives 14 days' notice, confirmed with the emailed code (leave) and the business's name typed out. Followers and recent givers are told today; every perk ends on the day. Publishes sponsor.status_changed.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "confirm_name": {
                    "type": "string"
                  },
                  "code": {
                    "type": "string",
                    "pattern": "^[0-9]{6}$",
                    "description": "The 6-digit code emailed to the person (POST /sponsors/{key}/manage/codes)."
                  }
                },
                "required": [
                  "confirm_name",
                  "code"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageSettings"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`owner_only`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`not_live`, `already_leaving`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`name_mismatch`, `code_required`, `bad_code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Sponsors · Workspace"
        ],
        "summary": "Stay on FundlyHub",
        "operationId": "cancelLeavingFundlyHub",
        "description": "Undo leaving before the day; nothing ends.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageSettings"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "`not_found`: no such sponsor, or not one the person is on the team of (a sponsor not live yet is its team's only).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "409": {
            "description": "`not_leaving`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/communities": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "List communities (the directory)",
        "operationId": "listCommunities",
        "description": "Active, listed communities. `q` (2 characters or more) matches name, city and about; `category` is a kind or `paid`. `counts` apply `q` and ignore `category`.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "paid",
                "city",
                "church",
                "diaspora",
                "families",
                "school",
                "workplace",
                "other"
              ],
              "default": "all"
            }
          },
          {
            "name": "offers_help",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "1"
              ]
            },
            "description": "Just the ones with help in Find help (#2423). Ignored while Resources are switched off. It narrows `counts` too."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "featured",
                "members",
                "impact",
                "new"
              ],
              "default": "featured"
            },
            "description": "`impact` ranks by Community impact, the figure on each card. `raised`, its old name, is still accepted."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 48,
              "default": 24
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CommunityCard"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/CommunityPage"
                    },
                    "counts": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Create a community",
        "operationId": "createCommunity",
        "description": "The caller becomes the owner. Co-leaders get invites with their role. `draft: true` keeps it visible to the owner only. Settings are audit-logged; `community.created` is published.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 80
                  },
                  "slug": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "city",
                      "church",
                      "diaspora",
                      "families",
                      "school",
                      "workplace",
                      "other"
                    ]
                  },
                  "city_text": {
                    "type": "string",
                    "nullable": true
                  },
                  "place_id": {
                    "type": "string",
                    "nullable": true
                  },
                  "languages": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "about": {
                    "type": "string",
                    "maxLength": 280,
                    "nullable": true
                  },
                  "links": {
                    "type": "array",
                    "maxItems": 8,
                    "description": "The community's links, in order (#2094). Same rules as PUT /communities/{key}/links.",
                    "items": {
                      "$ref": "#/components/schemas/CommunityLinkInput"
                    }
                  },
                  "guidelines": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "photo_url": {
                    "type": "string",
                    "nullable": true
                  },
                  "avatar_url": {
                    "type": "string",
                    "nullable": true
                  },
                  "photo_original_url": {
                    "type": "string",
                    "nullable": true
                  },
                  "photo_crop": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "avatar_crop": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "visibility": {
                    "type": "string",
                    "enum": [
                      "public",
                      "private"
                    ]
                  },
                  "listed": {
                    "type": "boolean"
                  },
                  "join_approval": {
                    "type": "string",
                    "enum": [
                      "none",
                      "leaders"
                    ]
                  },
                  "membership": {
                    "type": "string",
                    "enum": [
                      "free",
                      "paid"
                    ]
                  },
                  "price_cents": {
                    "type": "integer",
                    "nullable": true
                  },
                  "yearly_price_cents": {
                    "type": "integer",
                    "nullable": true
                  },
                  "perks": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "leaders_join_free": {
                    "type": "boolean"
                  },
                  "share_policy": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "leader_approval"
                    ]
                  },
                  "add_policy": {
                    "type": "string",
                    "enum": [
                      "leaders",
                      "members"
                    ]
                  },
                  "default_alert": {
                    "type": "string",
                    "enum": [
                      "instant",
                      "digest"
                    ]
                  },
                  "show_leaders": {
                    "type": "boolean"
                  },
                  "co_leaders": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "user_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "role": {
                          "type": "string",
                          "enum": [
                            "leader",
                            "volunteer"
                          ]
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "draft": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CommunityDetail"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "description": "Refused (see `code`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/top": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "Top communities this month",
        "operationId": "listTopCommunities",
        "description": "The current calendar month (UTC), ranked by Community impact in the month (the card's figure, over the month), new members, or Fundlies fully funded. `raised`, the old name of `impact`, is still accepted.",
        "parameters": [
          {
            "name": "metric",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "impact",
                "new_members",
                "funded"
              ],
              "default": "impact"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "community": {
                            "$ref": "#/components/schemas/CommunityCard"
                          },
                          "rank": {
                            "type": "integer"
                          },
                          "value": {
                            "type": "integer"
                          },
                          "fundlies_month": {
                            "type": "integer"
                          },
                          "funded_month": {
                            "type": "integer"
                          },
                          "month_impact_cents": {
                            "type": "integer",
                            "description": "With `metric=impact`. Community impact in the month."
                          },
                          "month_new_members": {
                            "type": "integer"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "month": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/slug-available": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "Check a community link",
        "operationId": "checkCommunitySlug",
        "description": "Whether `/communities/<slug>` is free, and a suggestion when it is not.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "slug": {
                          "type": "string"
                        },
                        "available": {
                          "type": "boolean"
                        },
                        "reason": {
                          "type": "string",
                          "enum": [
                            "taken",
                            "reserved",
                            "invalid"
                          ],
                          "nullable": true
                        },
                        "suggestion": {
                          "type": "string",
                          "nullable": true
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/form-rules": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "The community form's limits and choices",
        "operationId": "getCommunityFormRules",
        "description": "Every limit and option the owner's Create and Settings forms hold to (lengths, counts, the link cap, the co-leader cap, the plan's price limits and quick picks, and each setting's choices), read from the same constants the server validates with. The plan's limits are null on a build without paid communities.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "object",
                          "properties": {
                            "min": {
                              "type": "integer"
                            },
                            "max": {
                              "type": "integer"
                            }
                          }
                        },
                        "slug": {
                          "type": "object",
                          "properties": {
                            "min": {
                              "type": "integer"
                            },
                            "max": {
                              "type": "integer"
                            }
                          }
                        },
                        "city": {
                          "type": "object",
                          "properties": {
                            "max": {
                              "type": "integer"
                            }
                          }
                        },
                        "languages": {
                          "type": "object",
                          "properties": {
                            "max_items": {
                              "type": "integer"
                            },
                            "max_length": {
                              "type": "integer"
                            }
                          }
                        },
                        "about": {
                          "type": "object",
                          "properties": {
                            "max": {
                              "type": "integer"
                            }
                          }
                        },
                        "guidelines": {
                          "type": "object",
                          "properties": {
                            "max_items": {
                              "type": "integer"
                            },
                            "max_length": {
                              "type": "integer"
                            }
                          }
                        },
                        "links": {
                          "type": "object",
                          "properties": {
                            "max": {
                              "type": "integer"
                            },
                            "label_max": {
                              "type": "integer"
                            }
                          }
                        },
                        "co_leaders": {
                          "type": "object",
                          "properties": {
                            "max_leaders": {
                              "type": "integer"
                            },
                            "max_people": {
                              "type": "integer"
                            }
                          }
                        },
                        "owned_max": {
                          "type": "integer"
                        },
                        "perks": {
                          "type": "object",
                          "properties": {
                            "max_items": {
                              "type": "integer",
                              "nullable": true
                            },
                            "max_length": {
                              "type": "integer",
                              "nullable": true
                            }
                          }
                        },
                        "price": {
                          "type": "object",
                          "properties": {
                            "min_cents": {
                              "type": "integer",
                              "nullable": true
                            },
                            "max_cents": {
                              "type": "integer",
                              "nullable": true
                            },
                            "yearly_max_cents": {
                              "type": "integer",
                              "nullable": true
                            },
                            "presets_cents": {
                              "type": "array",
                              "items": {
                                "type": "integer"
                              }
                            },
                            "default_cents": {
                              "type": "integer"
                            },
                            "yearly_months": {
                              "type": "integer"
                            }
                          }
                        },
                        "processing_fee": {
                          "type": "object",
                          "description": "Card processing estimate from the payment service's fee policy; monetary values are in cents.",
                          "properties": {
                            "percentage": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1,
                              "exclusiveMaximum": true
                            },
                            "fixed_cents": {
                              "type": "integer",
                              "minimum": 0
                            }
                          }
                        },
                        "currency": {
                          "type": "string",
                          "nullable": true
                        },
                        "kinds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "visibilities": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "join_approvals": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "memberships": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "share_policies": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "add_policies": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "default_alerts": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "co_leader_roles": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/reach": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "Who would hear about a shared Fundly",
        "operationId": "getCommunityReach",
        "description": "For the share step: distinct people across up to 3 of the caller's communities (minus the caller), the overlap who hear once, and per community the instant and digest counts. Counts only.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "ids",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated community ids or slugs, at most 3."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer"
                        },
                        "overlap": {
                          "type": "integer"
                        },
                        "digest": {
                          "type": "integer"
                        },
                        "per": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "community_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "instant": {
                                "type": "integer"
                              },
                              "digest": {
                                "type": "integer"
                              }
                            },
                            "additionalProperties": true
                          }
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/home/featured-communities": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "Featured communities for the home page",
        "operationId": "listFeaturedCommunities",
        "description": "Staff-featured communities first, then the biggest.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 12,
              "default": 4
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CommunityCard"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/invites/{token}": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "Preview an invite",
        "operationId": "previewCommunityInvite",
        "description": "Works for a member's share link code and for an emailed invite token. Shows the community and who invited.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "An invite link code or an emailed invite token."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "kind": {
                          "type": "string",
                          "enum": [
                            "link",
                            "person"
                          ]
                        },
                        "community": {
                          "$ref": "#/components/schemas/CommunityCard"
                        },
                        "invited_by": {
                          "$ref": "#/components/schemas/CommunityPerson"
                        },
                        "role": {
                          "type": "string",
                          "enum": [
                            "owner",
                            "leader",
                            "volunteer",
                            "member"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "accepted",
                            "declined",
                            "cancelled",
                            "expired"
                          ]
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "requires_approval": {
                          "type": "boolean"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/invites/{token}/accept": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Accept an invite",
        "operationId": "acceptCommunityInvite",
        "description": "A share link joins (or requests, when approval applies); an emailed invite joins with its role. A paid community answers 402 for a member invite.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "An invite link code or an emailed invite token."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "active",
                            "requested"
                          ]
                        },
                        "community": {
                          "type": "object",
                          "properties": {
                            "slug": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "description": "Paid community: use the paid join",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Refused (see `code`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Invite expired or used",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/invites/{token}/decline": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Decline an invite",
        "operationId": "declineCommunityInvite",
        "description": "Turns down an emailed invite to a community for the signed-in caller: an invite that is still pending is marked declined (any other is left as it is), and the answer is `status: declined` with the community's `slug`. Only an emailed invite can be declined; an invite link's code, like an unknown token, answers `404` (`code: INVITE_INVALID`). An invite addressed to another account answers `403` (`code: NOT_YOUR_INVITE`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "An invite link code or an emailed invite token."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string"
                        },
                        "community": {
                          "type": "object",
                          "properties": {
                            "slug": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "Get a community",
        "operationId": "getCommunity",
        "description": "404 for a draft (except to its owner), a deleted community, or a hidden or suspended one (except to its members). A private community answers 200; its feed and members are gated.",
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CommunityDetail"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "tags": [
          "Communities"
        ],
        "summary": "Update a community",
        "operationId": "updateCommunity",
        "description": "Owner and leaders. Plan fields (membership, prices, perks, leaders_join_free) are owner only and follow the paid-membership rules. `publish: true` turns a draft live. Attribute CRUD: audit-logged, no event.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Any create field except `co_leaders`, `links` and `draft`, which it ignores: links change only through `PUT /communities/{key}/links`, and `publish: true` turns a draft live.",
                "properties": {
                  "publish": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CommunityDetail"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Refused (see `code`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Communities"
        ],
        "summary": "Delete a community",
        "operationId": "deleteCommunity",
        "description": "Owner only. A soft delete; 409 HAS_MONEY while the fund holds money or memberships are paying.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "boolean"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Refused (see `code`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/about": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "A community's About tab",
        "operationId": "getCommunityAbout",
        "description": "The community's About tab: its description, links, languages, guidelines, kind and city, visibility, how joining works (approval, and a paid membership's prices), when it was created, its stats and its team. Public, and a private community's About tab is readable too. A deleted community answers `404`, as do a draft (except to its owner) and a hidden or suspended community (except to its members).",
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "about": {
                          "type": "string",
                          "nullable": true
                        },
                        "languages": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "guidelines": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "city",
                            "church",
                            "diaspora",
                            "families",
                            "school",
                            "workplace",
                            "other"
                          ]
                        },
                        "city_text": {
                          "type": "string",
                          "nullable": true
                        },
                        "stats": {
                          "type": "object",
                          "additionalProperties": true
                        },
                        "team": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/feed": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "A community's feed",
        "operationId": "getCommunityFeed",
        "description": "Posts, the projection of community events (Fundlies posted, milestones, joins grouped per week, fund moves when the viewer can see the fund) and updates on Fundlies posted here, newest first. 403 MEMBERS_ONLY for non-members of a private community.",
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "before",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "`next_before` from the previous page."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CommunityFeedItem"
                      }
                    },
                    "next_before": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/fundlies": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "Fundlies posted in a community",
        "operationId": "listCommunityFundlies",
        "description": "Public, private communities included. Active = live and not fully funded; funded = raised at least the goal; ended = neither. `q` matches title, organizer name and city.",
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "funded",
                "ended"
              ],
              "default": "active"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "most_raised",
                "ending"
              ],
              "default": "newest"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 48,
              "default": 24
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CommunityFundly"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "counts": {
                      "type": "object",
                      "properties": {
                        "active": {
                          "type": "integer"
                        },
                        "funded": {
                          "type": "integer"
                        },
                        "ended": {
                          "type": "integer"
                        }
                      },
                      "additionalProperties": true
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/CommunityPage"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/members": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "A community's members",
        "operationId": "listCommunityMembers",
        "description": "The team first (owner, leaders, volunteers), then members, newest first; with show_leaders off and a viewer below leader, one list without roles. `q` matches public names; `total` is the match count.",
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "role",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "team",
                "leaders",
                "volunteers",
                "members"
              ]
            }
          },
          {
            "name": "filter",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "new_month"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 48
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CommunityMember"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "counts": {
                      "type": "object",
                      "properties": {
                        "all": {
                          "type": "integer"
                        },
                        "team": {
                          "type": "integer"
                        },
                        "leaders": {
                          "type": "integer"
                        },
                        "volunteers": {
                          "type": "integer"
                        },
                        "members": {
                          "type": "integer"
                        },
                        "new_month": {
                          "type": "integer"
                        }
                      },
                      "additionalProperties": true
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/CommunityPage"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Add people",
        "operationId": "addCommunityMembers",
        "description": "Adds where the person's setting allows it, otherwise sends an invite. Up to 50 adds and invites a day per person. Added people get one notification with a Leave action.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "user_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                },
                "required": [
                  "user_ids"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "added": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "invited": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "skipped": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "skipped_reasons": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    },
                    "remaining_today": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/alert-counts": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "Who hears a new Fundly",
        "operationId": "getCommunityAlertCounts",
        "description": "Owner, leaders and volunteers. Counts only; members' own settings stay private.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "instant": {
                          "type": "integer"
                        },
                        "digest": {
                          "type": "integer"
                        },
                        "off": {
                          "type": "integer"
                        },
                        "muted": {
                          "type": "integer"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/links": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "A community's links, for editing",
        "operationId": "getCommunityLinks",
        "description": "Owner and leaders. Every live link in order, with its Safe Browsing status (a flagged link is hidden from the page) and its clicks in the last 30 days.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CommunityEditableLink"
                      }
                    },
                    "max": {
                      "type": "integer",
                      "example": 8
                    }
                  },
                  "required": [
                    "data",
                    "max"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not the owner or a leader."
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "tags": [
          "Communities"
        ],
        "summary": "Replace a community's links",
        "operationId": "putCommunityLinks",
        "description": "Owner and leaders; a suspended community is read-only. The ordered list replaces the live one: a row with its id keeps it (and its clicks), a URL already live is matched to its row, a live link left out is deleted. The server normalizes, detects the platform, refuses duplicates and more than 8, and checks every new URL with Google Web Risk (Safe Browsing) (unreachable: saved unchecked and re-checked nightly). Audit-logged as community.links_updated; no domain event.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "links": {
                    "type": "array",
                    "maxItems": 8,
                    "items": {
                      "$ref": "#/components/schemas/CommunityLinkInput"
                    }
                  }
                },
                "required": [
                  "links"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The list as saved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CommunityEditableLink"
                      }
                    },
                    "max": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "data",
                    "max"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "A row was refused. details.index is the row; details.reason is empty, invalid, scheme, host, too_long, duplicate, max, label, unsafe (flagged by Safe Browsing) or removed (FundlyHub removed it).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "example": "VALIDATION_ERROR"
                    },
                    "details": {
                      "type": "object",
                      "properties": {
                        "index": {
                          "type": "integer"
                        },
                        "reason": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not the owner or a leader, or the community is suspended."
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/communities/{key}/links/{linkId}/click": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Count a click on a community link",
        "operationId": "postCommunityLinkClick",
        "description": "Public, rate-limited, sent as a beacon when someone opens a link. Adds one to today's count for the link; stores no user id. Always 204.",
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "linkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Counted, or ignored for an unknown, removed or flagged link."
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/report": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Report a community",
        "operationId": "reportCommunity",
        "description": "Signed in with a verified email. One report per person and community; a repeat report updates it. FundlyHub's Trust & Safety team reviews it.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string",
                    "enum": [
                      "spam",
                      "scam",
                      "harassment",
                      "inappropriate",
                      "other"
                    ]
                  },
                  "details": {
                    "type": "string",
                    "maxLength": 4000
                  },
                  "link_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "One of the community's links, when the report is about it."
                  }
                },
                "required": [
                  "reason"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Received.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The email is not verified yet."
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/communities/{key}/join": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Join a community",
        "operationId": "joinCommunity",
        "description": "One tap for a public community without approval; a request otherwise. A share link without approval (made by an owner or leader) joins directly. 402 PAYMENT_REQUIRED for a paid community; 403 REMOVED for a removed person.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "invite": {
                    "type": "string"
                  },
                  "via": {
                    "type": "string",
                    "enum": [
                      "qr",
                      "link",
                      "directory"
                    ]
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "active",
                            "requested"
                          ]
                        },
                        "viewer": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "description": "Paid community: use the paid join",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Refused (see `code`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/leave": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Leave a community",
        "operationId": "leaveCommunity",
        "description": "409 OWNER_MUST_TRANSFER for the owner; 409 PAID_MEMBERSHIP_ACTIVE while a paid membership runs (cancel it first).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "left": {
                          "type": "boolean"
                        },
                        "access_until": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Refused (see `code`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/requests": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "Join requests",
        "operationId": "listCommunityJoinRequests",
        "description": "The people waiting for approval to join, oldest request first (at most 200): each person's user id, public name, avatar, handle and profile link, when they asked, and whether they came through an invite (`via_invite`). Someone with a private profile or an inactive account is shown as \"A member\", with no picture or link. For the owner, leaders and volunteers; anyone else gets `403` (`code: FORBIDDEN`), as does everyone in a suspended community. An unknown community answers `404`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "user_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "avatar_url": {
                            "type": "string",
                            "nullable": true
                          },
                          "requested_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "via_invite": {
                            "type": "boolean"
                          }
                        },
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/requests/{userId}/approve": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Approve a join request",
        "operationId": "approveCommunityJoinRequest",
        "description": "Owner, leaders and volunteers. Publishes community.member_joined.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          },
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/requests/{userId}/deny": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Deny a join request",
        "operationId": "denyCommunityJoinRequest",
        "description": "Turns down `userId`'s request to join: the request is removed, and the answer is `status: denied`. For the owner, leaders and volunteers; anyone else gets `403` (`code: FORBIDDEN`), as does everyone in a suspended community. No pending request from that person answers `404`. `POST /communities/{key}/requests/{userId}/decline` does the same.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          },
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/requests/{userId}/decline": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Deny a join request (alias)",
        "operationId": "declineCommunityJoinRequest",
        "description": "An alias of `POST /communities/{key}/requests/{userId}/deny`, served by the same handler: it removes `userId`'s pending request to join and answers `status: denied`. For the owner, leaders and volunteers; anyone else gets `403`. No pending request from that person answers `404`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          },
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/me": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "My membership settings",
        "operationId": "getMyCommunityMembership",
        "description": "The caller's role and alert choice in this community.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": [
                            "owner",
                            "leader",
                            "volunteer",
                            "member"
                          ]
                        },
                        "status": {
                          "type": "string"
                        },
                        "alert_level": {
                          "type": "string",
                          "enum": [
                            "instant",
                            "digest",
                            "off"
                          ]
                        },
                        "channels": {
                          "type": "object",
                          "properties": {
                            "email": {
                              "type": "boolean"
                            },
                            "push": {
                              "type": "boolean"
                            },
                            "web": {
                              "type": "boolean"
                            }
                          },
                          "additionalProperties": true
                        },
                        "muted_until": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "pinned_home": {
                          "type": "boolean"
                        },
                        "joined_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "joined_via": {
                          "type": "string",
                          "nullable": true
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "tags": [
          "Communities"
        ],
        "summary": "Change my alerts here",
        "operationId": "updateMyCommunityMembership",
        "description": "Alert level, channels (an array or a partial object), mute (`mute_days` or `muted_until`, null unmutes) and pin to home.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "alert_level": {
                    "type": "string",
                    "enum": [
                      "instant",
                      "digest",
                      "off"
                    ]
                  },
                  "channels": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "mute_days": {
                    "type": "integer",
                    "enum": [
                      1,
                      7,
                      30,
                      90
                    ]
                  },
                  "muted_until": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  },
                  "pinned_home": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/people": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "Add people: search and suggestions",
        "operationId": "searchCommunityPeople",
        "description": "Names and handles of public profiles, or an exact email; with no `q`, people the caller knows. `state` says whether an Add adds them right away (their `community_add_policy`) or sends an invite.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "user_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "avatar_url": {
                            "type": "string",
                            "nullable": true
                          },
                          "handle": {
                            "type": "string",
                            "nullable": true
                          },
                          "city": {
                            "type": "string",
                            "nullable": true
                          },
                          "reason": {
                            "type": "string",
                            "nullable": true
                          },
                          "state": {
                            "type": "string",
                            "enum": [
                              "addable",
                              "invite_only",
                              "no_adds",
                              "member",
                              "invited",
                              "requested",
                              "removed"
                            ]
                          },
                          "invited_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "remaining_today": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/members/{userId}": {
      "patch": {
        "tags": [
          "Communities"
        ],
        "summary": "Change a member's role",
        "operationId": "changeCommunityMemberRole",
        "description": "Leaders change roles below leader; only the owner makes or unmakes leaders. 409 LEADER_LIMIT past 10 leaders, the owner included.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          },
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "role": {
                    "type": "string",
                    "enum": [
                      "leader",
                      "volunteer",
                      "member"
                    ]
                  }
                },
                "required": [
                  "role"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "user_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "role": {
                          "type": "string",
                          "enum": [
                            "owner",
                            "leader",
                            "volunteer",
                            "member"
                          ]
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Refused (see `code`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Communities"
        ],
        "summary": "Remove a member",
        "operationId": "removeCommunityMember",
        "description": "Owner and leaders; never the owner; a leader cannot remove a leader. A removed person cannot join again on their own; they come back only by accepting a personal invite addressed to them.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          },
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "removed": {
                          "type": "boolean"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/transfer": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Hand the community to a leader",
        "operationId": "transferCommunityOwnership",
        "description": "Owner only; the new owner must be an active leader. The old owner becomes a leader, or leaves with `leave: true`, which answers `{ \"data\": null }` (the caller is no longer in the community).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "user_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "leave": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "user_id"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "nullable": true,
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/CommunityDetail"
                        }
                      ],
                      "description": "The community as the caller now sees it, or `null` after `leave: true`."
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Refused (see `code`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/invites": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Invite people",
        "operationId": "createCommunityInvites",
        "description": "By email or account. Invites expire after 14 days. A volunteer role needs a leader; a leader role needs the owner.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "emails": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "user_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "member",
                      "volunteer",
                      "leader"
                    ]
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "invited": {
                          "type": "integer"
                        },
                        "invites": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        },
                        "skipped": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      },
                      "additionalProperties": true
                    },
                    "remaining_today": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "Pending invites",
        "operationId": "listCommunityInvites",
        "description": "Owner, leaders and volunteers. An address shows only for invites typed as an address.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "user_id": {
                            "type": "string",
                            "nullable": true
                          },
                          "name": {
                            "type": "string",
                            "nullable": true
                          },
                          "avatar_url": {
                            "type": "string",
                            "nullable": true
                          },
                          "email": {
                            "type": "string",
                            "nullable": true
                          },
                          "role": {
                            "type": "string",
                            "enum": [
                              "owner",
                              "leader",
                              "volunteer",
                              "member"
                            ]
                          },
                          "invited_by_name": {
                            "type": "string",
                            "nullable": true
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "expires_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "last_sent_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        },
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/invites/{inviteId}/resend": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Resend an invite",
        "operationId": "resendCommunityInvite",
        "description": "A fresh token and 14 more days; once a day.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          },
          {
            "name": "inviteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "resent": {
                          "type": "boolean"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Refused (see `code`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too soon",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/communities/{key}/invites/{inviteId}": {
      "delete": {
        "tags": [
          "Communities"
        ],
        "summary": "Cancel an invite",
        "operationId": "cancelCommunityInvite",
        "description": "Owner, leaders and volunteers, or whoever sent it.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          },
          {
            "name": "inviteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "cancelled": {
                          "type": "boolean"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/invite-link": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "My invite link",
        "operationId": "getCommunityInviteLink",
        "description": "Each member has their own link (`/communities/<slug>?invite=<token>`), so joins credit them.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "token": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "uses": {
                          "type": "integer"
                        },
                        "requires_approval": {
                          "type": "boolean"
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "tags": [
          "Communities"
        ],
        "summary": "Change my invite link",
        "operationId": "updateCommunityInviteLink",
        "description": "Owner and leaders: approval for each join, and an expiry.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "requires_approval": {
                    "type": "boolean"
                  },
                  "expires_in_days": {
                    "type": "integer",
                    "enum": [
                      1,
                      7,
                      30,
                      90
                    ],
                    "nullable": true
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/invite-link/rotate": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Replace my invite link",
        "operationId": "rotateCommunityInviteLink",
        "description": "Cancels the caller's own invite link for this community and issues one with a new code; the old code no longer works as an invite (its preview says `cancelled`). Answers the new link: `token`, `url`, `uses` back at 0, `requires_approval` and `expires_at`. The new link has no expiry, and an owner's or leader's link starts without the approval step, so set them again with `PATCH /communities/{key}/invite-link`. Any active member may rotate their own link; anyone else, and everyone in a suspended community, gets `403`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/posts": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Post to a community",
        "operationId": "createCommunityPost",
        "description": "Owner, leaders and volunteers; pinning needs owner or leader, and unpins the previous post. A \"Tell your members\" post (CM-07) names one of the community's own live resources in `resource_id` (owner and leaders only; 400 `VALIDATION_ERROR` with `details.field = resource_id` otherwise), and the feed shows the help's card under the post while the viewer may see it.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 2000
                  },
                  "pinned": {
                    "type": "boolean"
                  },
                  "resource_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "The community's own live resource this post tells members about."
                  }
                },
                "required": [
                  "body"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/posts/{postId}": {
      "patch": {
        "tags": [
          "Communities"
        ],
        "summary": "Edit or pin a post",
        "operationId": "updateCommunityPost",
        "description": "Edits a post's `body` (1 to 2000 characters) or pins or unpins it (`pinned`), and answers the post. The author may edit their own post while they can still post here (as an active volunteer, leader or owner); the owner and leaders may edit any post, and only they pin. One post is pinned at a time: pinning this one unpins the others. A post that is not in this community, or was deleted, answers `404`; a caller who may not make the change gets `403`, and a bad value `400` (`code: VALIDATION_ERROR`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          },
          {
            "name": "postId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string"
                  },
                  "pinned": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Communities"
        ],
        "summary": "Delete a post",
        "operationId": "deleteCommunityPost",
        "description": "Takes a post off the community's feed (a pinned post is unpinned) and answers `deleted: true`. The author may delete their own post while they can still post here (as an active volunteer, leader or owner); the owner and leaders may delete any post. Anyone else gets `403`. A post that is not in this community, or was already deleted, answers `404`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          },
          {
            "name": "postId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "deleted": {
                          "type": "boolean"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/me/communities/shareable": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "Communities I can share a Fundly to",
        "operationId": "listShareableCommunities",
        "description": "The caller's active communities, with this Fundly's share state when `fundraiser_id` is given (it may not exist yet).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "fundraiser_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CommunityCard"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/fundraisers/{id}/communities": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "A Fundly's community shares",
        "operationId": "getFundraiserCommunityShares",
        "description": "The organizer's view of where the Fundly is shared and what each share waits for.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The fundraiser id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "community_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "posted",
                              "rejected"
                            ]
                          },
                          "primary": {
                            "type": "boolean"
                          },
                          "awaiting": {
                            "type": "string",
                            "enum": [
                              "leader_approval",
                              "verification"
                            ],
                            "nullable": true
                          }
                        },
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "tags": [
          "Communities"
        ],
        "summary": "Share a Fundly to communities",
        "operationId": "setFundraiserCommunityShares",
        "description": "At most 3, exactly one primary; `[]` removes every share. A share posts only after the Fundly passes verification and, under leader approval, a leader approves; community.fundly_posted fires then.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The fundraiser id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "communities": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "community_id": {
                          "type": "string"
                        },
                        "primary": {
                          "type": "boolean"
                        }
                      },
                      "additionalProperties": true
                    }
                  }
                },
                "required": [
                  "communities"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/pending-fundlies": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "Fundlies waiting for approval",
        "operationId": "listPendingCommunityFundlies",
        "description": "Owner and leaders: shares waiting under leader approval.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "fundraiser": {
                            "$ref": "#/components/schemas/CommunityFundly"
                          },
                          "shared_by": {
                            "$ref": "#/components/schemas/CommunityPerson"
                          },
                          "shared_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "verified": {
                            "type": "boolean"
                          }
                        },
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/fundlies/{fundraiserId}/approve": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Approve a shared Fundly",
        "operationId": "approveCommunityFundly",
        "description": "Owner and leaders. Posts it now if it passed verification.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          },
          {
            "name": "fundraiserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "posted"
                          ]
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{key}/fundlies/{fundraiserId}/reject": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Reject a shared Fundly",
        "operationId": "rejectCommunityFundly",
        "description": "Turns down a Fundly shared to this community that is waiting for approval (the list is `GET /communities/{key}/pending-fundlies`): it is not posted, and the answer is `status: rejected`. For the owner and leaders; anyone else gets `403`, as does everyone in a suspended community. A Fundly with no share waiting here answers `404`. If this was the Fundly's primary community, another of its live shares becomes primary, a posted one before a pending one.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's slug or uuid."
          },
          {
            "name": "fundraiserId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/me/communities": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "My communities",
        "operationId": "listMyCommunities",
        "description": "Pinned first, then by role and name, with my alert choice and any paid membership.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CommunityCard"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/me/community-settings": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "My community settings",
        "operationId": "getMyCommunitySettings",
        "description": "Who can add me, quiet hours, profile and leaderboard visibility, timezone.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "add_policy": {
                          "type": "string",
                          "enum": [
                            "anyone",
                            "follows_and_shared",
                            "nobody"
                          ]
                        },
                        "quiet_hours": {
                          "type": "object",
                          "properties": {
                            "enabled": {
                              "type": "boolean"
                            },
                            "start": {
                              "type": "string"
                            },
                            "end": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": true
                        },
                        "show_on_profile": {
                          "type": "boolean"
                        },
                        "show_on_leaderboards": {
                          "type": "boolean"
                        },
                        "timezone": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "tags": [
          "Communities"
        ],
        "summary": "Change my community settings",
        "operationId": "updateMyCommunitySettings",
        "description": "Partial. Quiet hours are 10pm to 7am local; only `enabled` is stored.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "add_policy": {
                    "type": "string"
                  },
                  "quiet_hours": {
                    "type": "object",
                    "properties": {
                      "enabled": {
                        "type": "boolean"
                      }
                    },
                    "additionalProperties": true
                  },
                  "show_on_profile": {
                    "type": "boolean"
                  },
                  "show_on_leaderboards": {
                    "type": "boolean"
                  },
                  "timezone": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "tags": [
          "Communities"
        ],
        "summary": "Change my community settings (PUT)",
        "operationId": "putMyCommunitySettings",
        "description": "The same as `PATCH /me/community-settings` (one handler serves both): only the fields sent change. `add_policy` is who may add you to a community directly (`anyone`; `follows_and_shared`, the default: people you follow and people in your communities; or `nobody`), and any other add becomes an invite. `quiet_hours` takes `{ enabled }`, `show_on_profile` and `show_on_leaderboards` are true or false, and `timezone` is an IANA time zone. A bad value answers `400` (`code: VALIDATION_ERROR`, with `field`); otherwise the answer is all of the caller's community settings.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "add_policy": {
                    "type": "string"
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/users/{id}/communities": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "A person's communities",
        "operationId": "listUserCommunities",
        "description": "For the profile. Empty when the person turned it off; private communities show only to viewers who are members too.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Profile uuid or handle."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CommunityCard"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/unsubscribe/one-click": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "One-click unsubscribe (RFC 8058)",
        "operationId": "unsubscribeOneClick",
        "description": "The List-Unsubscribe-Post target mailbox providers call. The signed token names one address and one scope (the email's category); that one suppression is written at once.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "The signed unsubscribe token from the List-Unsubscribe header."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "scope": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{id}/stripe/onboarding": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Connect the community's Stripe account",
        "operationId": "startCommunityStripeOnboarding",
        "description": "Owner only. Creates (or reuses) the community's own Stripe Express account, which the owner verifies, and returns a fresh Stripe-hosted onboarding link that returns to the community's settings. `accept_debit_terms: true` records the owner's consent to Stripe Account Debits, which giving from the fund to a Fundly needs. Requires a signed-in session.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "accept_debit_terms": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string"
                        },
                        "account_id": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/communities/{id}/stripe/status": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "The community's Stripe account status",
        "operationId": "getCommunityStripeStatus",
        "description": "Owner and leaders. Read live from Stripe (the stored row when Stripe is unreachable).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "connected": {
                          "type": "boolean"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "not_connected",
                            "pending",
                            "restricted",
                            "active"
                          ]
                        },
                        "account_id": {
                          "type": "string",
                          "nullable": true
                        },
                        "charges_enabled": {
                          "type": "boolean"
                        },
                        "payouts_enabled": {
                          "type": "boolean"
                        },
                        "details_submitted": {
                          "type": "boolean"
                        },
                        "requirements_due": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "bank_name": {
                          "type": "string",
                          "nullable": true
                        },
                        "last4": {
                          "type": "string",
                          "nullable": true
                        },
                        "payout_schedule": {
                          "type": "string",
                          "enum": [
                            "weekly",
                            "manual"
                          ]
                        },
                        "debit_consent": {
                          "type": "boolean"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/communities/{id}/stripe/dashboard-link": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Open the community's Stripe dashboard",
        "operationId": "createCommunityStripeDashboardLink",
        "description": "Owner only: a one-time Stripe Express dashboard login link (bank account, payouts).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Refused (see `code`)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/communities/{id}/membership": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "The paid membership plan",
        "operationId": "getCommunityMembershipPlan",
        "description": "Public. The monthly and yearly price, perks, who receives the dues (named even when leaders are hidden), a price change serving its 30 days of notice, the card fee preview (FundlyHub keeps 0%), and that dues are not tax-deductible.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "membership": {
                          "type": "string",
                          "enum": [
                            "free",
                            "paid"
                          ]
                        },
                        "price_cents": {
                          "type": "integer",
                          "nullable": true
                        },
                        "yearly_price_cents": {
                          "type": "integer",
                          "nullable": true
                        },
                        "currency": {
                          "type": "string",
                          "enum": [
                            "usd"
                          ]
                        },
                        "perks": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "leaders_join_free": {
                          "type": "boolean"
                        },
                        "payee_name": {
                          "type": "string"
                        },
                        "pending_change": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "price_cents": {
                              "type": "integer",
                              "nullable": true
                            },
                            "yearly_price_cents": {
                              "type": "integer",
                              "nullable": true
                            },
                            "effective_at": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        },
                        "accepting_payments": {
                          "type": "boolean"
                        },
                        "fee_preview": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "gross_cents": {
                              "type": "integer"
                            },
                            "card_fee_cents": {
                              "type": "integer"
                            },
                            "fundlyhub_fee_cents": {
                              "type": "integer"
                            },
                            "net_cents": {
                              "type": "integer"
                            }
                          }
                        },
                        "tax_note": {
                          "type": "string",
                          "enum": [
                            "not_tax_deductible"
                          ]
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "tags": [
          "Communities"
        ],
        "summary": "Change the paid membership plan",
        "operationId": "updateCommunityMembershipPlan",
        "description": "Owner only. A price change with paying members is scheduled: every paying member is emailed and moves to the new price at their first renewal 30 days or more after the notice; new joiners pay it at once. Paid to free cancels every subscription at period end. Audit-logged, no event.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "membership": {
                    "type": "string",
                    "enum": [
                      "free",
                      "paid"
                    ]
                  },
                  "price_cents": {
                    "type": "integer",
                    "minimum": 100,
                    "maximum": 100000
                  },
                  "yearly_price_cents": {
                    "type": "integer",
                    "nullable": true,
                    "minimum": 100,
                    "maximum": 1000000
                  },
                  "perks": {
                    "type": "array",
                    "maxItems": 8,
                    "items": {
                      "type": "string",
                      "maxLength": 120
                    }
                  },
                  "leaders_join_free": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "membership": {
                          "type": "string",
                          "enum": [
                            "free",
                            "paid"
                          ]
                        },
                        "price_cents": {
                          "type": "integer",
                          "nullable": true
                        },
                        "yearly_price_cents": {
                          "type": "integer",
                          "nullable": true
                        },
                        "currency": {
                          "type": "string",
                          "enum": [
                            "usd"
                          ]
                        },
                        "perks": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "leaders_join_free": {
                          "type": "boolean"
                        },
                        "payee_name": {
                          "type": "string"
                        },
                        "pending_change": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "price_cents": {
                              "type": "integer",
                              "nullable": true
                            },
                            "yearly_price_cents": {
                              "type": "integer",
                              "nullable": true
                            },
                            "effective_at": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        },
                        "accepting_payments": {
                          "type": "boolean"
                        },
                        "fee_preview": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "gross_cents": {
                              "type": "integer"
                            },
                            "card_fee_cents": {
                              "type": "integer"
                            },
                            "fundlyhub_fee_cents": {
                              "type": "integer"
                            },
                            "net_cents": {
                              "type": "integer"
                            }
                          }
                        },
                        "tax_note": {
                          "type": "string",
                          "enum": [
                            "not_tax_deductible"
                          ]
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/communities/{id}/membership/me": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "My paid membership in a community",
        "operationId": "getMyPaidCommunityMembership",
        "description": "The signed-in person's paid membership: status, price, renewal, card, and the client secret of an open invoice while payment is needed.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "nullable": true
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "none",
                            "pending_approval",
                            "incomplete",
                            "active",
                            "trialing",
                            "past_due",
                            "unpaid",
                            "canceled",
                            "incomplete_expired"
                          ]
                        },
                        "interval": {
                          "type": "string",
                          "enum": [
                            "month",
                            "year"
                          ],
                          "nullable": true
                        },
                        "amount_cents": {
                          "type": "integer",
                          "nullable": true
                        },
                        "current_period_end": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "cancel_at_period_end": {
                          "type": "boolean"
                        },
                        "access_until": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "card": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "brand": {
                              "type": "string"
                            },
                            "last4": {
                              "type": "string"
                            }
                          }
                        },
                        "client_secret": {
                          "type": "string",
                          "nullable": true,
                          "description": "Only while status is incomplete: confirm the open invoice."
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/communities/{id}/join/paid": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Join a paid community",
        "operationId": "joinPaidCommunity",
        "description": "With approval (leaders approve, or a private community): creates the join request and returns a SetupIntent `client_secret` (`intent_type: setup`) to save the card. Nothing is charged until a leader approves; then the subscription is created and the saved card charged. Without approval: returns the first invoice's PaymentIntent secret (`intent_type: payment`); the member is in once it is paid. Dues go to the community's own Stripe account; FundlyHub keeps 0%. Dues are not donations and are not tax-deductible.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "interval": {
                    "type": "string",
                    "enum": [
                      "month",
                      "year"
                    ],
                    "default": "month",
                    "description": "How often the membership bills; `month` when left out."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "requested",
                            "payment_required",
                            "active"
                          ]
                        },
                        "intent_type": {
                          "type": "string",
                          "enum": [
                            "setup",
                            "payment"
                          ],
                          "nullable": true
                        },
                        "client_secret": {
                          "type": "string",
                          "nullable": true
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "REMOVED: only a leader's invite brings a removed person back",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "NOT_PAID_COMMUNITY, PAYMENTS_NOT_READY, ALREADY_MEMBER, INTERVAL_UNAVAILABLE, MEMBERSHIP_CANCELED (the membership was cancelled while its subscription was being set up, e.g. by the member's account deletion; nothing keeps charging)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/communities/{id}/membership/cancel": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Cancel a paid membership (leave)",
        "operationId": "cancelCommunityMembership",
        "description": "Cancels at the end of the paid period: access lasts until `access_until`, no further charge, then the member leaves. A membership never charged (waiting for approval) ends at once.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "access_until": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/communities/{id}/membership/resume": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Undo a cancellation",
        "operationId": "resumeCommunityMembership",
        "description": "Before the period ends, keeps the membership renewing.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "nullable": true
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "none",
                            "pending_approval",
                            "incomplete",
                            "active",
                            "trialing",
                            "past_due",
                            "unpaid",
                            "canceled",
                            "incomplete_expired"
                          ]
                        },
                        "interval": {
                          "type": "string",
                          "enum": [
                            "month",
                            "year"
                          ],
                          "nullable": true
                        },
                        "amount_cents": {
                          "type": "integer",
                          "nullable": true
                        },
                        "current_period_end": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "cancel_at_period_end": {
                          "type": "boolean"
                        },
                        "access_until": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "card": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "brand": {
                              "type": "string"
                            },
                            "last4": {
                              "type": "string"
                            }
                          }
                        },
                        "client_secret": {
                          "type": "string",
                          "nullable": true,
                          "description": "Only while status is incomplete: confirm the open invoice."
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Refused (see `code`)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/me/community-memberships": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "My paid community memberships",
        "operationId": "listMyCommunityMemberships",
        "description": "Every live paid membership of the signed-in person, for Settings: price, renewal, card. Dues are not tax-deductible.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "community": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "slug": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "avatar_url": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "additionalProperties": true
                          },
                          "status": {
                            "type": "string"
                          },
                          "interval": {
                            "type": "string",
                            "nullable": true
                          },
                          "amount_cents": {
                            "type": "integer",
                            "nullable": true
                          },
                          "current_period_end": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "cancel_at_period_end": {
                            "type": "boolean"
                          },
                          "tax_note": {
                            "type": "string"
                          }
                        },
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/me/community-memberships/{membershipId}/invoices": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "Receipts for a paid membership",
        "operationId": "listMyCommunityMembershipInvoices",
        "description": "The membership's paid and open Stripe invoices with their hosted and PDF links.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "membershipId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "number": {
                            "type": "string",
                            "nullable": true
                          },
                          "amount_paid_cents": {
                            "type": "integer"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "hosted_invoice_url": {
                            "type": "string",
                            "nullable": true
                          },
                          "pdf_url": {
                            "type": "string",
                            "nullable": true
                          }
                        },
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/communities/{id}/fund": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "The community fund",
        "operationId": "getCommunityFund",
        "description": "Visibility applies: `public` anyone; `members` paying members, the owner and leaders; `private` the owner and leaders. A viewer who cannot see the fund gets 200 with `viewer` and the settings only. Dues are one row a month; an anonymous giver is named to leaders only. `payout_account` is for the owner and leaders, `hold` for the owner.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "community_id": {
                          "type": "string"
                        },
                        "enabled": {
                          "type": "boolean"
                        },
                        "visibility": {
                          "type": "string",
                          "enum": [
                            "public",
                            "members",
                            "private"
                          ]
                        },
                        "accept_gifts": {
                          "type": "boolean"
                        },
                        "viewer": {
                          "type": "object",
                          "properties": {
                            "can_see": {
                              "type": "boolean"
                            },
                            "can_move_money": {
                              "type": "boolean"
                            },
                            "is_leader": {
                              "type": "boolean"
                            },
                            "can_give": {
                              "type": "boolean"
                            }
                          },
                          "additionalProperties": true
                        },
                        "balance": {
                          "type": "object",
                          "properties": {
                            "available_cents": {
                              "type": "integer"
                            },
                            "pending_cents": {
                              "type": "integer"
                            },
                            "pending_available_on": {
                              "type": "string",
                              "format": "date-time",
                              "nullable": true
                            },
                            "spendable_cents": {
                              "type": "integer"
                            },
                            "open_disputes_cents": {
                              "type": "integer"
                            }
                          },
                          "additionalProperties": true
                        },
                        "totals": {
                          "type": "object",
                          "properties": {
                            "raised_cents": {
                              "type": "integer"
                            },
                            "dues_cents": {
                              "type": "integer"
                            },
                            "gifts_cents": {
                              "type": "integer"
                            },
                            "given_cents": {
                              "type": "integer"
                            },
                            "withdrawn_cents": {
                              "type": "integer"
                            },
                            "since": {
                              "type": "string",
                              "format": "date-time",
                              "nullable": true
                            }
                          },
                          "additionalProperties": true
                        },
                        "given_to": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "fundraiser_id": {
                                "type": "string"
                              },
                              "slug": {
                                "type": "string"
                              },
                              "title": {
                                "type": "string"
                              },
                              "organizer_name": {
                                "type": "string",
                                "nullable": true
                              },
                              "image_url": {
                                "type": "string",
                                "nullable": true
                              },
                              "raised_cents": {
                                "type": "integer"
                              },
                              "from_fund_cents": {
                                "type": "integer"
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "entries": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "dues",
                                  "gift",
                                  "allocation",
                                  "withdrawal",
                                  "refund",
                                  "dispute",
                                  "auto_payout",
                                  "adjustment"
                                ]
                              },
                              "amount_cents": {
                                "type": "integer",
                                "description": "Signed, net of card fees."
                              },
                              "gross_cents": {
                                "type": "integer",
                                "nullable": true
                              },
                              "created_at": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "available_on": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                              },
                              "fundraiser": {
                                "type": "object",
                                "nullable": true,
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "slug": {
                                    "type": "string",
                                    "nullable": true
                                  },
                                  "title": {
                                    "type": "string",
                                    "nullable": true
                                  },
                                  "organizer_name": {
                                    "type": "string",
                                    "nullable": true
                                  }
                                }
                              },
                              "to_leader_fundly": {
                                "type": "boolean"
                              },
                              "donor_name": {
                                "type": "string",
                                "nullable": true,
                                "description": "Null for an anonymous gift unless the viewer is a leader."
                              },
                              "anonymous": {
                                "type": "boolean"
                              },
                              "note": {
                                "type": "string",
                                "nullable": true
                              },
                              "reason": {
                                "type": "string",
                                "nullable": true
                              },
                              "actor_name": {
                                "type": "string",
                                "nullable": true
                              },
                              "member_count": {
                                "type": "integer",
                                "nullable": true,
                                "description": "Dues rows only: paying members that month."
                              },
                              "period": {
                                "type": "string",
                                "nullable": true,
                                "description": "Dues rows only, YYYY-MM. Dues are one row a month, never per member."
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "entries_total": {
                          "type": "integer"
                        },
                        "payout_account": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "bank_name": {
                              "type": "string",
                              "nullable": true
                            },
                            "last4": {
                              "type": "string",
                              "nullable": true
                            }
                          }
                        },
                        "open_dispute": {
                          "type": "boolean"
                        },
                        "negative_balance": {
                          "type": "boolean"
                        },
                        "hold": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "limit_days": {
                              "type": "integer"
                            },
                            "next_auto_payout_on": {
                              "type": "string",
                              "format": "date-time",
                              "nullable": true
                            },
                            "next_auto_payout_cents": {
                              "type": "integer"
                            }
                          }
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "tags": [
          "Communities"
        ],
        "summary": "Fund settings",
        "operationId": "updateCommunityFund",
        "description": "Owner only. On: the account pays out manually and the money collects; off: weekly payouts. Visibility changes are audit-logged (no event) and hide past activity too. `accept_debit_terms: true` records the Account Debit consent.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  },
                  "visibility": {
                    "type": "string",
                    "enum": [
                      "public",
                      "members",
                      "private"
                    ]
                  },
                  "accept_gifts": {
                    "type": "boolean"
                  },
                  "accept_debit_terms": {
                    "type": "boolean",
                    "enum": [
                      true
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "community_id": {
                          "type": "string"
                        },
                        "enabled": {
                          "type": "boolean"
                        },
                        "visibility": {
                          "type": "string",
                          "enum": [
                            "public",
                            "members",
                            "private"
                          ]
                        },
                        "accept_gifts": {
                          "type": "boolean"
                        },
                        "viewer": {
                          "type": "object",
                          "properties": {
                            "can_see": {
                              "type": "boolean"
                            },
                            "can_move_money": {
                              "type": "boolean"
                            },
                            "is_leader": {
                              "type": "boolean"
                            },
                            "can_give": {
                              "type": "boolean"
                            }
                          },
                          "additionalProperties": true
                        },
                        "balance": {
                          "type": "object",
                          "properties": {
                            "available_cents": {
                              "type": "integer"
                            },
                            "pending_cents": {
                              "type": "integer"
                            },
                            "pending_available_on": {
                              "type": "string",
                              "format": "date-time",
                              "nullable": true
                            },
                            "spendable_cents": {
                              "type": "integer"
                            },
                            "open_disputes_cents": {
                              "type": "integer"
                            }
                          },
                          "additionalProperties": true
                        },
                        "totals": {
                          "type": "object",
                          "properties": {
                            "raised_cents": {
                              "type": "integer"
                            },
                            "dues_cents": {
                              "type": "integer"
                            },
                            "gifts_cents": {
                              "type": "integer"
                            },
                            "given_cents": {
                              "type": "integer"
                            },
                            "withdrawn_cents": {
                              "type": "integer"
                            },
                            "since": {
                              "type": "string",
                              "format": "date-time",
                              "nullable": true
                            }
                          },
                          "additionalProperties": true
                        },
                        "given_to": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "fundraiser_id": {
                                "type": "string"
                              },
                              "slug": {
                                "type": "string"
                              },
                              "title": {
                                "type": "string"
                              },
                              "organizer_name": {
                                "type": "string",
                                "nullable": true
                              },
                              "image_url": {
                                "type": "string",
                                "nullable": true
                              },
                              "raised_cents": {
                                "type": "integer"
                              },
                              "from_fund_cents": {
                                "type": "integer"
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "entries": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "dues",
                                  "gift",
                                  "allocation",
                                  "withdrawal",
                                  "refund",
                                  "dispute",
                                  "auto_payout",
                                  "adjustment"
                                ]
                              },
                              "amount_cents": {
                                "type": "integer",
                                "description": "Signed, net of card fees."
                              },
                              "gross_cents": {
                                "type": "integer",
                                "nullable": true
                              },
                              "created_at": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "available_on": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                              },
                              "fundraiser": {
                                "type": "object",
                                "nullable": true,
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "slug": {
                                    "type": "string",
                                    "nullable": true
                                  },
                                  "title": {
                                    "type": "string",
                                    "nullable": true
                                  },
                                  "organizer_name": {
                                    "type": "string",
                                    "nullable": true
                                  }
                                }
                              },
                              "to_leader_fundly": {
                                "type": "boolean"
                              },
                              "donor_name": {
                                "type": "string",
                                "nullable": true,
                                "description": "Null for an anonymous gift unless the viewer is a leader."
                              },
                              "anonymous": {
                                "type": "boolean"
                              },
                              "note": {
                                "type": "string",
                                "nullable": true
                              },
                              "reason": {
                                "type": "string",
                                "nullable": true
                              },
                              "actor_name": {
                                "type": "string",
                                "nullable": true
                              },
                              "member_count": {
                                "type": "integer",
                                "nullable": true,
                                "description": "Dues rows only: paying members that month."
                              },
                              "period": {
                                "type": "string",
                                "nullable": true,
                                "description": "Dues rows only, YYYY-MM. Dues are one row a month, never per member."
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "entries_total": {
                          "type": "integer"
                        },
                        "payout_account": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "bank_name": {
                              "type": "string",
                              "nullable": true
                            },
                            "last4": {
                              "type": "string",
                              "nullable": true
                            }
                          }
                        },
                        "open_dispute": {
                          "type": "boolean"
                        },
                        "negative_balance": {
                          "type": "boolean"
                        },
                        "hold": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "limit_days": {
                              "type": "integer"
                            },
                            "next_auto_payout_on": {
                              "type": "string",
                              "format": "date-time",
                              "nullable": true
                            },
                            "next_auto_payout_cents": {
                              "type": "integer"
                            }
                          }
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Refused (see `code`)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/communities/{id}/fund/entries": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "The fund activity, paged",
        "operationId": "listCommunityFundEntries",
        "description": "The fund's activity, newest first: `limit` entries (1 to 100, default 20) from `offset`, with `total` for paging. Visible as the fund is (see `GET /communities/{id}/fund`): `public` to anyone, `members` to paying members, the owner and leaders, `private` to the owner and leaders, and a fund that is switched off to the owner and leaders only. An unknown community answers `404`; anyone else who may not see the fund gets `403` (`code: FUND_HIDDEN`). Dues are one row a month (`period`, `member_count`); an anonymous giver is named to the owner and leaders only, and the team member behind an entry (`actor_name`) only when the community shows its leaders or the caller is the owner or a leader.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "entries": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "dues",
                                  "gift",
                                  "allocation",
                                  "withdrawal",
                                  "refund",
                                  "dispute",
                                  "auto_payout",
                                  "adjustment"
                                ]
                              },
                              "amount_cents": {
                                "type": "integer",
                                "description": "Signed, net of card fees."
                              },
                              "gross_cents": {
                                "type": "integer",
                                "nullable": true
                              },
                              "created_at": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "available_on": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                              },
                              "fundraiser": {
                                "type": "object",
                                "nullable": true,
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "slug": {
                                    "type": "string",
                                    "nullable": true
                                  },
                                  "title": {
                                    "type": "string",
                                    "nullable": true
                                  },
                                  "organizer_name": {
                                    "type": "string",
                                    "nullable": true
                                  }
                                }
                              },
                              "to_leader_fundly": {
                                "type": "boolean"
                              },
                              "donor_name": {
                                "type": "string",
                                "nullable": true,
                                "description": "Null for an anonymous gift unless the viewer is a leader."
                              },
                              "anonymous": {
                                "type": "boolean"
                              },
                              "note": {
                                "type": "string",
                                "nullable": true
                              },
                              "reason": {
                                "type": "string",
                                "nullable": true
                              },
                              "actor_name": {
                                "type": "string",
                                "nullable": true
                              },
                              "member_count": {
                                "type": "integer",
                                "nullable": true,
                                "description": "Dues rows only: paying members that month."
                              },
                              "period": {
                                "type": "string",
                                "nullable": true,
                                "description": "Dues rows only, YYYY-MM. Dues are one row a month, never per member."
                              }
                            },
                            "additionalProperties": true
                          }
                        },
                        "total": {
                          "type": "integer"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{id}/fund/entries.csv": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "Export the fund activity (CSV)",
        "operationId": "exportCommunityFundEntries",
        "description": "Owner and leaders. Every entry, givers named, dues by month.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          }
        ],
        "responses": {
          "200": {
            "description": "CSV",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/communities/{id}/fund/gifts": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Give once to the community fund",
        "operationId": "createCommunityFundGift",
        "description": "Anyone, guests included (a guest gives `donor_email`). A destination charge to the community's own Stripe account: the card fee comes out, FundlyHub keeps 0%. A gift to the fund is not a donation to a Fundly and is not tax-deductible. Confirm the returned PaymentIntent with Stripe Elements. Needs the same reCAPTCHA token as a donation's payment intent (`recaptcha_token` or `x-recaptcha-token`; signed-in verified users are exempt).",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amount_cents": {
                    "type": "integer",
                    "minimum": 100,
                    "maximum": 10000000
                  },
                  "note": {
                    "type": "string",
                    "maxLength": 280
                  },
                  "anonymous": {
                    "type": "boolean"
                  },
                  "donor_name": {
                    "type": "string"
                  },
                  "donor_email": {
                    "type": "string",
                    "format": "email"
                  },
                  "recaptcha_token": {
                    "type": "string"
                  }
                },
                "required": [
                  "amount_cents"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "client_secret": {
                          "type": "string"
                        },
                        "payment_intent_id": {
                          "type": "string"
                        },
                        "fee_cents": {
                          "type": "integer"
                        },
                        "net_cents": {
                          "type": "integer"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Refused (see `code`)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{id}/fund/allocation-check": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "Can the fund give to this Fundly?",
        "operationId": "checkCommunityFundAllocation",
        "description": "Owner only. Why not, when not: own_fundly (the owner organizes, co-organizes or is the beneficiary of the Fundly), dispute_open, negative_balance, fund_disabled, fundraiser_not_accepting, recipient_unavailable (the Fundly's beneficiary cannot take the gift now: a nonprofit without a ready payout account, or a beneficiary nobody linked or invited), account_not_ready, debit_consent_required.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          },
          {
            "name": "fundraiser_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "eligible": {
                          "type": "boolean"
                        },
                        "reason": {
                          "type": "string",
                          "nullable": true
                        },
                        "available_cents": {
                          "type": "integer"
                        },
                        "to_leader_fundly": {
                          "type": "boolean"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/communities/{id}/fund/allocations": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Give from the fund to a Fundly",
        "operationId": "allocateCommunityFund",
        "description": "Owner only, signed-in session. A Stripe Account Debit moves the money from the community account to the platform, then a donation from \"<Community> fund\" (no tip, no card fee, never anonymous, no receipt) lands on the Fundly and pays the recipient card checkout would: the nonprofit's own Stripe account, the linked beneficiary, a pending invitation (held until accepted) or, on the organizer's own Fundly, the organizer; never the organizer instead. A beneficiary that cannot take the gift is refused (409 RECIPIENT_UNAVAILABLE); if that is found after the debit, the money goes back to the fund. Refused for a Fundly the owner organizes, co-organizes or benefits from; labelled when it is a leader's. Send an `Idempotency-Key` header (or `idempotency_key`): the same key returns the first result; with a different body, 409 IDEMPOTENCY_CONFLICT. Publishes community.fund_allocated after commit.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "fundraiser_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "amount_cents": {
                    "type": "integer",
                    "minimum": 100,
                    "maximum": 10000000
                  },
                  "note": {
                    "type": "string",
                    "maxLength": 280
                  },
                  "idempotency_key": {
                    "type": "string",
                    "maxLength": 200
                  }
                },
                "required": [
                  "fundraiser_id",
                  "amount_cents"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "allocation_id": {
                          "type": "string"
                        },
                        "entry_id": {
                          "type": "string",
                          "nullable": true
                        },
                        "donation_id": {
                          "type": "string",
                          "nullable": true
                        },
                        "amount_cents": {
                          "type": "integer"
                        },
                        "available_cents_after": {
                          "type": "integer"
                        },
                        "to_leader_fundly": {
                          "type": "boolean"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "OWN_FUNDLY, INSUFFICIENT_BALANCE, AMOUNT_TOO_LARGE, DISPUTE_OPEN, NEGATIVE_BALANCE, FUND_DISABLED, ACCOUNT_NOT_READY, DEBIT_CONSENT_REQUIRED, FUNDRAISER_NOT_ACCEPTING, RECIPIENT_UNAVAILABLE, IDEMPOTENCY_CONFLICT, ALLOCATION_FAILED",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "502": {
            "description": "STRIPE_ERROR: the debit failed; nothing moved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/communities/{id}/fund/withdrawals/code": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Send the withdrawal code",
        "operationId": "requestCommunityFundWithdrawalCode",
        "description": "Owner only, signed-in session. Emails a 6-digit one-time code (10 minutes, one use, 5 attempts) to the owner's account address; at most 5 an hour.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "method": {
                          "type": "string",
                          "enum": [
                            "email"
                          ]
                        },
                        "sent_to_hint": {
                          "type": "string"
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Refused (see `code`)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/communities/{id}/fund/withdrawals": {
      "post": {
        "tags": [
          "Communities"
        ],
        "summary": "Withdraw from the fund to the community bank",
        "operationId": "withdrawCommunityFund",
        "description": "Owner only, signed-in session. A payout from the community's Stripe account to its bank, with a reason (at most 120 characters) and the emailed code. Blocked while a dispute is open or the balance is negative. Audit-logged; publishes community.fund_withdrawn after commit.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The community's uuid or slug."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amount_cents": {
                    "type": "integer",
                    "minimum": 100
                  },
                  "reason": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 120
                  },
                  "code": {
                    "type": "string",
                    "pattern": "^[0-9]{6}$"
                  }
                },
                "required": [
                  "amount_cents",
                  "reason",
                  "code"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "withdrawal_id": {
                          "type": "string"
                        },
                        "entry_id": {
                          "type": "string"
                        },
                        "payout_id": {
                          "type": "string"
                        },
                        "amount_cents": {
                          "type": "integer"
                        },
                        "arrival_date": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "available_cents_after": {
                          "type": "integer"
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "STEP_UP_REQUIRED, STEP_UP_INVALID, STEP_UP_EXPIRED",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "INSUFFICIENT_BALANCE, DISPUTE_OPEN, NEGATIVE_BALANCE, PAYOUTS_NOT_ENABLED, FUND_DISABLED",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "description": "STEP_UP_LOCKED",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "502": {
            "description": "STRIPE_ERROR: the payout did not start; nothing left the fund",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/me/community-funds/pay-options": {
      "get": {
        "tags": [
          "Communities"
        ],
        "summary": "Funds I can give from to this Fundly",
        "operationId": "getMyCommunityFundPayOptions",
        "description": "The donation widget's \"Pay with\" list: community funds the signed-in person owns, with money in them, that may give to this Fundly (never the person's own, co-organized or beneficiary Fundly, and none when the Fundly's beneficiary cannot take a fund gift now). A fund with an open dispute or a negative balance is listed with the reason.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "fundraiser_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "community_id": {
                            "type": "string"
                          },
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "avatar_url": {
                            "type": "string",
                            "nullable": true
                          },
                          "available_cents": {
                            "type": "integer"
                          },
                          "visibility": {
                            "type": "string"
                          },
                          "blocked_reason": {
                            "type": "string",
                            "enum": [
                              "dispute_open",
                              "negative_balance"
                            ],
                            "nullable": true
                          }
                        },
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/perks/{perkId}/use": {
      "get": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "getPerkUseScreen",
        "summary": "The \"Use perk\" screen",
        "description": "The perk, where it works (with each location's hours now), whether it can be used now, whether the signed-in person may use it (the tier, the 7-day hold after reaching it, once per period, \"Show sponsor perks\", the business's own team, a sanctioned region), their use this period and when it can be used again.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "near",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "example": "38.574,-121.481"
            },
            "description": "Where the phone is (`lat,lng`), sent only when the person already lets the site know: the storefronts come nearest first, with their distance. Never cached."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PerkUseScreen"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/perks/{perkId}/code": {
      "post": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "createPerkCodeKey",
        "summary": "Get the key for the live code",
        "description": "For a person who may use the perk in store now. Returns the key their phone makes the 6-digit codes with (also offline, for 24 hours). One live key per phone, three at most: a fourth replaces the oldest. 10 new codes a minute per person, with \"Get a code\". Never cached.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PerkUseCodeKey"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Perks aren't available in the person's region (`region`), or sponsors are switched off. Staff impersonating someone get `IMPERSONATION_RESTRICTED_ACTION`: staff never take a code, report or work the counter as anyone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "`perk_unavailable` (with the perk's `state` and its `availability`), `not_in_store`, or `not_eligible` (with the eligibility and `nextOn`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/perks/{perkId}/code/{keyId}": {
      "get": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "getPerkCodeStatus",
        "summary": "Whether the cashier has given it",
        "description": "The code screen polls this to turn green once the perk is given with its key. The key's owner only.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "keyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PerkUseCodeStatus"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/perks/{perkId}/online-code": {
      "post": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "getPerkOnlineCode",
        "summary": "Get a code (an online perk)",
        "description": "Hands the person the next one-time code from the business's list, in the same write as the use it counts as. Use it within 7 days. The team is told when it runs out, and when 10% of the list is left unless the list's low-stock alert is off. 10 new codes a minute per person.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The code",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PerkUseOnlineCode"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Perks aren't available in the person's region (`region`), or sponsors are switched off. Staff impersonating someone get `IMPERSONATION_RESTRICTED_ACTION`: staff never take a code, report or work the counter as anyone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "`out_of_codes`, `not_online`, `perk_unavailable` or `not_eligible`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/perk-uses/{useId}": {
      "get": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "getPerkUseReceipt",
        "summary": "A used perk's receipt",
        "description": "The person's own use only; anyone else gets `404`. An online use shows its code while it can still be used.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "useId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PerkUseReceipt"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/perk-uses/{useId}/report": {
      "post": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "reportPerkUse",
        "summary": "My perk wasn't honored",
        "description": "Once per use, within 30 days. The business is told what happened (never who) and has 3 days to answer: if it confirms, or doesn't answer, the person gets the use back; if it disputes, FundlyHub decides. `code_failed` is for online uses.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "useId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "kind"
                ],
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "not_given",
                      "gave_less",
                      "code_failed",
                      "other"
                    ]
                  },
                  "note": {
                    "type": "string",
                    "maxLength": 300
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The receipt, with the report",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PerkUseReceipt"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Staff impersonating someone get `IMPERSONATION_RESTRICTED_ACTION`: staff never take a code, report or work the counter as anyone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "`already_reported`, or `cannot_report` (undone, voided, or older than 30 days).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "422": {
            "description": "`invalid_kind` or `note_too_long`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/perk-uses/{useId}/report/reply": {
      "post": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "replyToPerkUseReport",
        "summary": "Not what happened? Reply",
        "description": "One reply to the outcome of the person's report, once the business answered or FundlyHub decided, within 30 days. The business sees it (never who wrote it), and so do FundlyHub staff.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "useId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reply"
                ],
                "properties": {
                  "reply": {
                    "type": "string",
                    "maxLength": 300
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The receipt, with the reply",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PerkUseReceipt"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Staff impersonating someone get `IMPERSONATION_RESTRICTED_ACTION`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "`no_report`, `already_replied`, or `cannot_reply` (still open, or more than 30 days after the outcome).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "422": {
            "description": "`reply_required` or `reply_too_long`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/counter/pair/preview": {
      "post": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "previewCounterPairing",
        "summary": "What a pairing code would pair",
        "description": "\"This device will check codes for Fast Cat Coffee Bar, Midtown.\" Does not use the code up. Codes are made in the workspace and work for 10 minutes. Ten tries per address per 10 minutes.",
        "security": [
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "pattern": "^\\d{6}$",
                    "example": "048213"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CounterPlace"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "`unknown_pairing_code`: wrong, used, or older than 10 minutes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "422": {
            "description": "`bad_code`: not six digits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/counter/pair": {
      "post": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "pairCounterDevice",
        "summary": "Pair this device",
        "description": "Uses the pairing code up and returns the device's session token, shown once. The device sends it on every counter request as `Authorization: Counter <token>`. A device signs out when the team removes it, its location closes, or after 30 days without use.",
        "security": [
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "pattern": "^\\d{6}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Paired",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/CounterPlace"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "token": {
                              "type": "string"
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "`unknown_pairing_code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "422": {
            "description": "`bad_code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/counter/session": {
      "get": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "getCounterSession",
        "summary": "Who is at the counter",
        "description": "With `Authorization: Counter <token>`, the paired device, its sponsor and location. Otherwise the signed-in person's sponsors and the locations they may use the counter at (owners and admins everywhere, managers and cashiers at theirs), each with whether it is open now.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CounterSession"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`device_unknown`, `device_removed`, `signed_out`, or `sign_in` (no device and nobody signed in).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/counter/check": {
      "post": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "checkCounterCode",
        "summary": "Check a code",
        "description": "A scanned QR (`qr`) or six typed digits (`code`), at this device's location, or at the location a signed-in team member picked (header `X-Counter-Location`). Answers with the perk and the tier, never the person. Five wrong codes in a row wait a minute; 30 checks a minute per device (or member and location), then `429 rate_limited` with `retryAfterSeconds`.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "X-Counter-Location",
            "in": "header",
            "required": false,
            "description": "A signed-in team member's location for this shift. Not sent by a paired device.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "qr": {
                    "type": "string",
                    "example": "FHP1:5b0e8d4c-2f1a-4c39-9d77-0a1b2c3d4e5f:59012345:048213"
                  },
                  "code": {
                    "type": "string",
                    "pattern": "^\\d{6}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The answer",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CounterAnswer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`pick_location`: a team member who has not picked a location.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "401": {
            "description": "`device_unknown`, `device_removed`, `signed_out` or `sign_in`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "403": {
            "description": "`not_your_location`, `not_on_team` (a member removed from the team: \"You're no longer on this team.\"), or sponsors are switched off. Staff impersonating someone get `IMPERSONATION_RESTRICTED_ACTION`: staff never take a code, report or work the counter as anyone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/counter/give": {
      "post": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "giveCounterPerk",
        "summary": "Give the perk",
        "description": "The code checked as `valid`, sent back with its key and step: it is checked again, and the use is recorded by the database, which applies the perk's rule once more. Can be undone for 15 minutes. Give tapped again for a code already given here answers `200` with the same use (`again: true`).",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "X-Counter-Location",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "keyId",
                  "step",
                  "code"
                ],
                "properties": {
                  "keyId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "step": {
                    "type": "integer"
                  },
                  "code": {
                    "type": "string",
                    "pattern": "^\\d{6}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Already given with this code (a second tap)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CounterGiven"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Given",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CounterGiven"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`device_unknown`, `device_removed`, `signed_out` or `sign_in`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "403": {
            "description": "`not_your_location`, or sponsors are switched off. Staff impersonating someone get `IMPERSONATION_RESTRICTED_ACTION`: staff never take a code, report or work the counter as anyone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "409": {
            "description": "`not_valid`, with what the counter would say now (`details.answer`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "422": {
            "description": "`bad_request`: no key, step or code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/counter/uses/{useId}/undo": {
      "post": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "undoCounterUse",
        "summary": "Undo a perk given here",
        "description": "Within 15 minutes, at the location it was given at. The person gets the use back. Not while a giver's report on the use waits for an answer: the report decides. The audit row names who undid it (the device, or the team member).",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "useId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "X-Counter-Location",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Undone",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "useId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "undoneAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`not_your_location`, or sponsors are switched off. Staff impersonating someone get `IMPERSONATION_RESTRICTED_ACTION`: staff never take a code, report or work the counter as anyone.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "`too_late` (after 15 minutes), `already_back`, or `answer_report` (a giver reported this use).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/counter/today": {
      "get": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "getCounterToday",
        "summary": "Today at this counter",
        "description": "Today's perks at this location, in its own time zone, and who checked each one: the newest 200 listed, and the count of those that count over the whole day.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "X-Counter-Location",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CounterToday"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/counter/problem": {
      "post": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "reportCounterProblem",
        "summary": "Something's wrong? Report it",
        "description": "The cashier's note to FundlyHub about an answer the counter gave: it records the answer, the location, the time and the perk it was about, never the giver. FundlyHub staff see it in the reports queue.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "X-Counter-Location",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "answer",
                  "note"
                ],
                "properties": {
                  "answer": {
                    "type": "string",
                    "description": "The answer shown: a `CounterAnswer` status, or `offline`."
                  },
                  "note": {
                    "type": "string",
                    "maxLength": 300
                  },
                  "perkId": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Sent",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "reportId": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`not_your_location` or `not_on_team`. Staff impersonating someone get `IMPERSONATION_RESTRICTED_ACTION`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "422": {
            "description": "`bad_answer`, `note_required` or `note_too_long`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/sponsors/{key}/manage/uses": {
      "get": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "listSponsorPerkUses",
        "summary": "Perks used",
        "description": "The four totals (today, this week, this month, all time: uses that count and the people who used them: \"givers thanked\" from 5 up all time, \"fewer than 10\" under 10 otherwise) and the uses themselves, newest first, in the sponsor's home time zone. Never who. Managers see their locations. Cashiers see today at theirs, with today's total alone and no draft perks in the filter. Online uses belong to no location, so only those who see every location see them.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug, an old slug, or its id."
          },
          {
            "name": "range",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "recent",
                "today",
                "yesterday",
                "week",
                "month",
                "all",
                "custom"
              ],
              "default": "recent"
            },
            "description": "`recent` is today and yesterday; `yesterday` is yesterday alone, in the home city. A cashier always gets `today`."
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "With `range=custom`."
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "With `range=custom`."
          },
          {
            "name": "location",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "A location id",
            "or `online`.": null
          },
          {
            "name": "perk",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "channel",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "counter",
                "online"
              ],
              "default": "all"
            }
          },
          {
            "name": "before",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "The `next` cursor of the previous page."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SponsorUsesPage"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "`bad_dates`, `bad_location`, `bad_perk` or `bad_cursor`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/uses/export": {
      "get": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "exportSponsorPerkUses",
        "summary": "Download perks used as CSV",
        "description": "The same filters as the list, at most 10,000 rows. Columns time, perk, location, tier, checked_by, status.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "range",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "recent",
                "today",
                "yesterday",
                "week",
                "month",
                "all",
                "custom"
              ]
            },
            "description": "`recent` is today and yesterday; `yesterday` is yesterday alone, in the home city."
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "location",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "perk",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "channel",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "counter",
                "online"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "CSV",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/sponsors/{key}/manage/uses/{useId}/void": {
      "post": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "voidSponsorPerkUse",
        "summary": "Give a use back",
        "description": "For a perk the business didn't honor: the person gets the use back. The owner and admins. Not while a report about it waits for an answer; answer the report instead. The reason is kept with the use (Perks used shows it under \"Undone\") and in the audit row.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "useId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reason"
                ],
                "properties": {
                  "reason": {
                    "type": "string",
                    "maxLength": 300
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Voided",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "useId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "voidedAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "`already_back` or `answer_report`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "422": {
            "description": "`reason_required` or `reason_too_long`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/reports": {
      "get": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "listSponsorUseReports",
        "summary": "Reports about perks used",
        "description": "Newest first, scoped like perks used, with how many came in the last 90 days. What happened, never who said so. Owners, admins and staff see every report, and managers see their locations'. Cashiers get 403: they see today's uses alone.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "reports": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/SponsorUseReport"
                          }
                        },
                        "last90Days": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/sponsors/{key}/manage/reports/{reportId}/answer": {
      "post": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "answerSponsorUseReport",
        "summary": "Answer a report",
        "description": "Within 3 days. `confirm` gives the person the use back at once; `dispute`, with what happened, goes to FundlyHub, who decide. A report not answered in 3 days is decided for the person. The owner and admins.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "reportId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "decision"
                ],
                "properties": {
                  "decision": {
                    "type": "string",
                    "enum": [
                      "confirm",
                      "dispute"
                    ]
                  },
                  "answer": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "Required to dispute."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Answered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "reportId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "confirmed",
                            "disputed"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "`already_answered`, `too_late` or `already_back`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "422": {
            "description": "`bad_decision`, `answer_required` or `answer_too_long`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/online-codes": {
      "get": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "listSponsorOnlineCodes",
        "summary": "Online code lists",
        "description": "Every online perk with its list of one-time codes, how many are left, and the uploads. The owner and admins.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "perks": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/SponsorOnlineCodeList"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "uploadSponsorOnlineCodes",
        "summary": "Upload one-time codes",
        "description": "A CSV's text, one code per line in the first column (a `code` header is skipped), at most 50,000. A code already on the perk's list or in the file, in any case, is refused, with its line; codes are stored encrypted. An upload that takes the perk from no codes left to some tells the givers watching it (\"Tell me when it's back\"). The owner and admins.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "perkId",
                  "csv"
                ],
                "properties": {
                  "perkId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "csv": {
                    "type": "string"
                  },
                  "filename": {
                    "type": "string",
                    "maxLength": 255
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Uploaded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "batchId": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true
                        },
                        "added": {
                          "type": "integer"
                        },
                        "duplicates": {
                          "type": "integer"
                        },
                        "duplicateLines": {
                          "type": "array",
                          "items": {
                            "type": "integer"
                          },
                          "description": "The first 20 lines (from 1) refused as duplicates."
                        },
                        "invalid": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Up to 20 lines that aren't codes."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "`not_online`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "422": {
            "description": "`bad_perk`, `empty_file`, `no_codes` or `file_too_large`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/online-codes/batches/{batchId}": {
      "delete": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "removeSponsorOnlineCodeBatch",
        "summary": "Remove an upload's unused codes",
        "description": "Codes already handed out stay, with their upload, as the record of their uses. The owner and admins.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "batchId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Removed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "removed": {
                          "type": "integer"
                        },
                        "batchKept": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/sponsors/{key}/manage/online-codes/{perkId}/alert": {
      "put": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "setSponsorOnlineCodesAlert",
        "summary": "A code list's low-stock alert",
        "description": "Whether the owner and admins are emailed when 10% of this list is left. Running out is always told. The owner and admins.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "lowStock"
                ],
                "properties": {
                  "lowStock": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "perkId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "lowStockAlert": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "`not_online`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          },
          "422": {
            "description": "`bad_switch`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/manage/connect": {
      "get": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "listSponsorConnectRequests",
        "summary": "The connections I asked about",
        "description": "Which connections that come later (an online shop, point of sale, loyalty, the developer API) the signed-in person asked to hear about for this business. The owner and admins.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "asked": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "shop",
                              "pos",
                              "loyalty",
                              "developers"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "tags": [
          "Sponsors · Perks and the counter"
        ],
        "operationId": "askSponsorConnect",
        "summary": "Tell me when it's ready",
        "description": "Kept per business, connection and person. Asking twice is the same ask.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "kind"
                ],
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "shop",
                      "pos",
                      "loyalty",
                      "developers"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Asked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "asked": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "shop",
                              "pos",
                              "loyalty",
                              "developers"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "`bad_kind`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorUsesError"
                }
              }
            }
          }
        }
      }
    },
    "/me/nonprofit-beneficiaries": {
      "get": {
        "tags": [
          "Non-profits"
        ],
        "operationId": "listMyNonprofitBeneficiaries",
        "summary": "List the signed-in user's nonprofit beneficiary choices",
        "description": "Uses live organization team roles and nonprofit verification status. Read-only members are listed with can_start false; unrelated organizations are never returned. Campaign creation and owner editing revalidate eligibility, including impersonated owners. Existing nonprofit selections are preserved on unrelated edits; recipient changes are locked once payment activity begins.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Nonprofit choices and server-owned eligibility",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "name",
                          "slug",
                          "logo",
                          "role",
                          "can_start",
                          "reason"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "slug": {
                            "type": "string"
                          },
                          "logo": {
                            "type": "string",
                            "nullable": true
                          },
                          "role": {
                            "type": "string",
                            "enum": [
                              "owner",
                              "admin",
                              "fundraiser",
                              "viewer",
                              "member"
                            ]
                          },
                          "can_start": {
                            "type": "boolean"
                          },
                          "reason": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "team_permission",
                              "not_verified",
                              null
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/me/nonprofit-invites": {
      "get": {
        "tags": [
          "Non-profits"
        ],
        "summary": "The signed-in person's waiting team invites",
        "operationId": "listMyNonprofitInvites",
        "description": "The team invites waiting for the signed-in person, so they can join or decline in the app and not only from the email's link: not accepted, declined, revoked or expired, sent to one of their VERIFIED emails (the rule accepting follows), and not to a team they are already on. Newest first, 50 at most. An account that already has the invited address verified also gets a bell when it is invited.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NonprofitMyInvite"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/me/nonprofit-invites/{id}/accept": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Join a team from the app",
        "operationId": "acceptMyNonprofitInvite",
        "description": "The same as accepting from the email's link (POST /nonprofits/invite/{token}/accept): the invite's role and title, On page as chosen, org.invite_accepted and the inviter's email. By id, an invite that is not addressed to one of the caller's verified emails answers 404, never a hint of the address.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The invite id from GET /me/nonprofit-invites."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "show_on_page": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slug": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "slug"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Unknown, or not addressed to one of your verified emails.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "409": {
            "description": "`expired`, `accepted` (by someone else; the same person accepting again gets `200`), `revoked` or `declined`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/me/nonprofit-invites/{id}/decline": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Decline a team invite from the app",
        "operationId": "declineMyNonprofitInvite",
        "description": "The same as declining from the email's link: the invite stops waiting, so the team can invite the address again. Declining twice answers the same. 404 when the invite is not addressed to one of the caller's verified emails.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The invite id from GET /me/nonprofit-invites."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slug": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "slug"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Unknown, or not addressed to one of your verified emails.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "409": {
            "description": "`expired`, `accepted` or `revoked`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits": {
      "get": {
        "tags": [
          "Non-profits"
        ],
        "summary": "The non-profit directory",
        "operationId": "listNonprofits",
        "description": "Verified pages only (paused ones after them); never drafts, never pages under review. Facets count causes and cities over the other filter. Each card is built for the caller (`viewer`: their role and Follow state).",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "Nonprofits excludes churches; church lists churches; all includes both. Applied before pagination and facets.",
            "schema": {
              "type": "string",
              "enum": [
                "nonprofit",
                "church",
                "all"
              ],
              "default": "nonprofit"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Name, mission or a 9-digit EIN (2+ characters)."
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "A city (place) slug."
          },
          {
            "name": "cause",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "animals",
                "arts_culture",
                "children_youth",
                "community_development",
                "disaster_relief",
                "education",
                "environment",
                "food_security",
                "health",
                "housing_homelessness",
                "human_rights",
                "immigrant_refugee",
                "mental_health",
                "seniors",
                "veterans",
                "women_girls",
                "religious",
                "other"
              ]
            },
            "description": "A cause key."
          },
          {
            "name": "offers_help",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "1"
              ]
            },
            "description": "Just the ones with help in Find help (#2423). Ignored while Resources are switched off."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "impact",
                "newest",
                "name"
              ],
              "default": "impact"
            },
            "description": "Order."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 24,
              "maximum": 48
            },
            "description": "Page size."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0
            },
            "description": "Offset."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NonprofitCard"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        }
                      }
                    },
                    "facets": {
                      "type": "object",
                      "properties": {
                        "causes": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "key": {
                                "type": "string"
                              },
                              "count": {
                                "type": "integer"
                              }
                            }
                          }
                        },
                        "cities": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "slug": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "count": {
                                "type": "integer"
                              }
                            }
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "data",
                    "pagination",
                    "facets"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Unknown `kind`, `sort` or `cause` (the error's `code` names which).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Create a non-profit draft from an EIN",
        "operationId": "createNonprofitDraft",
        "description": "Add flow (requireVerifiedEmail; shares the EIN lookup's 20 per hour per person). Allowed for lookup outcomes `verified` and `manual_review` (and `revoked` with `route: reinstatement`). Creates the org (kind nonprofit, verification pending) with the caller as owner; one unfinished draft per person per EIN (the existing one is returned), and at most 5 unfinished drafts per person (MAX_OPEN_DRAFTS; 409 `too_many_drafts`). Someone else's draft that nobody has saved for 30 days no longer holds the EIN: it is released (soft-deleted, its address freed) and this draft is created.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ein": {
                    "type": "string",
                    "example": "12-3456789"
                  },
                  "route": {
                    "type": "string",
                    "enum": [
                      "reinstatement"
                    ]
                  }
                },
                "required": [
                  "ein"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The caller already has an unfinished draft for this EIN; it is returned as it is and nothing is created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "slug": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "draft"
                      ]
                    },
                    "step": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "slug": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "draft"
                      ]
                    },
                    "step": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "description": "`ein_taken` (with `existing`), `not_eligible`, `not_found`, or `too_many_drafts` (`details.max`: the caller already has that many unfinished drafts; finish or delete one).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "422": {
            "description": "`invalid_ein`: an EIN is 9 digits, like 12-3456789.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: the EIN lookup budget (20 per hour per person) is spent."
          }
        }
      }
    },
    "/nonprofits/lookup": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Look an EIN up",
        "operationId": "lookupNonprofitEin",
        "description": "Add flow step 1 (requireVerifiedEmail; 20 per hour per person). The six outcomes, first match wins: existing, revoked, verified, manual_review (church, group, private_foundation), not_eligible, not_found. Every outcome is a `200`: `existing` means a submitted page already has this EIN, and carries that page's card in `existing` with the caller's own standing on its team (`existing.viewer`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ein": {
                    "type": "string",
                    "example": "12-3456789"
                  }
                },
                "required": [
                  "ein"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitLookupResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "description": "`invalid_ein`: the EIN is not 9 digits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "429": {
            "description": "Too many lookups.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/drafts/mine": {
      "get": {
        "tags": [
          "Non-profits"
        ],
        "summary": "My unfinished non-profit drafts",
        "operationId": "listMyNonprofitDrafts",
        "description": "The caller's unfinished non-profit drafts, the add flow's resume list, most recently saved first: each draft's id, slug, display name, EIN (as `12-3456789`), the add-flow `step` it is on, and when it was last saved. Only drafts the caller owns and has not yet submitted are listed. Needs a signed-in session with a verified email address (`403` with `code: EMAIL_NOT_VERIFIED` otherwise).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "slug": {
                            "type": "string"
                          },
                          "display_name": {
                            "type": "string"
                          },
                          "ein": {
                            "type": "string"
                          },
                          "step": {
                            "type": "integer"
                          },
                          "updated_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/nonprofits/notify-me": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Notify me when an EIN appears",
        "operationId": "notifyMeNonprofitEin",
        "description": "EIN lookup outcome 6: the monthly IRS load emails the person when the EIN becomes an eligible 501(c)(3).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ein": {
                    "type": "string"
                  }
                },
                "required": [
                  "ein"
                ]
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Done"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/nonprofits/claims/report": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Report a wrong claim on an EIN",
        "operationId": "reportNonprofitClaim",
        "description": "Writes an org_reports row (category impersonation) on the page that has the EIN, an unfinished draft included (the one a 409 `ein_taken` names).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ein": {
                    "type": "string"
                  },
                  "details": {
                    "type": "string",
                    "maxLength": 4000
                  }
                },
                "required": [
                  "ein"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Reported. One report per person per page; reporting the same page again replaces the earlier report and keeps its `id`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "The report's id."
                    }
                  },
                  "required": [
                    "id"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No page, not even an unfinished draft, has this EIN.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "422": {
            "description": "`invalid_ein` (not 9 digits) or `invalid` (`details` that is not text or is longer than 4000 characters).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/invite/{token}": {
      "get": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Read a team invite",
        "operationId": "readNonprofitInvite",
        "description": "Public, built for the caller. What the invite page shows: the invited address as a hint, and in full only to a caller one of whose verified emails it is; whether accepting will work and whether the caller is already on the team.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The invite token from the email."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitInviteView"
                }
              }
            }
          },
          "404": {
            "description": "Unknown token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/invite/{token}/accept": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Accept a team invite",
        "operationId": "acceptNonprofitInvite",
        "description": "Joins with the invite's role and title; On page as chosen, else on for owner/admin/fundraiser/viewer and off for member. One of the person's VERIFIED emails must equal the invited address. Publishes org.invite_accepted and emails the inviter.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The invite token from the email."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "show_on_page": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slug": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "slug"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`email_mismatch`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "404": {
            "description": "Unknown token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "409": {
            "description": "`expired`, `accepted` (by someone else; the same person accepting again gets `200`), `revoked` or `declined`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/invite/{token}/decline": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Decline a team invite",
        "operationId": "declineNonprofitInvite",
        "description": "The invited person says no. One of the person's VERIFIED emails must equal the invited address. The invite stops waiting, so the team can invite the address again. Declining twice answers the same.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The invite token from the email."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slug": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "slug"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`email_mismatch`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "404": {
            "description": "Unknown token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "409": {
            "description": "`expired`, `accepted` or `revoked`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/{slug}": {
      "get": {
        "tags": [
          "Non-profits"
        ],
        "summary": "A non-profit page",
        "operationId": "getNonprofit",
        "description": "404 for a draft unless the viewer is its owner or staff; a page under review (or rejected, suspended) only for its team and staff. An old slug answers with the current one in `slug`.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The non-profit's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitDetail"
                }
              }
            }
          },
          "404": {
            "description": "Not found (or not visible to this viewer).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Delete my non-profit draft",
        "operationId": "deleteNonprofitDraft",
        "description": "The owner deletes their own unfinished draft: it disappears and its address (slug) is freed. This operation takes the draft's id in the `{slug}` segment, not a slug. Only the draft's owner may call it, with a verified email address; anyone else, an unknown id and a deleted draft get `404`. A non-profit that was already submitted answers `409` `already_submitted`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The draft's id (a uuid), not its slug. The segment is named `slug` because this delete shares its path with the page read, `GET /nonprofits/{slug}`."
          }
        ],
        "responses": {
          "204": {
            "description": "Done"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Not a draft of the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "409": {
            "description": "`already_submitted`: the non-profit was submitted, so it is no longer a draft.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/{id}/onboarding": {
      "get": {
        "tags": [
          "Non-profits"
        ],
        "summary": "A draft's add-flow state",
        "operationId": "getNonprofitOnboarding",
        "description": "The add flow's state for a non-profit the caller owns, a draft or a page already submitted: the page as `GET /nonprofits/{slug}` shows it to its owner, plus the current `step`, the IRS record, how authority to act for the organization was claimed and where that stands, the address, the receipt settings, the Stripe summary, the documents, the latest checks and the attestation sentence to accept (`attestation_text`, `attestation_version`). Only the owner may read it, with a verified email address; anyone else, an unknown id and a deleted page get `404`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The non-profit's id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitOnboarding"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Not a non-profit the caller owns (a draft or a submitted page).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Save add-flow fields",
        "operationId": "patchNonprofitOnboarding",
        "description": "Any of `{step, title, attestation, attestation_text}` and the page settings fields (validated as Settings), links replaced as a list. With `attestation` true, `attestation_text` is required (422 `required` without it) and must be the sentence that was shown (the GET's `attestation_text`); a sentence that has changed since is refused (409 `attestation_changed`). The server stores its own sentence with `attestation_version` and the time. Changing the website to another registrable domain resets a work-email authority claim (authority method and status back to null; the address is kept for the next code) unless the address is at a staff-verified domain.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The non-profit's id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/NonprofitSettingsPatch"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "step": {
                        "type": "integer"
                      },
                      "title": {
                        "type": "string"
                      },
                      "attestation": {
                        "type": "boolean"
                      },
                      "attestation_text": {
                        "type": "string",
                        "description": "Required with `attestation` true, the attestation sentence the person was shown (the GET's `attestation_text`)."
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitOnboarding"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "description": "`already_submitted`, or `attestation_changed`: the sent `attestation_text` is no longer this organization's sentence (`details.attestation_text` is the current one); nothing is saved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "422": {
            "description": "A field failed (`details.field`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/{id}/authority/email": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Send a work-email code",
        "operationId": "sendNonprofitAuthorityEmail",
        "description": "The domain must be the org website's (or a subdomain), never a free mail domain.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The non-profit's id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string"
                  },
                  "website": {
                    "type": "string"
                  }
                },
                "required": [
                  "email"
                ]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sent_to": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Not a draft or page of the caller (an unknown id, someone else's, or a deleted one).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "409": {
            "description": "`already_verified` (authority is already confirmed) or `already_submitted` (the page was submitted).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "422": {
            "description": "`invalid_email`, `free_email_domain`, `website_required` (the page has no website and none was sent), `invalid_website`, or `domain_mismatch` (`details.expected` is the domain the address must be at).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: five codes an hour for this page and person.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/{id}/authority/email/verify": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Verify the work-email code",
        "operationId": "verifyNonprofitAuthorityEmail",
        "description": "Six digits, 15 minutes, 5 attempts. The right code proves the inbox. Authority is `verified` only when the address is at a domain staff verified for this organization; at the website the owner entered it is `pending` until staff decide. The confirmed address is a new claim: a staff decision on an earlier one does not carry over. `domain_mismatch` when the website has moved to another domain since the code was sent. Once authority is verified (staff may have decided after the code was sent) the code is refused with `already_verified` and stays unused.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The non-profit's id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  }
                },
                "required": [
                  "code"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "authority": {
                      "$ref": "#/components/schemas/NonprofitAuthority"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "description": "`already_verified`: authority is already confirmed, so the code cannot replace it. `already_submitted`: the page was submitted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "422": {
            "description": "`bad_code`, `expired`, `too_many_attempts` or `domain_mismatch`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/{id}/authority/form990": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Claim authority by the latest Form 990",
        "operationId": "claimNonprofitAuthorityForm990",
        "description": "Claims authority to act for the organization as one of the officers listed on its latest Form 990: `name_on_990` (your name as the 990 gives it) and your `title`, each required and at most 120 characters. The claim is saved as pending (`authority.method: form990`, `status: pending`) for staff, who check the name against the 990. Only the draft's owner may call it (`404` for anyone else), with a verified email address. A page already submitted answers `409` `already_submitted`, authority that is already confirmed `409` `already_verified`, and a missing or overlong field `422` `invalid`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The non-profit's id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name_on_990": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  }
                },
                "required": [
                  "name_on_990",
                  "title"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "authority": {
                      "$ref": "#/components/schemas/NonprofitAuthority"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/nonprofits/{id}/authority/letter": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Claim authority by an officer letter",
        "operationId": "claimNonprofitAuthorityLetter",
        "description": "The letter is uploaded first through POST /org-admin/{slug}/documents with doc_type officer_letter.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The non-profit's id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "document_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "document_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "authority": {
                      "$ref": "#/components/schemas/NonprofitAuthority"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/nonprofits/{id}/authority/volunteer": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Submit a volunteer affiliation claim for staff review",
        "operationId": "claimNonprofitAuthorityVolunteer",
        "description": "Only the verified-email owner of a draft may submit. The claim stays pending until staff verify it; it never enables donations by itself.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The non-profit's id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "authority": {
                      "$ref": "#/components/schemas/NonprofitAuthority"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/nonprofits/{id}/submit": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Submit a draft for review",
        "operationId": "submitNonprofit",
        "description": "Records the terms, runs every check and publishes organization.created (kind nonprofit). The page becomes under_review.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The non-profit's id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "terms_accepted": {
                    "type": "boolean",
                    "enum": [
                      true
                    ]
                  }
                },
                "required": [
                  "terms_accepted"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitDetail"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "description": "`incomplete` with `details.missing`. `attestation` is missing unless the stored acceptance has the current `attestation_version` and `attestation_text`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/{slug}/giving-policy": {
      "get": {
        "tags": [
          "Non-profits"
        ],
        "operationId": "getNonprofitGivingPolicy",
        "summary": "Read current general-fund giving policy",
        "description": "Returns server-owned presets, limits, currency and current one-time/monthly availability. Reads current nonprofit standing and both money switches. No account IDs, donor contacts or private legal address are returned.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current policy; can_give false means checkout is unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "org_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "slug": {
                          "type": "string"
                        },
                        "currency": {
                          "type": "string",
                          "enum": [
                            "usd"
                          ]
                        },
                        "can_give": {
                          "type": "boolean"
                        },
                        "monthly_enabled": {
                          "type": "boolean"
                        },
                        "unavailable_reason": {
                          "type": "string",
                          "nullable": true
                        },
                        "limits": {
                          "type": "object",
                          "properties": {
                            "gift_min_cents": {
                              "type": "integer"
                            },
                            "gift_max_cents": {
                              "type": "integer"
                            },
                            "note_max": {
                              "type": "integer"
                            },
                            "purpose_max": {
                              "type": "integer"
                            },
                            "donor_name_max": {
                              "type": "integer"
                            },
                            "preset_cents": {
                              "type": "array",
                              "items": {
                                "type": "integer"
                              }
                            },
                            "default_cents": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/nonprofits/{slug}/gift-quote": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "operationId": "quoteNonprofitGeneralGift",
        "summary": "Quote a general-fund gift without reserving or charging it",
        "description": "Prices a gift to the non-profit's general fund the way checkout prices it, without reserving or charging anything: `amount_cents` (within the `gift_min_cents` and `gift_max_cents` of `GET /nonprofits/{slug}/giving-policy`), optional `tip_cents` (must be zero; nonprofit and church donations do not accept FundlyHub tips), `cover_fee` to add the processing fee on top, and `frequency` (`once`, the default, or `monthly`). No sign-in needed; `POST /nonprofits/{slug}/gifts` computes the quote again when the gift is made. A page the caller cannot see answers `404`, a fund that is not taking gifts (or `monthly` while monthly gifts are off) `409`, and a bad amount or an unknown field `422`.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "amount_cents"
                ],
                "properties": {
                  "amount_cents": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "tip_cents": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 0,
                    "default": 0
                  },
                  "cover_fee": {
                    "type": "boolean"
                  },
                  "frequency": {
                    "type": "string",
                    "enum": [
                      "once",
                      "monthly"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Exact current quote; final checkout repeats eligibility and quote calculations.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/NonprofitGiftQuote"
                        },
                        {
                          "type": "object",
                          "required": [
                            "frequency",
                            "currency"
                          ],
                          "properties": {
                            "frequency": {
                              "type": "string",
                              "enum": [
                                "once",
                                "monthly"
                              ]
                            },
                            "currency": {
                              "type": "string",
                              "enum": [
                                "usd"
                              ]
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Nonprofit or requested giving frequency is unavailable."
          },
          "422": {
            "description": "Invalid amount",
            "frequency": null,
            "or input fields.": null
          }
        }
      }
    },
    "/nonprofits/{slug}/gifts": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "operationId": "createNonprofitGeneralGift",
        "summary": "Reserve a nonprofit general-fund gift and prepare payment",
        "description": "Guest and authenticated checkout. Requires private receipt contacts even when giving anonymously. Reserves immutable recipient and quote before Stripe; no personal-account fallback. The response does not itself charge a card. The donor confirms its PaymentIntent through Stripe Elements. Monthly gifts require explicit consent and use Billing after the first capture. Treat receipt and payment identifiers as private capabilities.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NonprofitGeneralGiftInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reserved payment and frozen final quote; no card charge until donor confirmation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "client_secret": {
                          "type": "string"
                        },
                        "payment_intent_id": {
                          "type": "string"
                        },
                        "amount_cents": {
                          "type": "integer",
                          "description": "The total the card is charged (the quote's total_cents)."
                        },
                        "stripe_fee_cents": {
                          "type": "integer",
                          "description": "The processing fee (the quote's processing_fee_cents)."
                        },
                        "net_amount_cents": {
                          "type": "integer",
                          "description": "What the non-profit receives (the quote's nonprofit_net_cents)."
                        },
                        "receipt_id": {
                          "type": "string"
                        },
                        "frequency": {
                          "type": "string",
                          "enum": [
                            "once",
                            "monthly"
                          ]
                        },
                        "quote": {
                          "$ref": "#/components/schemas/NonprofitGiftQuote"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Nonprofit",
            "account": null,
            "policy or reused checkout key is unavailable or conflicts.": null
          },
          "422": {
            "description": "Invalid input or missing monthly consent."
          },
          "429": {
            "description": "Checkout rate limit exceeded."
          }
        }
      }
    },
    "/nonprofits/{slug}/fundlies": {
      "get": {
        "tags": [
          "Non-profits"
        ],
        "summary": "A non-profit's Fundlies",
        "operationId": "listNonprofitFundlies",
        "description": "Only its own Fundlies (beneficiary_type nonprofit, this org), publicly listed; never a team member's personal Fundly. Rows are the communities Fundlies tab rows plus `goal_reached_at` (the Impact tab's rows). Active = live and not fully funded.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The non-profit's slug (an old slug resolves too) or id."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "completed",
                "all"
              ],
              "default": "active"
            },
            "description": "Tab."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "most_raised",
                "ending"
              ]
            },
            "description": "The communities Fundlies tab's sorts; omitted keeps each tab's own order (Active: live first, newest; Completed: most recently ended)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 12,
              "maximum": 48
            },
            "description": "Page size."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Offset."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "allOf": [
                          {
                            "$ref": "#/components/schemas/CommunityFundly"
                          },
                          {
                            "type": "object",
                            "properties": {
                              "goal_reached_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true,
                                "description": "When it reached its goal (\"Funded Sep 18\")."
                              }
                            }
                          }
                        ]
                      }
                    },
                    "counts": {
                      "type": "object",
                      "properties": {
                        "active": {
                          "type": "integer"
                        },
                        "completed": {
                          "type": "integer"
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/CommunityPage"
                    }
                  },
                  "required": [
                    "data",
                    "counts"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "422": {
            "description": "Unknown status or sort.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/{slug}/team": {
      "get": {
        "tags": [
          "Non-profits"
        ],
        "summary": "A non-profit's Members tab",
        "operationId": "getNonprofitTeam",
        "description": "On page members only, grouped by their title's category (governance/executive: leadership; programs/fundraising/operations: staff; community: volunteers), else by role. The followers it names are chosen for the caller.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The non-profit's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "groups": {
                      "type": "object",
                      "properties": {
                        "leadership": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/NonprofitPublicMember"
                          }
                        },
                        "staff": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/NonprofitPublicMember"
                          }
                        },
                        "volunteers": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/NonprofitPublicMember"
                          }
                        }
                      }
                    },
                    "hidden_count": {
                      "type": "integer",
                      "description": "Members who keep their names private."
                    },
                    "followers": {
                      "type": "integer"
                    },
                    "followers_preview": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NonprofitPersonFace"
                      },
                      "maxItems": 5,
                      "description": "Up to 5 followers with public profiles, people the caller follows first, then the newest; never the caller."
                    },
                    "followers_others": {
                      "type": "integer",
                      "description": "`followers` less the ones named in followers_preview (\"and 1,202 others\")."
                    }
                  },
                  "required": [
                    "groups",
                    "hidden_count",
                    "followers",
                    "followers_preview",
                    "followers_others"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/{slug}/activity": {
      "get": {
        "tags": [
          "Non-profits"
        ],
        "summary": "A non-profit's activity",
        "operationId": "getNonprofitActivity",
        "description": "Updates, Fundlies launched, 25/50/75% and goals reached, newest first.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The non-profit's slug (an old slug resolves too) or id."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 50
            },
            "description": "How many."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NonprofitActivityItem"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/{slug}/impact": {
      "get": {
        "tags": [
          "Non-profits"
        ],
        "summary": "A non-profit's impact",
        "operationId": "getNonprofitImpact",
        "description": "Historical Raised and distinct donors across its own public counted Fundlies and completed direct general-fund/monthly gifts, with separate Fundly/direct subtotals. Tips are excluded and processing fees deducted. Completed own-fund grants do not count the same money twice. Raw Fundly cards retain their progress; optional impact_raised_cents gives their adjusted contribution. The City block retains its separate existing campaign attribution rules.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The non-profit's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "raised_cents": {
                      "type": "integer",
                      "description": "fundly_raised_cents plus general_fund_raised_cents; includes paid/refunded historical gifts."
                    },
                    "fundly_raised_cents": {
                      "type": "integer"
                    },
                    "general_fund_raised_cents": {
                      "type": "integer"
                    },
                    "fundlies": {
                      "type": "integer"
                    },
                    "donors": {
                      "type": "integer"
                    },
                    "since": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true,
                      "description": "The earliest counted Fundly launch or completed direct gift."
                    },
                    "breakdown": {
                      "type": "array",
                      "items": {
                        "allOf": [
                          {
                            "$ref": "#/components/schemas/CommunityFundly"
                          },
                          {
                            "type": "object",
                            "properties": {
                              "goal_reached_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true,
                                "description": "When it reached its goal (\"funded Sep 18\")."
                              },
                              "impact_raised_cents": {
                                "type": "integer",
                                "description": "Contribution to the organization's impact after excluding its own completed fund grants; omitted when equal to the raw raised_cents card value."
                              }
                            }
                          }
                        ]
                      },
                      "maxItems": 200,
                      "description": "Its counted Fundlies, most raised first. Adjusted contributions exclude own-fund grants; direct general-fund gifts are separate. At most 200 rows, while totals cover every eligible gift."
                    },
                    "city": {
                      "nullable": true,
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/NonprofitCityBlock"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "place": {
                              "$ref": "#/components/schemas/NonprofitPlaceRef"
                            },
                            "city_impact_cents": {
                              "type": "integer"
                            },
                            "communities": {
                              "type": "integer"
                            },
                            "nonprofits": {
                              "type": "integer"
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/{slug}/documents/{docId}": {
      "get": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Open a non-profit's public document",
        "operationId": "getNonprofitPublicDocument",
        "description": "A document staff approved and the team shows on About (the determination letter); never a W-9 or bank document. PDFs and images open inline (nosniff); anything else downloads. 404 for anything else, or for a page the caller may not see.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The non-profit's slug (an old slug resolves too) or id."
          },
          {
            "name": "docId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The document id (tax.determination_letter.id)."
          }
        ],
        "responses": {
          "200": {
            "description": "The file",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/{slug}/follow": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Follow a non-profit",
        "operationId": "followNonprofit",
        "description": "Follows the non-profit's page and answers `following: true` with its follower count; following it again changes nothing. Any signed-in caller may follow a page they can see, by the same rule as `GET /nonprofits/{slug}`; any other page, an unknown slug and a deleted page answer `404`. The follow is stored like any organization follow (`following_type: organization`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The non-profit's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "following": {
                      "type": "boolean"
                    },
                    "followers": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Unfollow a non-profit",
        "operationId": "unfollowNonprofit",
        "description": "Stops following the non-profit and answers `following: false` with its follower count. It is idempotent: not following already is fine. Any signed-in caller; unlike following, it works on any page the slug names, even one the caller can no longer see, and only an unknown slug or a deleted page answers `404`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The non-profit's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "following": {
                      "type": "boolean"
                    },
                    "followers": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/{slug}/links/{linkId}/click": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Count a link click",
        "operationId": "clickNonprofitLink",
        "description": "A beacon: one counter per link per UTC day, no user ids. Always 204.",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The non-profit's slug (an old slug resolves too) or id."
          },
          {
            "name": "linkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The link id."
          }
        ],
        "responses": {
          "204": {
            "description": "Done"
          }
        }
      }
    },
    "/nonprofits/{slug}/report": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Report a non-profit",
        "operationId": "reportNonprofit",
        "description": "requireVerifiedEmail. The org_reports flow (one report per person per org).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The non-profit's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "category": {
                    "type": "string",
                    "enum": [
                      "fraud",
                      "impersonation",
                      "spam",
                      "mission_misalignment",
                      "sexual_content",
                      "hate",
                      "other"
                    ]
                  },
                  "details": {
                    "type": "string",
                    "maxLength": 4000
                  }
                },
                "required": [
                  "category"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/{slug}/join-requests": {
      "post": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Ask to join the team",
        "operationId": "requestToJoinNonprofit",
        "description": "requireVerifiedEmail. Publishes nonprofit.join_requested and emails the owner and admins.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The non-profit's slug (an old slug resolves too) or id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "note": {
                    "type": "string",
                    "maxLength": 500
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "pending"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Not found (or a draft).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "409": {
            "description": "`already_member` or `already_requested`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/nonprofits/{slug}/join-requests/mine": {
      "delete": {
        "tags": [
          "Non-profits"
        ],
        "summary": "Withdraw my join request",
        "operationId": "withdrawNonprofitJoinRequest",
        "description": "Withdraws the caller's pending request to join the non-profit's team. It is idempotent: with no pending request nothing changes, and the answer is the same `204`. Any signed-in caller; it works on any page the slug names, and only an unknown slug or a deleted page answers `404`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The non-profit's slug (an old slug resolves too) or id."
          }
        ],
        "responses": {
          "204": {
            "description": "Done"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/nonprofit/attention": {
      "get": {
        "tags": [
          "Non-profits · Team settings"
        ],
        "summary": "Needs your attention",
        "operationId": "getNonprofitAttention",
        "description": "org.read, built for the caller. Counts from the same reads as the surfaces they point at (0 included): join_requests and invites_waiting (the team view's lists; an expired invite waits to be resent), stripe_requirements, registry_renewal (within 30 days, with `due`), check_failed (the verification view's latest checks), authority_pending. fundly_approvals joins in phase 2. Plus the month-so-far card over the org's counted gifts since the 1st, the gifts the Overview and Analytics count: to its counted Fundlies, plus the general-fund and monthly gifts made to it directly (`label` is the ISO month, e.g. 2026-10).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The organization's slug (requireOrgPermission resolves it)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "kind": {
                            "type": "string",
                            "enum": [
                              "join_requests",
                              "invites_waiting",
                              "stripe_requirements",
                              "registry_renewal",
                              "check_failed",
                              "authority_pending"
                            ]
                          },
                          "count": {
                            "type": "integer"
                          },
                          "href": {
                            "type": "string"
                          },
                          "due": {
                            "type": "string",
                            "format": "date"
                          },
                          "sent_at": {
                            "type": "string",
                            "format": "date-time",
                            "description": "invites_waiting: when the oldest one was sent."
                          },
                          "emails": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "invites_waiting, only to someone who manages the team: the waiting addresses."
                          }
                        },
                        "required": [
                          "kind",
                          "count",
                          "href"
                        ]
                      }
                    },
                    "month": {
                      "type": "object",
                      "properties": {
                        "label": {
                          "type": "string"
                        },
                        "raised_cents": {
                          "type": "integer"
                        },
                        "gifts": {
                          "type": "integer"
                        },
                        "donors": {
                          "type": "integer"
                        },
                        "payouts_href": {
                          "type": "string"
                        },
                        "donations_href": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Not a non-profit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/nonprofit": {
      "get": {
        "tags": [
          "Non-profits · Team settings"
        ],
        "summary": "Read editable nonprofit settings",
        "operationId": "getNonprofitSettings",
        "description": "Requires org.update_settings. Returns the scoped nonprofit's editable page fields, private contact and mailing address, receipt preferences, and general fund preferences.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The organization's slug (requireOrgPermission resolves it)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitSettings"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Not a non-profit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Non-profits · Team settings"
        ],
        "summary": "Edit the page",
        "operationId": "patchNonprofitSettings",
        "description": "org.update_settings. The page fields; legal_name and ein are refused (422 `locked`). A city change applies to Fundlies launched afterwards. On an unsubmitted draft, changing the website to another registrable domain resets a work-email authority claim, as PATCH /nonprofits/{id}/onboarding does (not after submit, where staff decide the claim). The team's only way to change a non-profit's website (PATCH /org-admin/{slug}/settings refuses it, 422 `use_nonprofit_settings`). Audited as organization.nonprofit_settings_updated; no event.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The organization's slug (requireOrgPermission resolves it)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NonprofitSettingsPatch"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitDetail"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Not a non-profit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "422": {
            "description": "`locked`, or a field failed (`details.field`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/links": {
      "get": {
        "tags": [
          "Non-profits · Team settings"
        ],
        "summary": "The page's links, for editing",
        "operationId": "getNonprofitLinks",
        "description": "org.update_settings. Flagged rows and 30-day clicks included.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The organization's slug (requireOrgPermission resolves it)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NonprofitEditableLink"
                      }
                    },
                    "max": {
                      "type": "integer",
                      "example": 8
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "put": {
        "tags": [
          "Non-profits · Team settings"
        ],
        "summary": "Replace the page's links",
        "operationId": "putNonprofitLinks",
        "description": "org.update_settings. The ordered list replaces the live one (a row with its id keeps it and its clicks). Normalized, deduped, at most 8, Web Risk on save; a staff-removed URL cannot come back. Mirrors the six fixed keys of social_links. Audited as organization.links_updated; no event.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The organization's slug (requireOrgPermission resolves it)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "links": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/NonprofitLinkInput"
                    }
                  }
                },
                "required": [
                  "links"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NonprofitEditableLink"
                      }
                    },
                    "max": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "description": "A row failed (`details.index`, `details.reason`: empty, invalid, scheme, host, too_long, duplicate, max, label, unsafe, removed), or the body is not a list (`list`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/programs": {
      "get": {
        "tags": [
          "Non-profits · Team settings"
        ],
        "summary": "The page's programs",
        "operationId": "getNonprofitPrograms",
        "description": "The programs (\"What we do\") on the non-profit's page, in display order, for the edit form, with `max`, the most a page can have (12). `PUT /org-admin/{slug}/programs` replaces the list. Needs `org.update_settings` on the organization (its owner and admins), else `403`; an organization that is not a non-profit answers `404` (`not_nonprofit`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The organization's slug (requireOrgPermission resolves it)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NonprofitProgram"
                      }
                    },
                    "max": {
                      "type": "integer",
                      "example": 12
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "put": {
        "tags": [
          "Non-profits · Team settings"
        ],
        "summary": "Replace the page's programs",
        "operationId": "putNonprofitPrograms",
        "description": "org.update_settings. The ordered list, up to 12; a row with its id keeps it. Audited as organization.programs_updated.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The organization's slug (requireOrgPermission resolves it)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "programs": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "title": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string",
                          "nullable": true
                        },
                        "icon": {
                          "type": "string",
                          "nullable": true
                        }
                      },
                      "required": [
                        "title"
                      ]
                    }
                  }
                },
                "required": [
                  "programs"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NonprofitProgram"
                      }
                    },
                    "max": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "description": "`list` (the body is not a list), `max`, `title`, `description` or `icon`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/team": {
      "get": {
        "tags": [
          "Non-profits · Team settings"
        ],
        "summary": "The team",
        "operationId": "getNonprofitTeamSettings",
        "description": "org.read. Emails, invites and join requests only for managers.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The organization's slug (requireOrgPermission resolves it)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitTeam"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/org-admin/{slug}/invites": {
      "post": {
        "tags": [
          "Non-profits · Team settings"
        ],
        "summary": "Invite people to the team",
        "operationId": "inviteToNonprofit",
        "description": "nonprofit.team.manage. Up to 20 emails; each gets the org_invite email (link /nonprofits/invite/{token}, 30 days). Nobody grants above their own role. Audited as organization.invite_sent.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The organization's slug (requireOrgPermission resolves it)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "emails": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 20
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "admin",
                      "fundraiser",
                      "viewer",
                      "member"
                    ],
                    "description": "Never owner: ownership is transferred. The RBAC spelling (org_admin, ...) is accepted too."
                  },
                  "title": {
                    "type": "string",
                    "maxLength": 80
                  }
                },
                "required": [
                  "emails",
                  "role"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "created": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NonprofitInvite"
                      }
                    },
                    "skipped": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "email": {
                            "type": "string"
                          },
                          "reason": {
                            "type": "string",
                            "enum": [
                              "already_member",
                              "already_invited",
                              "invalid"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`above_own`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "422": {
            "description": "`emails`, `max` or `role`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/invites/{inviteId}/resend": {
      "post": {
        "tags": [
          "Non-profits · Team settings"
        ],
        "summary": "Resend an invite",
        "operationId": "resendNonprofitInvite",
        "description": "nonprofit.team.manage. A new token and 30 days; 5 sends at most.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The organization's slug (requireOrgPermission resolves it)."
          },
          {
            "name": "inviteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The invite id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitInvite"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`above_own`: the invite is for a role above the caller's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "409": {
            "description": "`max_sends`, `accepted`, `revoked` or `declined`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/invites/{inviteId}": {
      "delete": {
        "tags": [
          "Non-profits · Team settings"
        ],
        "summary": "Cancel an invite",
        "operationId": "revokeNonprofitInvite",
        "description": "Cancels an invite to the non-profit's team, so it can no longer be accepted. Cancelling one that is already cancelled changes nothing; one that was already accepted answers `409` `accepted`, and an id that is not one of this organization's invites `404`. Needs `nonprofit.team.manage` (the owner and admins), and an invite for a role above the caller's own answers `403` `above_own`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The organization's slug (requireOrgPermission resolves it)."
          },
          {
            "name": "inviteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The invite id."
          }
        ],
        "responses": {
          "204": {
            "description": "Done"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "409": {
            "description": "`accepted`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/join-requests/{requestId}/approve": {
      "post": {
        "tags": [
          "Non-profits · Team settings"
        ],
        "summary": "Approve a join request",
        "operationId": "approveNonprofitJoinRequest",
        "description": "nonprofit.team.manage. The person joins with the role and title and is emailed.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The organization's slug (requireOrgPermission resolves it)."
          },
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The request id."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "role": {
                    "type": "string",
                    "enum": [
                      "admin",
                      "fundraiser",
                      "viewer",
                      "member"
                    ],
                    "default": "member",
                    "description": "Optional; `member` when left out. Never owner: ownership is transferred. The RBAC spelling (org_admin, ...) is accepted too."
                  },
                  "title": {
                    "type": "string",
                    "maxLength": 80
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitTeamMember"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`above_own`: the role is above the caller's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "409": {
            "description": "Already decided.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "422": {
            "description": "`role` (not one of admin, fundraiser, viewer or member) or `title` (not text, or over 80 characters).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/join-requests/{requestId}/decline": {
      "post": {
        "tags": [
          "Non-profits · Team settings"
        ],
        "summary": "Decline a join request",
        "operationId": "declineNonprofitJoinRequest",
        "description": "Declines a pending request to join the non-profit's team; the person does not join. A request that was already decided or withdrawn answers `409` with its state as the code (`approved`, `declined` or `withdrawn`), and an id that is not one of this organization's requests `404`. Needs `nonprofit.team.manage` (the owner and admins).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The organization's slug (requireOrgPermission resolves it)."
          },
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The request id."
          }
        ],
        "responses": {
          "204": {
            "description": "Done"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "409": {
            "description": "Already decided.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/transfer-ownership": {
      "post": {
        "tags": [
          "Non-profits · Team settings"
        ],
        "summary": "Transfer ownership",
        "operationId": "transferNonprofitOwnership",
        "description": "The owner only, to one of the admins; the old owner becomes an admin. Audited as organization.ownership_transferred.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The organization's slug (requireOrgPermission resolves it)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "user_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "user_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "owner": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "previous_owner": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`not_owner`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          },
          "422": {
            "description": "`not_admin` or `self`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/verification": {
      "get": {
        "tags": [
          "Non-profits · Team settings"
        ],
        "summary": "Verification and tax status",
        "operationId": "getNonprofitVerification",
        "description": "org.read. The latest check per source, the documents (W-9 and bank documents only with org.upload_documents), the IRS record and how authority was shown.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The organization's slug (requireOrgPermission resolves it)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitVerification"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/org-admin/{slug}/verification/check-now": {
      "post": {
        "tags": [
          "Non-profits · Team settings"
        ],
        "summary": "Run every check now",
        "operationId": "checkNonprofitNow",
        "description": "org.update_settings. At most once an hour (else 429 `too_soon`). Answers as GET.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The organization's slug (requireOrgPermission resolves it)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitVerification"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "`too_soon`, with `details.retry_after_seconds`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NonprofitError"
                }
              }
            }
          }
        }
      }
    },
    "/resources/search": {
      "post": {
        "tags": [
          "Resources"
        ],
        "summary": "Find help",
        "operationId": "searchResources",
        "description": "Provider cards with their matching help, facets and the total. A city matches help whose service area is the city, one of its ZIP codes, its state or the whole country, or that has a location in it; a ZIP code or a point resolves to its city first. Order: open now first when `openNow` is asked for, then nearest (to the provider's nearest public storefront; online and confidential help have no distance), then the most recently confirmed. Nothing is paid or boosted. Help whose capacity is paused, and a private community's members-only help, are never listed. A search that finds nothing is counted by city and topic only. It is a POST so a sensitive topic never lands in a URL; the answer is sent `Cache-Control: no-store`.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResourceSearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceSearch"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "description": "`validation_error`, `unknown_city`, `unknown_zip` or `no_city_near`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourcePublicError"
                }
              }
            }
          }
        }
      }
    },
    "/resources/topics": {
      "get": {
        "tags": [
          "Resources"
        ],
        "summary": "List topics, needs and hotlines",
        "operationId": "listResourceTopics",
        "description": "\"What's going on?\": every active topic with its one sentence, reviewed first steps (at most 3), hotlines and needs, plus the hotlines and the urgent strip, in the reader's language (`lang`, then the language cookie, then `Accept-Language`; English otherwise). Cached for 60 seconds.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceTopics"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/resources/providers/{slug}": {
      "get": {
        "tags": [
          "Resources"
        ],
        "summary": "Read a provider's page",
        "operationId": "getResourceProvider",
        "description": "The provider's card, every resource the viewer may see (a private community's members-only help only for its active members), the places they happen (a street and a pin only for a public storefront no confidential help shares) and its verified licenses (holder, kind, state and the date checked). A provider with nothing public now answers `not_listed` with similar providers, never a 404. An old slug answers `301` to the current page. Cached for 60 seconds for a guest; never for a signed-in person.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceProviderPage"
                }
              }
            }
          },
          "301": {
            "description": "An old slug; `Location` is the current page."
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "No provider ever had this slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourcePublicError"
                }
              }
            }
          }
        }
      }
    },
    "/resources/for/{kind}/{entitySlug}": {
      "get": {
        "tags": [
          "Resources"
        ],
        "summary": "Read the help an organization, business or community offers",
        "operationId": "getResourcesForEntity",
        "description": "Up to `limit` resources for a page's \"Help we offer\" section, help for everyone first, with the total and the provider page's slug for See all. The same visibility as the provider page. An entity with no help the viewer may see answers an empty list.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "nonprofit",
                "church",
                "sponsor",
                "business",
                "community"
              ]
            }
          },
          {
            "name": "entitySlug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The non-profit's, business's or community's own slug."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 3,
              "maximum": 12
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceForEntity"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "description": "`unknown_kind`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourcePublicError"
                }
              }
            }
          }
        }
      }
    },
    "/resources/{id}/reports": {
      "post": {
        "tags": [
          "Resources"
        ],
        "summary": "Report a problem with a listing",
        "operationId": "reportResource",
        "description": "Wrong info, closed, unsafe, scam or other; signed out is allowed. One report per reporter, resource and day: a second answers `200` with the first (`duplicate: true`). At most 10 reports a day per reporter. Who reported is kept as a keyed hash, never the IP address. Unsafe and scam reports reach FundlyHub's on-call staff at once. Nothing is taken down automatically, and the reporter is never told the outcome.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string",
                    "enum": [
                      "wrong_info",
                      "closed",
                      "unsafe",
                      "scam",
                      "other"
                    ]
                  },
                  "note": {
                    "type": "string",
                    "maxLength": 500,
                    "nullable": true
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "nullable": true,
                    "description": "Signed out only."
                  }
                },
                "required": [
                  "reason"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The same report, made earlier today.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceReport"
                }
              }
            }
          },
          "201": {
            "description": "Reported.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceReport"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "No resource the caller may see has this id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourcePublicError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourcePublicError"
                }
              }
            }
          },
          "429": {
            "description": "`too_many_reports`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourcePublicError"
                }
              }
            }
          }
        }
      }
    },
    "/resources/suggestions": {
      "post": {
        "tags": [
          "Resources"
        ],
        "summary": "Suggest a place that helps",
        "operationId": "suggestResourceProvider",
        "description": "A name, a city and an optional website, US phone number, topics and note, for FundlyHub's staff to look into. Signed out is allowed, at most 5 a day per suggester.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 120
                  },
                  "city": {
                    "type": "string",
                    "description": "A city page's slug."
                  },
                  "website": {
                    "type": "string",
                    "nullable": true
                  },
                  "phone": {
                    "type": "string",
                    "nullable": true
                  },
                  "topics": {
                    "type": "array",
                    "maxItems": 5,
                    "items": {
                      "type": "string"
                    },
                    "nullable": true
                  },
                  "note": {
                    "type": "string",
                    "maxLength": 500,
                    "nullable": true
                  }
                },
                "required": [
                  "name",
                  "city"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Received.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "description": "`validation_error`, `unknown_city`, `invalid_phone` or `invalid_website`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourcePublicError"
                }
              }
            }
          },
          "429": {
            "description": "`too_many_suggestions`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourcePublicError"
                }
              }
            }
          }
        }
      }
    },
    "/me/resource-saves": {
      "get": {
        "tags": [
          "Resources"
        ],
        "summary": "List my saved providers",
        "operationId": "listResourceSaves",
        "description": "The providers the signed-in person saved, newest first (at most 200). Each comes with its card while it still has help the person may see; otherwise `listed` is false (\"No longer listed\") and there is no card. Only that person ever sees their saves: never cached, never shared, never in an event or an audit log.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceSaves"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/me/resource-saves/{providerId}": {
      "put": {
        "tags": [
          "Resources"
        ],
        "summary": "Save a provider",
        "operationId": "saveResourceProvider",
        "description": "Saves a provider for My help. Saving again changes nothing and answers the first save. Only a provider with help the person may see now can be saved (a private community's members-only help for its members); anything else is a `404`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "providerId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "saved": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "savedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "`not_found`: no provider the person may see has this id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourcePublicError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Resources"
        ],
        "summary": "Unsave a provider",
        "operationId": "unsaveResourceProvider",
        "description": "Removes the save. A provider that isn't saved is not an error.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Not saved now."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/sponsors": {
      "get": {
        "tags": [
          "Sponsors"
        ],
        "summary": "List sponsors",
        "operationId": "listSponsors",
        "description": "The sponsor directory: live or paused sponsors with a perk that is live, or ended less than 30 days ago. A city lists the sponsors with an open location whose address is in it, the same rule its \"14 sponsors\" counts by. Nearest first from `near` (a point the person chose to share; it only sorts), else from a signed-in viewer's own place, else by name. Each card leads with the perk the signed-in viewer can best use there, its state for them, and how many they can use; a guest sees neither. `viewer.usable` is the viewer's count over the whole city (the other filters aside). Without a city a signed-in viewer sees their own (`cityDefault`); `city=all` is every city.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "A city page's slug, or `all`. Absent: a signed-in viewer's own city, else every city."
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Category ids, comma separated (`coffee_cafe,bakery`)."
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 80
            },
            "description": "Part of the name, a name it trades under, one of its places' names (\"Midtown\") or one of its perks."
          },
          {
            "name": "near",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "38.5762,-121.4805"
            },
            "description": "`lat,lng` to sort from. Without it, a signed-in viewer's own place."
          },
          {
            "name": "can_use",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "1"
              ]
            },
            "description": "Signed in only - just the sponsors with a perk the viewer can use."
          },
          {
            "name": "open_now",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "1"
              ]
            },
            "description": "Just the sponsors with a storefront open now."
          },
          {
            "name": "nearby",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "1"
              ]
            },
            "description": "Just the sponsors with a storefront within 5 miles of the point (ignored without one)."
          },
          {
            "name": "new",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "1"
              ]
            },
            "description": "Just the sponsors approved in the last 30 days."
          },
          {
            "name": "online",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "1"
              ]
            },
            "description": "Just the sponsors that sell online (online only",
            "or a perk online).": null
          },
          {
            "name": "offers_help",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "1"
              ]
            },
            "description": "Just the ones with help in Find help (#2423). Ignored while Resources are switched off."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 24,
              "maximum": 48
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorDirectory"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "Sponsors · Become a sponsor"
        ],
        "summary": "Start a sponsor (a draft)",
        "operationId": "createSponsorDraft",
        "description": "A draft saved as you go; the person who starts it is its owner. At most three unfinished drafts per person. `ref` is an ambassador code from /sponsors/join?ref=. Needs a verified email. `is_sponsor: false` starts a business that only lists help in Resources (/resources/join, \"Add your business\"; #2422): the same steps and checks (who runs it, the registry, sanctions, the 25%-owners answer, the terms) with no first perk and no sticker kits, and its home a storefront or a service-area or online location (never a private storefront). While sponsors are off and Resources are on, such a business can still be started here, finish its steps and use its workspace (#2426); a sponsor's draft, and a sponsor's perks and stickers, answer 403 until sponsors are on.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 80
                  },
                  "category_id": {
                    "type": "string"
                  },
                  "ref": {
                    "type": "string"
                  },
                  "is_sponsor": {
                    "type": "boolean",
                    "default": true,
                    "description": "False for a business that only offers help (no perks, no stickers, never in /sponsors)."
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorJoinDraft"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "description": "`too_many_drafts`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          },
          "422": {
            "description": "`category_not_allowed` and field errors.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SponsorManageError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/categories": {
      "get": {
        "tags": [
          "Sponsors"
        ],
        "summary": "List sponsor categories",
        "operationId": "listSponsorCategories",
        "description": "The business categories in display order, each with its policy (`allowed`, `limited` - bars, breweries and wineries can't give perks on alcohol, pharmacies not on prescriptions -, or `not_allowed`) and the number of listed sponsors in it (in `city`, when given). Names are the site's translations of the id.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "A city page's slug."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PublicSponsorCategory"
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/sponsors/perks": {
      "get": {
        "tags": [
          "Sponsors"
        ],
        "summary": "Perks for one achievement card",
        "operationId": "listAchievementCardPerks",
        "description": "The perks of listed sponsors for one achievement, split at a card's tier: `unlocks` are the perks for that tier and below, `higher` counts the perks of each tier above with two examples, never how far the holder is from it. The card's code and QR are public and never unlock a perk; for a signed-in holder each perk carries their own eligibility.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "achievement",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The achievement's slug or id."
          },
          {
            "name": "tier",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "base",
                "bronze",
                "silver",
                "gold"
              ],
              "default": "base"
            }
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "near",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 4,
              "maximum": 24
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicCardPerks"
                }
              }
            }
          },
          "404": {
            "description": "No achievement perks can be for has this slug or id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error` (no achievement) or `invalid_tier`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}": {
      "get": {
        "tags": [
          "Sponsors"
        ],
        "summary": "Get a sponsor's page",
        "operationId": "getSponsorPage",
        "description": "A sponsor's page for the person looking: the business, its numbers (from the same views the workspace and the admin portal read; givers thanked from 5 up), its perks with the viewer's eligibility, its open locations, the latest updates, the team members shown on the page (never cashiers), what FundlyHub checked (only checks that passed), and the viewer block (following, their role on the team, whether they may open the workspace). The team and staff also get `teamWeek` and each perk's counted uses. A live, paused, suspended or closed sponsor is public; any other is visible to its team and to staff only, and answers `404` to anyone else. An old slug answers with the current one in `slug` and `renamed: true`. A closed sponsor's page is a record: no perks.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug, a slug it used to have, or its id."
          },
          {
            "name": "near",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "`lat,lng` for each location's distance (the browser's position, when the person allowed it). Without it, a signed-in viewer's own place on their profile is used; never a guess from the IP address."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorPage"
                }
              }
            }
          },
          "404": {
            "description": "No sponsor the caller may see has this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/perks": {
      "get": {
        "tags": [
          "Sponsors"
        ],
        "summary": "List a sponsor's perks",
        "operationId": "listSponsorPerks",
        "description": "The perks the public sees: live, paused and scheduled, and an ended one for 30 days; never one FundlyHub stopped or one not approved yet. Each with its availability for everyone and the viewer's eligibility.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug, a slug it used to have, or its id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorPerks"
                }
              }
            }
          },
          "404": {
            "description": "No sponsor the caller may see has this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/perks/{perkId}": {
      "get": {
        "tags": [
          "Sponsors"
        ],
        "summary": "Get one of a sponsor's perks",
        "operationId": "getSponsorPerk",
        "description": "One perk with where it works in store (each place's state today and any closure ahead), when it went live, and the viewer's eligibility. `404` for a perk of another sponsor, one the public doesn't see, or any perk of a closed sponsor.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug, a slug it used to have, or its id."
          },
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorPerk"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/locations": {
      "get": {
        "tags": [
          "Sponsors"
        ],
        "summary": "List a sponsor's locations",
        "operationId": "listSponsorLocations",
        "description": "The open locations, home first. A storefront shows its street address and map point; a business that comes to customers shows the ZIP codes it serves and never its address (often a home); an online-only business shows its city. Each with its weekly hours, whether it is open now, closed now or temporarily closed (in its city's time zone), a closure within 30 days, whether its address is confirmed, and which perks work there. A location closed for good is not listed.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug, a slug it used to have, or its id."
          },
          {
            "name": "near",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "`lat,lng` for each location's distance. Without it, a signed-in viewer's own place on their profile is used; never a guess from the IP address."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "locations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PublicSponsorLocation"
                      }
                    },
                    "perksByLocation": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    },
                    "team": {
                      "type": "boolean",
                      "description": "The viewer is on the team or staff (they see which addresses are not confirmed yet)."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No sponsor the caller may see has this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/impact": {
      "get": {
        "tags": [
          "Sponsors"
        ],
        "summary": "Get a sponsor's impact",
        "operationId": "getSponsorImpact",
        "description": "Counts, never dollars: perks used (in-store uses confirmed at the counter plus online codes handed out, minus any undone or voided), givers thanked (different people, from 5 up), followers and the new ones this week, sponsor since, and the uses by perk, by place (online apart) and by month in the home city's time zone, each adding up to the total. Never the gifts its customers made, which count as their own giving and their city's.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug, a slug it used to have, or its id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorImpact"
                }
              }
            }
          },
          "404": {
            "description": "No sponsor the caller may see has this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/updates": {
      "get": {
        "tags": [
          "Sponsors"
        ],
        "summary": "List a sponsor's updates",
        "operationId": "listSponsorUpdates",
        "description": "Updates on the page, newest first, with who posted each (a team member's name and role, FundlyHub, or posted automatically when a perk went live).",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug, a slug it used to have, or its id."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PublicSponsorUpdate"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No sponsor the caller may see has this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/follow": {
      "post": {
        "tags": [
          "Sponsors"
        ],
        "summary": "Follow a sponsor",
        "operationId": "followSponsor",
        "description": "Follows the sponsor and answers its follower count; following again changes nothing. A sponsor sees how many follow it, never who. A closed sponsor takes no new followers (`409` `sponsor_closed`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug, a slug it used to have, or its id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorFollow"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No sponsor the caller may see has this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          },
          "409": {
            "description": "`sponsor_closed`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Sponsors"
        ],
        "summary": "Unfollow a sponsor",
        "operationId": "unfollowSponsor",
        "description": "Stops following; always allowed, and a no-op when not following.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug, a slug it used to have, or its id."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorFollow"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No sponsor the caller may see has this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          }
        }
      }
    },
    "/sponsors/{key}/reports": {
      "post": {
        "tags": [
          "Sponsors"
        ],
        "summary": "Report wrong information",
        "operationId": "reportSponsorWrongInfo",
        "description": "Tells FundlyHub something on the page, or at one of its locations, is wrong. Staff handle it; the business never learns who reported. A second report of the same thing by the same person within a day answers `200` with the first one (`duplicate: true`). Needs a verified email. A perk that wasn't honored is reported from the use's receipt instead.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sponsor's slug, a slug it used to have, or its id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "wrong_info"
                    ]
                  },
                  "note": {
                    "type": "string",
                    "maxLength": 300,
                    "nullable": true
                  },
                  "locationId": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true,
                    "description": "One of the sponsor's open locations."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The same report, made within the last day.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorReport"
                }
              }
            }
          },
          "201": {
            "description": "Reported.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorReport"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No sponsor the caller may see has this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error` (a note over 300 characters) or `unknown_location`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          }
        }
      }
    },
    "/sticker/{code}": {
      "get": {
        "tags": [
          "Sponsors"
        ],
        "summary": "Read a Proud Sponsor sticker",
        "operationId": "getSticker",
        "description": "What fundlyhub.org/sticker/{code} says. Giving first: the Fundlies in the sticker's city (a gift goes to the Fundly, never to the business). Then `status`: `real` (the business, the location and the perks there, for this viewer), `replaced` (a lost or damaged sticker was reordered and its code stopped working), `location_closed`, `ended` (the business is no longer a sponsor), or `unknown` (no sticker has this code; it may be a copy). Someone on the team at the location also gets `team`, with whether they can confirm the address with this sticker.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "K7Q2MX"
            },
            "description": "The code printed in the sticker's QR (any case)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicStickerPage"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/sticker/{code}/confirm": {
      "post": {
        "tags": [
          "Sponsors"
        ],
        "summary": "Confirm a location's address with its sticker",
        "operationId": "confirmStickerAddress",
        "description": "Someone on the team who works at the sticker's location confirms its address: the sticker was mailed there. Each sticker confirms once, and an address that is already confirmed answers `409`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "K7Q2MX"
            },
            "description": "The code printed in the sticker's QR (any case)."
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "confirmed": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "confirmedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "locationId": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`not_on_team`: the caller is not on the team at this location.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          },
          "404": {
            "description": "No sticker has this code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          },
          "409": {
            "description": "`already_confirmed`, `sticker_replaced`, `location_closed` or `sponsor_ended`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          }
        }
      }
    },
    "/sticker/{code}/report": {
      "post": {
        "tags": [
          "Sponsors"
        ],
        "summary": "Report a sticker",
        "operationId": "reportSticker",
        "description": "A sticker that looks fake, or that is still up after it was replaced or its sponsor left. Kept with the code as scanned and, for a real sticker, its sponsor and location. Same one-a-day rule as other reports. Needs a verified email.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "K7Q2MX"
            },
            "description": "The code printed in the sticker's QR (any case)."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "note": {
                    "type": "string",
                    "maxLength": 300,
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The same report, made within the last day.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorReport"
                }
              }
            }
          },
          "201": {
            "description": "Reported.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorReport"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "description": "`invalid_code` or `validation_error`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          }
        }
      }
    },
    "/me/perks": {
      "get": {
        "tags": [
          "Sponsors"
        ],
        "summary": "My perks",
        "operationId": "listMyPerks",
        "description": "The signed-in person's perks at listed sponsors. `ready`: perks they qualify for (they hold the tier and its 7 days have passed), including ones used as often as they allow; `other`: perks for a tier they don't hold yet, or hold but still wait out; `saved`; `used`: their counted uses, newest first. `counts` covers every tab, `unlocking` groups the tiers whose wait is running with the day it ends. Perks of a sponsor they work for are never ready or other. With \"Show sponsor perks\" off (`show_sponsor_perks` in the user's preferences) ready and other are empty and `perksOff` is true.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "tab",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ready",
                "other",
                "saved",
                "used"
              ],
              "default": "ready"
            }
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "A city's slug, or `all`. Absent: the person's own city."
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "online",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "1"
              ]
            },
            "description": "Just the perks used online."
          },
          {
            "name": "near",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "`lat,lng` to sort from. Without it, the person's own place."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicMyPerks"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/me/perks/{perkId}/save": {
      "put": {
        "tags": [
          "Sponsors"
        ],
        "summary": "Save a perk",
        "operationId": "saveMyPerk",
        "description": "Adds a perk the public can see to My perks, Saved. Saving it again changes nothing.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "saved": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No perk the public can see has this id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Sponsors"
        ],
        "summary": "Unsave a perk",
        "operationId": "unsaveMyPerk",
        "description": "Removes a perk from Saved; always allowed.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "saved": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/me/perks/{perkId}/watch": {
      "put": {
        "tags": [
          "Sponsors"
        ],
        "summary": "Tell me when a perk's codes are back",
        "operationId": "watchMyPerk",
        "description": "\"Tell me when it's back\" under an online perk that is out of codes. When an upload takes the perk from no codes to some, the person is told once (bell and email) and the watch ends. Watching it again changes nothing.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "watching": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No online perk the public can see has this id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSponsorError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Sponsors"
        ],
        "summary": "Stop waiting for a perk's codes",
        "operationId": "unwatchMyPerk",
        "description": "Ends the watch; always allowed.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "perkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "watching": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/org-admin/{slug}/users": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "List donors and followers",
        "operationId": "listOrgAdminUsers",
        "description": "Distinct named donors and public followers are combined once per account. Donors are those of the organization's counted gifts (paid or refunded) to any of its fundraisers that is not deleted (unlisted, private and not-yet-approved ones included) or made directly to the non-profit (general fund and monthly); the Overview's and Analytics' figures count counted (approved, public) fundraisers only. Guest and anonymous gift identities remain separate. Follower-only records have zero gifts and no email or donation date. Gift filters match the donor's gifts while returned totals retain their entire organization history. Totals (\"Raised after card fees\", `total_amount_cents` and the per-currency `totals`) are what the donor's gifts raised, each gift at its ledger donation credit less its Stripe fee, never the tip, a refunded gift included at that amount; not the gross the donor paid. Requires organization permission `org.read_donors`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Organization slug; middleware resolves and authorizes this organization before any read or write.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 128
            },
            "description": "Search visible name, registered donor gift email or public city. Guest receipt emails are excluded."
          },
          {
            "name": "dateFrom",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Inclusive gift creation timestamp."
          },
          {
            "name": "dateTo",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Inclusive gift creation timestamp."
          },
          {
            "name": "amount",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^\\d{1,10}(\\.\\d{1,2})?$"
            },
            "description": "Exact gift amount in major units, without currency symbols."
          },
          {
            "name": "fundraiser",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 128
            },
            "description": "Fundraiser title contains this text."
          },
          {
            "name": "following",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "yes",
                "no",
                "na"
              ]
            },
            "description": "Following, not following, or not applicable for guest/anonymous records."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful organization-scoped response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "donor_key": {
                            "type": "string",
                            "description": "Opaque public identity; anonymous keys never expose an account id."
                          },
                          "donor_detail_id": {
                            "type": "string",
                            "format": "uuid",
                            "nullable": true,
                            "description": "An organization-owned gift id for donor detail."
                          },
                          "follower_user_id": {
                            "type": "string",
                            "format": "uuid",
                            "nullable": true
                          },
                          "donor_display_name": {
                            "type": "string"
                          },
                          "donor_avatar": {
                            "type": "string",
                            "nullable": true
                          },
                          "donor_email": {
                            "type": "string",
                            "nullable": true,
                            "description": "Gift-provided contact only; absent for anonymous and follower-only records."
                          },
                          "donor_city": {
                            "type": "string",
                            "nullable": true
                          },
                          "is_anonymous": {
                            "type": "boolean"
                          },
                          "is_following": {
                            "type": "boolean",
                            "nullable": true,
                            "description": "Null for anonymous and guest identities."
                          },
                          "donation_count": {
                            "type": "integer"
                          },
                          "totals": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "currency": {
                                  "type": "string"
                                },
                                "amount_cents": {
                                  "oneOf": [
                                    {
                                      "type": "integer"
                                    },
                                    {
                                      "type": "string",
                                      "pattern": "^-?\\d+$"
                                    }
                                  ]
                                }
                              }
                            }
                          },
                          "last_donated_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Organization permission missing, or action forbidden during impersonation"
          },
          "404": {
            "description": "Resource not found in this organization"
          },
          "503": {
            "description": "Upstream or data source temporarily unavailable; retry without changing the draft"
          }
        }
      }
    },
    "/org-admin/{slug}/users/followers/{userId}": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Read an organization follower",
        "operationId": "getOrgAdminFollower",
        "description": "The account must follow this organization. If it also has identified counted gifts (paid or refunded), its scoped giving history is returned, with totals as in the donor detail (what the gifts raised, net of the Stripe fee). Follower-only email is never disclosed. Requires organization permission `org.read_donors`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Organization slug; middleware resolves and authorizes this organization before any read or write.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful organization-scoped response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "donor_key": {
                          "type": "string",
                          "description": "Opaque public identity; anonymous keys never expose an account id."
                        },
                        "donor_detail_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true,
                          "description": "An organization-owned gift id for donor detail."
                        },
                        "follower_user_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true
                        },
                        "donor_display_name": {
                          "type": "string"
                        },
                        "donor_avatar": {
                          "type": "string",
                          "nullable": true
                        },
                        "donor_email": {
                          "type": "string",
                          "nullable": true,
                          "description": "Gift-provided contact only; absent for anonymous and follower-only records."
                        },
                        "donor_city": {
                          "type": "string",
                          "nullable": true
                        },
                        "is_anonymous": {
                          "type": "boolean"
                        },
                        "is_following": {
                          "type": "boolean",
                          "nullable": true,
                          "description": "Null for anonymous and guest identities."
                        },
                        "donation_count": {
                          "type": "integer"
                        },
                        "totals": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "currency": {
                                "type": "string"
                              },
                              "amount_cents": {
                                "oneOf": [
                                  {
                                    "type": "integer"
                                  },
                                  {
                                    "type": "string",
                                    "pattern": "^-?\\d+$"
                                  }
                                ]
                              }
                            }
                          }
                        },
                        "last_donated_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "donations": {
                          "type": "array",
                          "description": "The donor's giving history at this organization, most recent first (at most 100).",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "amount_cents": {
                                "type": "integer",
                                "description": "The gift the donor was charged for, in CENTS, before the card fee."
                              },
                              "raised_cents": {
                                "type": "string",
                                "pattern": "^-?\\d+$",
                                "description": "What this gift raised for the organization after the card fee, in integer CENTS as a JSON string: its ledger donation credit less its Stripe fee, never the tip, a refunded gift included. The per-gift figure the donor's `totals` sum."
                              },
                              "currency": {
                                "type": "string"
                              },
                              "created_at": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "comment": {
                                "type": "string",
                                "nullable": true
                              },
                              "fundraiser_id": {
                                "type": "string",
                                "format": "uuid",
                                "nullable": true,
                                "description": "Null for a gift made directly to the non-profit (general fund, monthly)."
                              },
                              "fundraiser_title": {
                                "type": "string",
                                "nullable": true
                              },
                              "fundraiser_slug": {
                                "type": "string",
                                "nullable": true
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Organization permission missing, or action forbidden during impersonation"
          },
          "404": {
            "description": "Resource not found in this organization"
          },
          "503": {
            "description": "Upstream or data source temporarily unavailable; retry without changing the draft"
          }
        }
      }
    },
    "/org-admin/{slug}/donors/{donorId}": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Read a donor and their gifts",
        "operationId": "getOrgAdminDonor",
        "description": "The donorId is one of the organization's counted donation ids (paid or refunded, to any of its fundraisers that is not deleted, or made directly to the non-profit) anchoring the donor identity, so every paid or refunded gift's detail links to a donor. Arbitrary account ids cannot be used to browse profiles. A gift made directly to the non-profit has null fundraiser fields. Totals (\"Raised after card fees\") are grouped by currency and are what the donor's gifts raised, each gift at its ledger donation credit less its Stripe fee, never the tip, a refunded gift included at that amount. Each listed gift (the 100 most recent) carries that same per-gift figure as `raised_cents`, so a donor's history adds up to the total; its `amount_cents` is the amount the donor was charged for, before the fee, which the gift's own detail and receipt show. Requires organization permission `org.read_donors`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Organization slug; middleware resolves and authorizes this organization before any read or write.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "donorId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful organization-scoped response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "donor_key": {
                          "type": "string",
                          "description": "Opaque public identity; anonymous keys never expose an account id."
                        },
                        "donor_detail_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true,
                          "description": "An organization-owned gift id for donor detail."
                        },
                        "follower_user_id": {
                          "type": "string",
                          "format": "uuid",
                          "nullable": true
                        },
                        "donor_display_name": {
                          "type": "string"
                        },
                        "donor_avatar": {
                          "type": "string",
                          "nullable": true
                        },
                        "donor_email": {
                          "type": "string",
                          "nullable": true,
                          "description": "Gift-provided contact only; absent for anonymous and follower-only records."
                        },
                        "donor_city": {
                          "type": "string",
                          "nullable": true
                        },
                        "is_anonymous": {
                          "type": "boolean"
                        },
                        "is_following": {
                          "type": "boolean",
                          "nullable": true,
                          "description": "Null for anonymous and guest identities."
                        },
                        "donation_count": {
                          "type": "integer"
                        },
                        "totals": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "currency": {
                                "type": "string"
                              },
                              "amount_cents": {
                                "oneOf": [
                                  {
                                    "type": "integer"
                                  },
                                  {
                                    "type": "string",
                                    "pattern": "^-?\\d+$"
                                  }
                                ]
                              }
                            }
                          }
                        },
                        "last_donated_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "donations": {
                          "type": "array",
                          "description": "The donor's giving history at this organization, most recent first (at most 100).",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "amount_cents": {
                                "type": "integer",
                                "description": "The gift the donor was charged for, in CENTS, before the card fee."
                              },
                              "raised_cents": {
                                "type": "string",
                                "pattern": "^-?\\d+$",
                                "description": "What this gift raised for the organization after the card fee, in integer CENTS as a JSON string: its ledger donation credit less its Stripe fee, never the tip, a refunded gift included. The per-gift figure the donor's `totals` sum."
                              },
                              "currency": {
                                "type": "string"
                              },
                              "created_at": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "comment": {
                                "type": "string",
                                "nullable": true
                              },
                              "fundraiser_id": {
                                "type": "string",
                                "format": "uuid",
                                "nullable": true,
                                "description": "Null for a gift made directly to the non-profit (general fund, monthly)."
                              },
                              "fundraiser_title": {
                                "type": "string",
                                "nullable": true
                              },
                              "fundraiser_slug": {
                                "type": "string",
                                "nullable": true
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Organization permission missing, or action forbidden during impersonation"
          },
          "404": {
            "description": "Resource not found in this organization"
          },
          "503": {
            "description": "Upstream or data source temporarily unavailable; retry without changing the draft"
          }
        }
      }
    },
    "/org-admin/{slug}/donations/{id}": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Read donation details and receipt history",
        "operationId": "getOrgAdminDonation",
        "description": "The donation must belong to a non-deleted fundraiser in this organization, or be a gift made directly to this non-profit (general fund or monthly; its fundraiser fields are null). Anonymous identity display stays masked, and for an anonymous gift the receipt email, city and country are null for every organization role. The donor's receipt id and PaymentIntent are never returned. Receipt history includes delivery state, destination and sent timestamp; the destination is shown only when it is the gift's own contact (null otherwise, and always null for an anonymous gift). Requires organization permission `org.read_donations`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Organization slug; middleware resolves and authorizes this organization before any read or write.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful organization-scoped response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "amount_cents": {
                          "oneOf": [
                            {
                              "type": "integer"
                            },
                            {
                              "type": "string",
                              "pattern": "^-?\\d+$"
                            }
                          ]
                        },
                        "currency": {
                          "type": "string"
                        },
                        "donor_display_name": {
                          "type": "string"
                        },
                        "donor_avatar": {
                          "type": "string",
                          "nullable": true
                        },
                        "anonymous_key": {
                          "type": "string",
                          "nullable": true
                        },
                        "donor_city": {
                          "type": "string",
                          "nullable": true,
                          "description": "Null for an anonymous gift."
                        },
                        "donor_country": {
                          "type": "string",
                          "nullable": true,
                          "description": "Null for an anonymous gift."
                        },
                        "receipt_email": {
                          "type": "string",
                          "nullable": true,
                          "description": "The gift's own contact; null for an anonymous gift."
                        },
                        "receipt_history": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "recipient_email": {
                                "type": "string",
                                "nullable": true,
                                "description": "Shown only when the receipt went to the gift's own contact."
                              },
                              "subject": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "created_at": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "sent_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                              }
                            }
                          }
                        },
                        "can_send_receipt": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Organization permission missing, or action forbidden during impersonation"
          },
          "404": {
            "description": "Resource not found in this organization"
          },
          "503": {
            "description": "Upstream or data source temporarily unavailable; retry without changing the draft"
          }
        }
      }
    },
    "/org-admin/{slug}/donations/{id}/receipt": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Preview a donation receipt",
        "operationId": "getOrgAdminDonationReceipt",
        "description": "Read-only donation receipt preview for one of this organization's donations, including gifts made directly to the non-profit. Never includes the donor's receipt id (their bearer capability for the public receipt endpoints). An anonymous gift's address is withheld. Requires organization permission `org.read_donations`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Organization slug; middleware resolves and authorizes this organization before any read or write.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Receipt fields in integer cents, with anonymous names masked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "donation_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "currency": {
                      "type": "string",
                      "example": "USD"
                    },
                    "amount_cents": {
                      "type": "integer"
                    },
                    "tip_amount_cents": {
                      "type": "integer"
                    },
                    "fee_amount_cents": {
                      "type": "integer"
                    },
                    "net_amount_cents": {
                      "type": "integer"
                    },
                    "total_charged_cents": {
                      "type": "integer",
                      "description": "`amount_cents + tip_amount_cents`."
                    },
                    "payment_status": {
                      "type": "string",
                      "nullable": true
                    },
                    "fundraiser_id": {
                      "type": "string",
                      "format": "uuid",
                      "nullable": true
                    },
                    "fundraiser_title": {
                      "type": "string",
                      "nullable": true,
                      "description": "Who the receipt says the gift went to, as the automatic receipt does; the Fundly's title, or the non-profit's name for a gift made directly to it, including a pending reservation. Null only when the target cannot be established; this name is not a tax acknowledgment."
                    },
                    "fundraiser_slug": {
                      "type": "string",
                      "nullable": true
                    },
                    "receipt_context": {
                      "$ref": "#/components/schemas/DonationReceiptContext"
                    },
                    "donor_name": {
                      "type": "string",
                      "description": "The name the receipt uses — `Valued Donor` for anonymous gifts."
                    },
                    "is_anonymous": {
                      "type": "boolean"
                    },
                    "donor_email": {
                      "type": "string",
                      "nullable": true,
                      "description": "The address on file; null when there is none or when the gift is anonymous."
                    },
                    "has_email_on_file": {
                      "type": "boolean",
                      "description": "Whether a send to the address on file can work, even when the address is withheld."
                    },
                    "can_choose_recipient": {
                      "type": "boolean",
                      "description": "Always false here; an organization sends only to the address on file."
                    },
                    "times_sent": {
                      "type": "integer"
                    },
                    "sendable": {
                      "type": "boolean",
                      "description": "Whether a send would succeed now (the donation is paid)."
                    },
                    "reason": {
                      "type": "string",
                      "nullable": true,
                      "description": "Why it is not sendable; null when `sendable` is true."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Organization permission missing, or action forbidden during impersonation"
          },
          "404": {
            "description": "Resource not found in this organization"
          },
          "503": {
            "description": "Upstream or data source temporarily unavailable; retry without changing the draft"
          }
        }
      }
    },
    "/org-admin/{slug}/donations/{id}/receipt-emails/{emailId}": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Inspect a receipt email",
        "operationId": "getOrgAdminReceiptEmail",
        "description": "Only receipt emails tied to this donation are available. Account tokens, unsubscribe capabilities, the donor's receipt id and PaymentIntent links, and private anonymous greeting names are removed from the inspection view. The recipient address is shown only when it is the gift's own contact, and never for an anonymous gift. Requires organization permission `org.read_donations`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Organization slug; middleware resolves and authorizes this organization before any read or write.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "emailId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful organization-scoped response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "recipient_email": {
                          "type": "string",
                          "nullable": true,
                          "description": "Null unless the receipt went to the gift's own contact; always null for an anonymous gift."
                        },
                        "subject": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "sent_at": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true
                        },
                        "html_body": {
                          "type": "string",
                          "nullable": true
                        },
                        "text_body": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Organization permission missing, or action forbidden during impersonation"
          },
          "404": {
            "description": "Resource not found in this organization"
          },
          "503": {
            "description": "Upstream or data source temporarily unavailable; retry without changing the draft"
          }
        }
      }
    },
    "/org-admin/{slug}/donations/{id}/receipt/email": {
      "post": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Send or resend the donor receipt",
        "operationId": "sendOrgAdminDonationReceipt",
        "description": "Queues the paid donation receipt to its address on file, and only there; a request carrying recipient_email is refused (403, refusal `recipient_locked`), so an organization can never mail itself the donor's receipt. For an anonymous gift the address is used but not echoed back (`recipient` is null). Receipt amounts and donor language always come from the saved donation, and the receipt names the gift's recipient as the automatic receipt does (its Fundly, or the non-profit for a general-fund or monthly gift). The send is audit-logged, sends are rate-limited, and impersonated sessions cannot send. Nonprofit receipts requiring recovery review cannot be resent. Requires organization permission `org.update_settings`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Organization slug; middleware resolves and authorizes this organization before any read or write.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful organization-scoped response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "sent": {
                          "type": "boolean"
                        },
                        "status": {
                          "type": "string"
                        },
                        "recipient": {
                          "type": "string",
                          "nullable": true,
                          "description": "The address it went to; null for an anonymous gift."
                        },
                        "times_sent": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Organization permission missing, action forbidden during impersonation, or a recipient_email was sent (refusal `recipient_locked`)"
          },
          "404": {
            "description": "Resource not found in this organization"
          },
          "503": {
            "description": "Upstream or data source temporarily unavailable; retry without changing the draft"
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "recipient_email": {
                    "type": "string",
                    "format": "email",
                    "description": "Not accepted from an organization (403 `recipient_locked`); omit it to send to the address on file."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/analytics": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Read fundraising and audience analytics",
        "operationId": "getOrgAdminAnalytics",
        "description": "Raised, gifts and donors are over the organization's counted gifts, the same gifts as the Overview and the non-profit Home's month card (paid or refunded, to its counted fundraisers or made directly to the non-profit), in the range. Supporters list the donors of a wider set (any fundraiser of the organization that is not deleted, unlisted, private and not-yet-approved ones included). Raised money uses the shared ledger net-of-fees definition and stays grouped by currency; donors are distinct by the shared donor identity. In `fundraisers`, the row whose `id` is null is the general fund. GA4 audience data is restricted to organization and fundraiser page paths. Geography contains approximate city aggregates, not donor identities or street addresses. Requires organization permission `org.read_donations`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Organization slug; middleware resolves and authorizes this organization before any read or write.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "range",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "28d"
            },
            "description": "Existing analytics range such as 7d, 28d, 90d or alltime; custom dates use the analytics range format."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful organization-scoped response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "range": {
                          "type": "string"
                        },
                        "from": {
                          "type": "string",
                          "format": "date"
                        },
                        "to": {
                          "type": "string",
                          "format": "date"
                        },
                        "donors": {
                          "type": "integer"
                        },
                        "totals": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "currency": {
                                "type": "string"
                              },
                              "gifts": {
                                "type": "integer"
                              },
                              "donors": {
                                "type": "integer"
                              },
                              "raised_cents": {
                                "oneOf": [
                                  {
                                    "type": "integer"
                                  },
                                  {
                                    "type": "string",
                                    "pattern": "^-?\\d+$"
                                  }
                                ]
                              }
                            }
                          }
                        },
                        "trend": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "date": {
                                "type": "string",
                                "format": "date"
                              },
                              "currency": {
                                "type": "string"
                              },
                              "raised_cents": {
                                "oneOf": [
                                  {
                                    "type": "integer"
                                  },
                                  {
                                    "type": "string",
                                    "pattern": "^-?\\d+$"
                                  }
                                ]
                              },
                              "gifts": {
                                "type": "integer"
                              }
                            }
                          }
                        },
                        "geography": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "city": {
                                "type": "string"
                              },
                              "country": {
                                "type": "string",
                                "nullable": true
                              },
                              "gifts": {
                                "type": "integer"
                              },
                              "lat": {
                                "type": "number",
                                "nullable": true
                              },
                              "lng": {
                                "type": "number",
                                "nullable": true
                              }
                            }
                          }
                        },
                        "fundraisers": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {}
                          }
                        },
                        "audience": {
                          "type": "object",
                          "properties": {},
                          "nullable": true
                        },
                        "ga_status": {
                          "type": "string",
                          "enum": [
                            "available",
                            "unavailable"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Organization permission missing, or action forbidden during impersonation"
          },
          "404": {
            "description": "Resource not found in this organization"
          },
          "503": {
            "description": "Upstream or data source temporarily unavailable; retry without changing the draft"
          }
        }
      }
    },
    "/org-admin/{slug}/funds": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Read organization balances and payout configuration",
        "operationId": "getOrgAdminFunds",
        "description": "Reads the organization's own Stripe Connect account and ledger. Available bank balance, unsettled processing, platform-held gifts and bank payouts are separate; no member's personal balance is used. Requires organization permission `org.read_payouts`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Organization slug; middleware resolves and authorizes this organization before any read or write.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful organization-scoped response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "connected": {
                          "type": "boolean"
                        },
                        "ready": {
                          "type": "boolean"
                        },
                        "canManage": {
                          "type": "boolean"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "balances": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "currency": {
                                "type": "string"
                              },
                              "totalRaisedCents": {
                                "type": "integer"
                              },
                              "processingCents": {
                                "type": "integer"
                              },
                              "availableCents": {
                                "type": "integer"
                              },
                              "transferredCents": {
                                "type": "integer"
                              },
                              "heldCents": {
                                "type": "integer"
                              },
                              "settlingCents": {
                                "type": "integer"
                              },
                              "readyForReleaseCents": {
                                "type": "integer"
                              }
                            }
                          }
                        },
                        "requirements": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "methods": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {}
                          }
                        },
                        "schedule": {
                          "type": "object",
                          "properties": {},
                          "nullable": true
                        },
                        "payouts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {}
                          }
                        },
                        "hasMorePayouts": {
                          "type": "boolean"
                        },
                        "heldCampaigns": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {}
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Organization permission missing, or action forbidden during impersonation"
          },
          "404": {
            "description": "Resource not found in this organization"
          },
          "503": {
            "description": "Upstream or data source temporarily unavailable; retry without changing the draft"
          }
        }
      }
    },
    "/org-admin/{slug}/funds/processing": {
      "get": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Read the organization processing breakdown",
        "operationId": "getOrgAdminFundsProcessing",
        "description": "Read-only settlement estimates and held-gift breakdown. Requires organization permission `org.read_payouts`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Organization slug; middleware resolves and authorizes this organization before any read or write.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "currency",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "USD"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful organization-scoped response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "currency": {
                          "type": "string"
                        },
                        "total_cents": {
                          "type": "integer"
                        },
                        "donations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {}
                          }
                        },
                        "release_schedule": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {}
                          }
                        },
                        "dates_from_stripe": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Organization permission missing, or action forbidden during impersonation"
          },
          "404": {
            "description": "Resource not found in this organization"
          },
          "503": {
            "description": "Upstream or data source temporarily unavailable; retry without changing the draft"
          }
        }
      }
    },
    "/org-admin/{slug}/funds/payouts": {
      "post": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Transfer available organization funds to its bank",
        "operationId": "createOrgAdminBankPayout",
        "description": "Creates a bank payout from the organization's own connected account and writes its payout ledger mapping. Reusing requestId retains the fixed amount and Stripe idempotency key. Requests must be fresh and within the available bank balance; held processing funds are not transferable. Impersonation is rejected. Requires organization permission `org.manage_payouts`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Organization slug; middleware resolves and authorizes this organization before any read or write.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful organization-scoped response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "amountCents": {
                          "type": "integer"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Organization permission missing, or action forbidden during impersonation"
          },
          "404": {
            "description": "Resource not found in this organization"
          },
          "503": {
            "description": "Upstream or data source temporarily unavailable; retry without changing the draft"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amountCents": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "currency": {
                    "type": "string",
                    "pattern": "^[A-Za-z]{3}$"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "requestedAt": {
                    "type": "integer",
                    "description": "Client timestamp in epoch milliseconds; expires after ten minutes."
                  }
                },
                "required": [
                  "amountCents",
                  "currency",
                  "requestId",
                  "requestedAt"
                ]
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/funds/schedule": {
      "put": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Update the organization payout schedule",
        "operationId": "updateOrgAdminPayoutSchedule",
        "description": "Updates only this organization's Stripe account. Weekly and monthly schedules require their matching anchor. Impersonation is rejected. Requires organization permission `org.manage_payouts`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Organization slug; middleware resolves and authorizes this organization before any read or write.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful organization-scoped response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "interval": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Organization permission missing, or action forbidden during impersonation"
          },
          "404": {
            "description": "Resource not found in this organization"
          },
          "503": {
            "description": "Upstream or data source temporarily unavailable; retry without changing the draft"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "interval": {
                    "type": "string",
                    "enum": [
                      "manual",
                      "daily",
                      "weekly",
                      "monthly"
                    ]
                  },
                  "weeklyAnchor": {
                    "type": "string",
                    "enum": [
                      "monday",
                      "tuesday",
                      "wednesday",
                      "thursday",
                      "friday",
                      "saturday",
                      "sunday"
                    ]
                  },
                  "monthlyAnchor": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 31
                  }
                },
                "required": [
                  "interval"
                ]
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/funds/dashboard": {
      "post": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Open the organization Stripe dashboard",
        "operationId": "createOrgAdminStripeDashboardLink",
        "description": "Creates a short-lived dashboard link for the organization's connected account. Impersonation is rejected. Requires organization permission `org.manage_payouts`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Organization slug; middleware resolves and authorizes this organization before any read or write.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful organization-scoped response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Organization permission missing, or action forbidden during impersonation"
          },
          "404": {
            "description": "Resource not found in this organization"
          },
          "503": {
            "description": "Upstream or data source temporarily unavailable; retry without changing the draft"
          }
        }
      }
    },
    "/creator-hub/schema": {
      "get": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "Read engine schemas",
        "description": "Authoritative v1 JSON Schemas for template and project inputs, format/fact keys and limits. Tokens use the same permissions as their owner.",
        "operationId": "creatorHubReadEngineSchemas",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        }
      }
    },
    "/creator-hub/templates": {
      "get": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "List templates",
        "description": "Lightweight metadata only: items and opaque nextCursor. Community attribution comes from profiles.name; built-ins use FundlyHub. No private templates of other accounts are included.",
        "operationId": "creatorHubListTemplates",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "parameters": [
          {
            "name": "collection",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "fundlyhub",
                "community",
                "mine"
              ]
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "topic",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "post",
                "carousel",
                "story",
                "reel"
              ]
            }
          }
        ]
      },
      "post": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "Create private template",
        "description": "Creates a private immutable version 1. Client attribution fields are not accepted inside a definition. Image defaults cannot be published. The template limit is 200 per account.",
        "operationId": "creatorHubCreatePrivateTemplate",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "definition"
                ],
                "properties": {
                  "definition": {
                    "$ref": "#/components/schemas/CreatorHubTemplateV1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/creator-hub/templates/{id}": {
      "get": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "Read template version",
        "description": "Owner can read their drafts. Others can read previously published immutable versions only while the template remains public.",
        "operationId": "creatorHubReadTemplateVersion",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ]
      }
    },
    "/creator-hub/templates/{id}/versions": {
      "post": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "Create template version",
        "description": "Owner only. baseVersion must be the current latest version; publication is unchanged.",
        "operationId": "creatorHubCreateTemplateVersion",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "baseVersion",
                  "definition"
                ],
                "properties": {
                  "baseVersion": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "definition": {
                    "$ref": "#/components/schemas/CreatorHubTemplateV1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/creator-hub/templates/{id}/publish": {
      "post": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "Publish template version",
        "description": "Owner only. Explicitly publish an immutable version, or send null to unpublish. New edits never alter the existing public version.",
        "operationId": "creatorHubPublishTemplateVersion",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "version"
                ],
                "properties": {
                  "version": {
                    "type": "integer",
                    "minimum": 1,
                    "nullable": true
                  }
                }
              }
            }
          }
        }
      }
    },
    "/creator-hub/campaigns": {
      "get": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "Find usable campaigns",
        "description": "Mine lists owned campaigns or campaigns of the org authorized by org.read. Platform lists approved active public campaigns. Results contain items and nextOffset.",
        "operationId": "creatorHubFindUsableCampaigns",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "parameters": [
          {
            "name": "collection",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "mine",
                "platform"
              ]
            }
          },
          {
            "name": "org",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ]
      }
    },
    "/creator-hub/campaigns/{id}": {
      "get": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "Read campaign source",
        "description": "Fresh permitted story, photos, link, public facts, public endorsers with names and processed avatars, percentage and source revision. Uses normal campaign/organization read permissions; no donor emails or private identities. Moderated/processing assets are excluded.",
        "operationId": "creatorHubReadCampaignSource",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/creator-hub/directory/organizations": {
      "get": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "Search system organizations",
        "description": "Publicly listed approved/verified organizations and their canonical names/logos.",
        "operationId": "creatorHubSearchSystemOrganizations",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Resolve a saved organization outside the first search page.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/creator-hub/directory/achievements": {
      "get": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "List system achievements",
        "description": "Public system achievement slugs and names, excluding hidden or unpublished definitions.",
        "operationId": "creatorHubListSystemAchievements",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        }
      }
    },
    "/creator-hub/directory/achievements/{slug}/art": {
      "get": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "Read achievement artwork",
        "description": "Rasterized cut-out of a public system achievement for the composer.",
        "operationId": "creatorHubReadAchievementArtwork",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/creator-hub/projects": {
      "get": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "List owned projects",
        "description": "Owner-only private projects. Returns items and nextOffset.",
        "operationId": "creatorHubListOwnedProjects",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "parameters": [
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ]
      },
      "post": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "Create private project",
        "description": "Validates template version, campaign access and image ownership. Missing sourceRevision captures the current permitted source; a provided stale revision returns 409.",
        "operationId": "creatorHubCreatePrivateProject",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatorHubProjectV1"
              }
            }
          }
        }
      }
    },
    "/creator-hub/projects/{id}": {
      "get": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "Read owned project",
        "description": "Returns id, body, revision, source_revision and updated_at. No other user can read the draft by guessing its ID.",
        "operationId": "creatorHubReadOwnedProject",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "patch": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "Update owned project",
        "description": "Optimistic concurrency: revision must match the current saved record.",
        "operationId": "creatorHubUpdateOwnedProject",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "revision",
                  "project"
                ],
                "properties": {
                  "revision": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "project": {
                    "$ref": "#/components/schemas/CreatorHubProjectV1"
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "Delete owned project",
        "description": "Soft-deletes the draft and prevents future downloads of its exports.",
        "operationId": "creatorHubDeleteOwnedProject",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/creator-hub/preview": {
      "post": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "Render validated preview",
        "description": "Optional read-shaped render. Returns a base64 SVG data URL and sourceRevision. Native editing uses the same engine locally. Limited to 30 previews/minute/account.",
        "operationId": "creatorHubRenderValidatedPreview",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "project"
                ],
                "properties": {
                  "project": {
                    "$ref": "#/components/schemas/CreatorHubProjectV1"
                  },
                  "slide": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 19
                  }
                }
              }
            }
          }
        }
      }
    },
    "/creator-hub/projects/{id}/exports": {
      "post": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "Queue private PNG export",
        "description": "Exports one saved slide. Supply Idempotency-Key (recommended) or idempotencyKey in the body. Reusing a key for different input returns 409; identical retries return the same job. Current project/source revisions and permissions are required. Four pending jobs/account, 60 exports/hour/account.",
        "operationId": "creatorHubQueuePrivatePngExport",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "202": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "revision"
                ],
                "properties": {
                  "revision": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "slide": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 19,
                    "default": 0
                  },
                  "idempotencyKey": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  }
                }
              }
            }
          }
        }
      }
    },
    "/creator-hub/exports/{id}": {
      "get": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "Read export status",
        "description": "Owner-only queued/running/succeeded/failed state, error and expiry. Poll until terminal.",
        "operationId": "creatorHubReadExportStatus",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/creator-hub/exports/{id}/download": {
      "get": {
        "tags": [
          "Creator Hub"
        ],
        "summary": "Download private PNG",
        "description": "Owner-only binary. Expires after 24 hours and rechecks source/template permissions and saved revision. No public CDN URL is issued.",
        "operationId": "creatorHubDownloadPrivatePng",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Resource unavailable to this account"
          },
          "409": {
            "description": "Revision/source changed or retry key conflicts"
          },
          "422": {
            "description": "Invalid definition or project; details are returned in issues"
          },
          "429": {
            "description": "Request, queue or storage limit reached"
          },
          "503": {
            "description": "Rendering temporarily busy; retry later"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/free-stuff": {
      "get": {
        "tags": [
          "Free stuff"
        ],
        "summary": "Browse free stuff near a place",
        "operationId": "browseFreeStuff",
        "description": "Available items, nearest first from `near` (the browser's position, sent once the person allows it), else the city's center, else the signed-in person's own place; newest first with no point. Each shows the area and a distance band, never the pickup address or a pin. A city with nothing of its own shows what is within 25 miles, with `nearby: true`. A person the giver blocked never sees the giver's items. No account needed.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "A city's slug."
          },
          {
            "name": "near",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "38.68,-121.18"
            },
            "description": "lat,lng of the browser."
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "baby_kids,kitchen"
            },
            "description": "Category ids, comma-separated."
          },
          {
            "name": "distance",
            "in": "query",
            "schema": {
              "type": "number",
              "example": 5
            },
            "description": "Within this many miles of the point (1, 2, 5, 10 or 25 in the filters)."
          },
          {
            "name": "pickup",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "porch,public_place"
            },
            "description": "Pickup methods; an item offering any of them matches."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 24,
              "maximum": 48
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Items.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FreeItemCard"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "city": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "slug": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "region": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    },
                    "nearby": {
                      "type": "boolean",
                      "description": "The city had nothing; these are within 25 miles of it."
                    },
                    "from": {
                      "type": "string",
                      "nullable": true,
                      "enum": [
                        "near",
                        "city",
                        "profile"
                      ],
                      "description": "What the distances are measured from."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`unknown_city`, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Free stuff"
        ],
        "summary": "Give something away",
        "operationId": "postFreeItem",
        "description": "Posts an item. The automatic checks run on the title, description and category: a currency amount or a not-allowed item refuses it (`422 not_allowed`, with `details.reasons[]`: `rule`, `field`, `term`, `match`, and `topic: pets` for live animals); a borderline match holds it for review. A person's first post is held too (\"Held for review, usually within a day\"); anything else is available at once. Photos come from `POST /storage/upload` (bucket `free-stuff-photos`), 1 to 6. Posting as a provider needs to be able to manage it; after 3 posts as the same provider in 30 days the answer carries `nudge`. 10 posts a person a day.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FreeItemInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Posted: the giver's view of it, `status` `held` or `available`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeItemPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Sign-in without a verified email (`EMAIL_NOT_VERIFIED`) or phone (`PHONE_NOT_VERIFIED`), or a pause on this person (`asking_paused`, `giving_paused`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, `not_allowed`, `photo_required`, `available_until_too_far`, or an address that did not resolve (`details.reason` `address_*`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "429": {
            "description": "`daily_post_limit`: 10 posts a day.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      }
    },
    "/free-stuff/categories": {
      "get": {
        "tags": [
          "Free stuff"
        ],
        "summary": "The categories",
        "operationId": "listFreeItemCategories",
        "description": "What the post form and the filters offer, in the reader's language (`?lang=`, the language cookie, then Accept-Language), with how many days an item in each is up (14, or 2 for food). The browser may keep it for 60 seconds.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Categories.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "maxDays": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such item for this viewer, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      }
    },
    "/free-stuff/{id}": {
      "get": {
        "tags": [
          "Free stuff"
        ],
        "summary": "An item",
        "operationId": "getFreeItem",
        "description": "One item for this viewer: photos, title, condition, area and distance band, pickup methods, available until, and the giver's first name with \"gave N things\" (or the provider's name and kind). Signed in, the viewer's own ask and what stops them asking. The giver also gets the asks, why it is held and staff's decision; the person chosen gets the pickup place and note while chosen. Nobody else ever gets the pickup. A closed item answers `410` to anyone who did not ask for it; a held one is the giver's alone (`404`). A person the giver blocked gets `410`.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The item."
          },
          {
            "name": "near",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "lat,lng of the browser, for the distance band."
          }
        ],
        "responses": {
          "200": {
            "description": "The item.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeItemPage"
                }
              }
            }
          },
          "404": {
            "description": "No such item for this viewer, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "410": {
            "description": "`no_longer_available`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Free stuff"
        ],
        "summary": "Edit an item",
        "operationId": "editFreeItem",
        "description": "The giver edits a held, available, promised or expired item. Changing the title, description, category or photos runs the checks again: a block refuses the edit, a borderline match holds a live post, a clean edit of a post held by the checks puts it back up (unless it is still the person's first post). While someone is picking it up (`promised`) only the pickup details, methods, date and condition change (`409 promised`). Switching to \"first to ask\" with asks waiting chooses the earliest.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The item."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Any of the post's fields; `pickup.address` optional, `pickup.note` null clears it.",
                "properties": {
                  "title": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 70
                  },
                  "description": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 800
                  },
                  "categoryId": {
                    "type": "string"
                  },
                  "condition": {
                    "type": "string",
                    "enum": [
                      "new",
                      "like_new",
                      "good",
                      "fair",
                      "for_parts"
                    ]
                  },
                  "pickup": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "$ref": "#/components/schemas/FreeItemAddress"
                      },
                      "point": {
                        "type": "object",
                        "nullable": true
                      },
                      "note": {
                        "type": "string",
                        "nullable": true
                      }
                    }
                  },
                  "pickupMethods": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "porch",
                        "public_place",
                        "delivery"
                      ]
                    }
                  },
                  "availableUntil": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  },
                  "selectionMode": {
                    "type": "string",
                    "enum": [
                      "choose",
                      "first"
                    ]
                  },
                  "photos": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 6,
                    "items": {
                      "$ref": "#/components/schemas/FreeItemPhotoInput"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The giver's view.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeItemPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Sign-in without a verified email (`EMAIL_NOT_VERIFIED`) or phone (`PHONE_NOT_VERIFIED`), or a pause on this person (`asking_paused`, `giving_paused`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "404": {
            "description": "No such item for this viewer, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "409": {
            "description": "`promised` or `invalid_state`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, `not_allowed` or `available_until_too_far`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Free stuff"
        ],
        "summary": "Remove an item",
        "operationId": "removeFreeItem",
        "description": "The giver removes it; everyone who asked hears it is no longer available. Needs only a sign-in (it takes something away).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The item."
          }
        ],
        "responses": {
          "200": {
            "description": "Removed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "removed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such item for this viewer, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "409": {
            "description": "`invalid_state`: already given, removed or taken down.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      }
    },
    "/free-stuff/{id}/relist": {
      "post": {
        "tags": [
          "Free stuff"
        ],
        "summary": "Relist an expired item",
        "operationId": "relistFreeItem",
        "description": "An expired item goes back up in one tap with a fresh date (14 days, or the category's limit, by default). The checks and the first-post rule run again, so it may be held. People whose asks closed with it may ask again.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The item."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "availableUntil": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The giver's view.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeItemPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Sign-in without a verified email (`EMAIL_NOT_VERIFIED`) or phone (`PHONE_NOT_VERIFIED`), or a pause on this person (`asking_paused`, `giving_paused`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "404": {
            "description": "No such item for this viewer, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "409": {
            "description": "`invalid_state`: only an expired item relists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "422": {
            "description": "`not_allowed` or `available_until_too_far`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      }
    },
    "/free-stuff/{id}/requests": {
      "post": {
        "tags": [
          "Free stuff"
        ],
        "summary": "Ask for it",
        "operationId": "askForFreeItem",
        "description": "Asks for an item. The note is optional (\"You don't need to explain why\"). One ask per person per item, at most 5 open, never your own, not while asking is paused, and not from someone the giver blocked. With \"first to ask\" the first valid ask is chosen at once (`autoChosen: true`, and the pickup is in `item`); a later ask answers `409 went_to_first`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The item."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "note": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 280
                  },
                  "pickupPref": {
                    "type": "string",
                    "nullable": true,
                    "enum": [
                      "porch",
                      "public_place",
                      "delivery"
                    ],
                    "description": "One of the methods the item offers."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Asked.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "autoChosen": {
                      "type": "boolean"
                    },
                    "item": {
                      "$ref": "#/components/schemas/FreeItemPage"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Sign-in without a verified email (`EMAIL_NOT_VERIFIED`) or phone (`PHONE_NOT_VERIFIED`), or a pause on this person (`asking_paused`, `giving_paused`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "404": {
            "description": "No such item for this viewer, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "409": {
            "description": "`already_asked`, `open_ask_limit` (\"You have 5 open asks. Withdraw one to ask for this.\"), `went_to_first`, `not_available` or `own_item`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error` (the body), with `details`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      }
    },
    "/free-stuff/{id}/requests/mine": {
      "delete": {
        "tags": [
          "Free stuff"
        ],
        "summary": "Withdraw my ask",
        "operationId": "withdrawFreeItemAsk",
        "description": "Takes the caller's ask back. If they were chosen, the item is available again: with \"first to ask\" the next ask is chosen, otherwise the giver hears to choose someone else. Needs only a sign-in.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The item."
          }
        ],
        "responses": {
          "200": {
            "description": "Withdrawn.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "withdrawn": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such item for this viewer, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "409": {
            "description": "`invalid_state`: the ask is already closed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      }
    },
    "/free-stuff/{id}/requests/{requestId}/choose": {
      "post": {
        "tags": [
          "Free stuff"
        ],
        "summary": "Choose who gets it",
        "operationId": "chooseFreeItemAsk",
        "description": "The giver chooses one ask: the item is promised to that person, who alone is shown the pickup place and note, and told \"It's yours\". The other asks stay open as backups until it is given. `pickupNote` updates the note shared with them.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The item."
          },
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The ask."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pickupNote": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 280
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The giver's view.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeItemPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Sign-in without a verified email (`EMAIL_NOT_VERIFIED`) or phone (`PHONE_NOT_VERIFIED`), or a pause on this person (`asking_paused`, `giving_paused`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "404": {
            "description": "No such item for this viewer, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "409": {
            "description": "`already_chosen` (mark a no-show first) or `invalid_state`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      }
    },
    "/free-stuff/{id}/requests/{requestId}/block": {
      "post": {
        "tags": [
          "Free stuff"
        ],
        "summary": "Block the other person on an ask",
        "operationId": "blockOnFreeItemAsk",
        "description": "Blocks the other person on this ask, found by the server (no person's id is ever sent): for the item's giver, the person who asked; for the person who asked, the giver. It is the account-wide block (`user_blocks`), which free stuff honours. The giver blocking cancels that person's open asks on the giver's things (a chosen one reopens the choice; they see \"No longer available\"); the asker blocking withdraws their own open ask on this item. Needs sign-in only, no verified phone. Idempotent.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The item."
          },
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The ask."
          }
        ],
        "responses": {
          "200": {
            "description": "Blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffBlock"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such ask, the caller is neither side of it, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Free stuff"
        ],
        "summary": "Unblock the other person on an ask",
        "operationId": "unblockOnFreeItemAsk",
        "description": "Removes the block the caller made on the other person of this ask. Asks it closed stay closed. Idempotent.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The item."
          },
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The ask."
          }
        ],
        "responses": {
          "200": {
            "description": "Unblocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffBlock"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such ask, the caller is neither side of it, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      }
    },
    "/free-stuff/{id}/requests/{requestId}/no-show": {
      "post": {
        "tags": [
          "Free stuff"
        ],
        "summary": "Didn't show, choose someone else",
        "operationId": "markFreeItemNoShow",
        "description": "The giver marks the person chosen as a no-show and the choice reopens (\"first to ask\" chooses the next ask). Two no-shows within 60 days pause that person's asking for 14 days, and they are told.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The item."
          },
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The ask."
          }
        ],
        "responses": {
          "200": {
            "description": "The giver's view.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeItemPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Sign-in without a verified email (`EMAIL_NOT_VERIFIED`) or phone (`PHONE_NOT_VERIFIED`), or a pause on this person (`asking_paused`, `giving_paused`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "404": {
            "description": "No such item for this viewer, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "409": {
            "description": "`invalid_state`: only the person chosen can be a no-show.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      }
    },
    "/free-stuff/{id}/given": {
      "post": {
        "tags": [
          "Free stuff"
        ],
        "summary": "Picked up",
        "operationId": "markFreeItemGiven",
        "description": "The giver marks it picked up: the chosen ask is picked up, everyone else who asked hears it went to someone else, and saved copies drop off.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The item."
          }
        ],
        "responses": {
          "200": {
            "description": "The giver's view.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeItemPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Sign-in without a verified email (`EMAIL_NOT_VERIFIED`) or phone (`PHONE_NOT_VERIFIED`), or a pause on this person (`asking_paused`, `giving_paused`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "404": {
            "description": "No such item for this viewer, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "409": {
            "description": "`invalid_state`: choose someone first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      }
    },
    "/free-stuff/{id}/messages": {
      "get": {
        "tags": [
          "Free stuff"
        ],
        "summary": "The pickup thread",
        "operationId": "listFreeItemMessages",
        "description": "The thread between the giver and the person chosen, text only; nobody else can read it, and neither side's phone or email is part of it. Marks the other person's messages read. The giver reads the current chosen ask's thread, or another with `requestId`. Messages are deleted 90 days after the item closes.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The item."
          },
          {
            "name": "requestId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The thread.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "thread": {
                      "type": "object",
                      "properties": {
                        "requestId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status": {
                          "type": "string"
                        },
                        "role": {
                          "type": "string",
                          "enum": [
                            "giver",
                            "chosen"
                          ]
                        },
                        "with": {
                          "type": "object",
                          "properties": {
                            "firstName": {
                              "type": "string",
                              "nullable": true
                            }
                          }
                        },
                        "canWrite": {
                          "type": "boolean"
                        },
                        "blockedByMe": {
                          "type": "boolean",
                          "description": "The caller blocked the other person (#2435): the thread offers Unblock."
                        }
                      }
                    },
                    "messages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "mine": {
                            "type": "boolean"
                          },
                          "body": {
                            "type": "string"
                          },
                          "sentAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "readAt": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`not_in_thread`, or the verification gates.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "404": {
            "description": "No such item for this viewer, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Free stuff"
        ],
        "summary": "Send a pickup message",
        "operationId": "sendFreeItemMessage",
        "description": "Sends a message in the pickup thread, up to 1000 characters. 30 messages an hour per person per thread. The other person gets a bell for the first message they haven't read yet. A person who blocked the sender gets nothing: `403 cannot_message`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The item."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "body"
                ],
                "properties": {
                  "body": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1000
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Sent: the thread.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "thread": {
                      "type": "object",
                      "properties": {
                        "requestId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status": {
                          "type": "string"
                        },
                        "role": {
                          "type": "string",
                          "enum": [
                            "giver",
                            "chosen"
                          ]
                        },
                        "with": {
                          "type": "object",
                          "properties": {
                            "firstName": {
                              "type": "string",
                              "nullable": true
                            }
                          }
                        },
                        "canWrite": {
                          "type": "boolean"
                        },
                        "blockedByMe": {
                          "type": "boolean",
                          "description": "The caller blocked the other person (#2435): the thread offers Unblock."
                        }
                      }
                    },
                    "messages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "mine": {
                            "type": "boolean"
                          },
                          "body": {
                            "type": "string"
                          },
                          "sentAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "readAt": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`not_in_thread`, `cannot_message`, or the verification gates.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "404": {
            "description": "No such item for this viewer, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error` (the body), with `details`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "429": {
            "description": "`message_limit`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      }
    },
    "/free-stuff/{id}/reports": {
      "post": {
        "tags": [
          "Free stuff"
        ],
        "summary": "Report an item or a person",
        "operationId": "reportFreeStuff",
        "description": "Reports the item's giver (from the item), the other side of an ask (`requestId`) or the sender of a message (`messageId`). \"Asked me to pay\" and \"Unsafe item\" go to the top of the staff queue, hold the reported person's available items until staff look, and tell staff now. The reporter is never revealed to the person reported. The same open report again answers `200` with the first one.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The item."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reason"
                ],
                "properties": {
                  "reason": {
                    "type": "string",
                    "enum": [
                      "asked_to_pay",
                      "unsafe_item",
                      "reselling",
                      "harassment",
                      "no_show",
                      "other"
                    ]
                  },
                  "note": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 300
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                  },
                  "messageId": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The same open report, made before.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "duplicate": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Reported.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "duplicate": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Sign-in without a verified email (`EMAIL_NOT_VERIFIED`) or phone (`PHONE_NOT_VERIFIED`), or a pause on this person (`asking_paused`, `giving_paused`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "404": {
            "description": "No such item for this viewer, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error` or `cannot_report_self`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      }
    },
    "/me/free-stuff-saves/{id}": {
      "put": {
        "tags": [
          "Free stuff"
        ],
        "summary": "Save an item",
        "operationId": "saveFreeItem",
        "description": "Saves an item that is up, for My help -> Free stuff (it drops off when the item closes). Idempotent. Needs only a sign-in.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The item."
          }
        ],
        "responses": {
          "200": {
            "description": "Saved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "saved": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such item for this viewer, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Free stuff"
        ],
        "summary": "Unsave an item",
        "operationId": "unsaveFreeItem",
        "description": "Removes a save. Idempotent.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The item."
          }
        ],
        "responses": {
          "200": {
            "description": "Not saved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "saved": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such item for this viewer, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      }
    },
    "/me/free-stuff": {
      "get": {
        "tags": [
          "Free stuff"
        ],
        "summary": "My help -> Free stuff",
        "operationId": "myFreeStuff",
        "description": "The signed-in person's free stuff. `giving`: their items with open ask counts, who is picking it up (first name), held, given, expired or taken down with staff's reason. `getting`: their asks by state, \"It's yours\" first, with the pickup for an ask that is chosen. `saved`: items they saved that are still up.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "tab",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "giving",
                "getting",
                "saved"
              ],
              "default": "giving"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 24,
              "maximum": 48
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The tab.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tab": {
                      "type": "string"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "items": {
                      "type": "array",
                      "description": "giving and saved: FreeItemCard (giving adds openAsks, chosen and review); getting: { item: FreeItemCard, ask: FreeItemOwnAsk, pickup: FreeItemPickup }.",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such item for this viewer, or free stuff is switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`: an unknown tab.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeStuffError"
                }
              }
            }
          }
        }
      }
    },
    "/me/resources-menu": {
      "get": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Resources in the menus",
        "operationId": "getResourcesMenu",
        "description": "Whether Resources (and free stuff) are on for the caller, and up to 10 providers they can see. Mirrors /me/sponsor-menu: a `403` from the switch means Resources are off. Signed out is allowed (no providers).",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resources": {
                      "type": "boolean"
                    },
                    "free_stuff": {
                      "type": "boolean"
                    },
                    "providers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MyResourceProvider"
                      }
                    },
                    "person_provider": {
                      "type": "object",
                      "nullable": true,
                      "description": "The help the caller lists as themself (#2436), for My help and the user menu's \"Help you offer\".",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "slug": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/me/resource-providers": {
      "get": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Providers I can see or manage",
        "operationId": "listMyResourceProviders",
        "description": "Every non-profit or church (org.read or nonprofit.resources.manage), business (owner, admin, manager) and community (owner, leader, volunteer) the caller is on, with its provider when it lists help already (`provider` null: \"Add services to it?\"). For /resources/join and \"Post as\". `person` is listing help as yourself (#2436): your provider if you have one, and whether you may make it (a verified email, a public name, an account in good standing). A person's provider is never in `items`, so it is never a \"Post as\".",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MyResourceProvider"
                      }
                    },
                    "person": {
                      "type": "object",
                      "properties": {
                        "provider": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "slug": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string"
                            }
                          }
                        },
                        "name": {
                          "type": "string",
                          "nullable": true,
                          "description": "The public name the card would show; null until the profile has one."
                        },
                        "email_verified": {
                          "type": "boolean"
                        },
                        "can_create": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/resource-places": {
      "get": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Cities and ZIP codes for a service area",
        "operationId": "searchResourcePlaces",
        "description": "What a service area can name, with the place id it stores (#2422). Five digits: that ZIP code, made from the ZIP table when FundlyHub has none yet. Otherwise US cities whose name starts with `q`; \"Folsom, CA\" narrows to the state. Fewer than 2 characters: none. `kind=city`: cities only, a ZIP answering with its city (the staff city filters and a public program's city, which need no manage_cities; #2434).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 80
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "city"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "city",
                              "postal_code"
                            ]
                          },
                          "label": {
                            "type": "string",
                            "example": "95630 · Folsom, CA"
                          },
                          "region": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/resource-providers": {
      "get": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "The provider of a non-profit, business, community or person",
        "operationId": "getResourceProviderForEntity",
        "description": "For a workspace's Resources tab (#2422): the provider of the entity, as GET /resource-providers/{providerId} answers it, or `provider: null` when it lists nothing yet, with whether the viewer may make it (`can_create`) and what they may do. Anyone on the entity's team whose role sees the tab reads it, and staff with review_resources or manage_resources. A role that doesn't (a cashier, a non-profit member) gets 403, someone with nothing to do with it 404. `kind=person` (#2436) is a person's own (My help -> Help you offer): `entity_id` is their profile, the caller's when left out; only they and staff read it, and `person` says what stands in the way of making it (a verified email, a public name).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "kind",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "nonprofit",
                "business",
                "community",
                "person"
              ]
            }
          },
          {
            "name": "entity_id",
            "in": "query",
            "required": false,
            "description": "Required for every kind but person.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entity": {
                      "type": "object",
                      "properties": {
                        "kind": {
                          "type": "string"
                        },
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "slug": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        }
                      }
                    },
                    "provider": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/ResourceProvider"
                        }
                      ],
                      "nullable": true,
                      "description": "With `counts`, `ready_to_publish` and `viewer`, as GET /resource-providers/{providerId}."
                    },
                    "can_create": {
                      "type": "boolean",
                      "description": "The viewer may make the provider (POST /resource-providers) and add its first help."
                    },
                    "person": {
                      "type": "object",
                      "description": "kind=person only: what making it needs.",
                      "properties": {
                        "email_verified": {
                          "type": "boolean"
                        },
                        "has_name": {
                          "type": "boolean"
                        },
                        "listable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "viewer": {
                      "type": "object",
                      "description": "When there is no provider yet, what the viewer's role reaches.",
                      "properties": {
                        "role": {
                          "type": "string",
                          "nullable": true
                        },
                        "as_staff": {
                          "type": "boolean"
                        },
                        "can": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "422": {
            "description": "A kind or an id that isn't one (`details.field`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Make the provider for an entity I manage, or for myself",
        "operationId": "createResourceProvider",
        "description": "Idempotent per entity: 201 the first time, 200 with the same provider after. The slug is the entity's own, with -2, -3 ... when another provider has it. Owners and admins (a business's owner or admin, a community's owner or leaders), or staff with manage_resources. Public programs are listed by staff. `{kind: person}` lists help as yourself (#2436, \"List help as yourself\"): it needs a verified email (403 `email_not_verified`, saying to verify it from Settings), a public name (422 `name_required`) and an account in good standing (403 `account_not_active`); idempotent per person; its slug follows your handle, or your name when the handle came from your email. Naming someone else's profile is a 404. Every listing it sends goes through staff review.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "nonprofit",
                      "business",
                      "community",
                      "person"
                    ]
                  },
                  "entity_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required for every kind but person (for a person it may only be your own profile)."
                  }
                },
                "required": [
                  "kind"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Made (200 when it existed)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "created": {
                      "type": "boolean"
                    },
                    "provider": {
                      "$ref": "#/components/schemas/ResourceProvider"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "422": {
            "description": "Something to fix, with `details.field`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resource-providers/{providerId}": {
      "get": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "A provider in the workspace",
        "operationId": "getWorkspaceResourceProvider",
        "description": "The provider, its counts (drafts, in review, live, paused, held, links waiting, open reports), whether its entity may publish yet, and what the viewer may do (`viewer.can`, per action: all, locations or false). **Checks:** `requireProviderAccess('view_resources')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The provider (resource_providers.id)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ResourceProvider"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "counts": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "integer"
                          }
                        },
                        "ready_to_publish": {
                          "type": "boolean"
                        },
                        "linked": {
                          "type": "array",
                          "description": "The providers on the other side of its link (a church's communities, a community's church; CH-04), and whether the viewer can list help under each, for \"Who provides this?\".",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "kind": {
                                "type": "string"
                              },
                              "slug": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "is_church": {
                                "type": "boolean"
                              },
                              "entity_slug": {
                                "type": "string",
                                "nullable": true
                              },
                              "status": {
                                "type": "string"
                              },
                              "relation": {
                                "type": "string",
                                "enum": [
                                  "part_of",
                                  "part"
                                ]
                              },
                              "can_manage": {
                                "type": "boolean"
                              }
                            }
                          }
                        },
                        "viewer": {
                          "type": "object",
                          "properties": {
                            "role": {
                              "type": "string",
                              "nullable": true
                            },
                            "as_staff": {
                              "type": "boolean"
                            },
                            "can": {
                              "type": "object",
                              "additionalProperties": {
                                "oneOf": [
                                  {
                                    "type": "string",
                                    "enum": [
                                      "all",
                                      "locations"
                                    ]
                                  },
                                  {
                                    "type": "boolean",
                                    "enum": [
                                      false
                                    ]
                                  }
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resource-providers/{providerId}/resources": {
      "get": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "The provider's resources",
        "operationId": "listProviderResources",
        "description": "Drafts and changes requested first, archived only with `status=archived` (or `archived=true`).\n**Checks:** `requireProviderAccess('view_resources')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The provider (resource_providers.id)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "One status."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Title contains."
          },
          {
            "name": "archived",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 48,
              "default": 24
            },
            "description": "Page size (24 by default, 48 at most)."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            },
            "description": "Rows to skip."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ResourceListItem"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Start a draft",
        "operationId": "createResourceDraft",
        "description": "A draft from whatever the editor has (a title at least). A business manager names one or more of their own locations. A person's help (#2436) names no location (422 `resource_locations_person`, `details.field` location_ids) and no sensitive topic, or a topic under one (422 `resource_topic_links_person_sensitive`, `details.field` topic_ids); the same holds for PATCH /resources/{id}, for a change to live help too. **Checks:** `requireProviderAccess('manage_resources')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The provider (resource_providers.id)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResourceFields"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resource"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "422": {
            "description": "Something to fix, with `details.field`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resource-providers/{providerId}/near-duplicates": {
      "post": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Near-identical help under a linked church or community",
        "operationId": "resourceNearDuplicates",
        "description": "CH-04, CM-12 (#2434): when a church also runs a FundlyHub community (resource_providers.part_of_provider_id), help can be listed under either one, and the editor warns of a near-identical listing under the other: the same title or nearly (trigram similarity 0.6), a topic in common or under the same parent, and a city, ZIP's city or state in common, or both online. Before any place is picked, `same_place` is null and the title and topic decide. Someone off the other provider's team hears only of help anyone can find. A POST, so topics stay out of addresses and logs. Up to 5.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "topic_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "location_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "service_areas": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "online": {
                    "type": "boolean"
                  },
                  "exclude_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "The resource being edited."
                  }
                },
                "required": [
                  "title",
                  "topic_ids"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "title": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "provider": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "kind": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "slug": {
                                "type": "string"
                              },
                              "is_church": {
                                "type": "boolean"
                              }
                            }
                          },
                          "same_place": {
                            "type": "boolean",
                            "nullable": true
                          },
                          "can_open": {
                            "type": "boolean"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resource-providers/{providerId}/topics": {
      "get": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "The topics the editor picks from",
        "operationId": "listResourceEditorTopics",
        "description": "Every active topic and its needs with the ids the editor's fields store (`topic_ids`, `need_ids`), in the reader's language (`?lang=`, the cookie, then Accept-Language), and whether a topic is sensitive (never in a URL or a notification) or licensed (its help needs a license, NP-13). #2422. **Checks:** `requireProviderAccess('view_resources')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The provider (resource_providers.id)."
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "language": {
                      "type": "string"
                    },
                    "topics": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "slug": {
                            "type": "string"
                          },
                          "parent_id": {
                            "type": "string",
                            "format": "uuid",
                            "nullable": true
                          },
                          "name": {
                            "type": "string"
                          },
                          "sensitive": {
                            "type": "boolean"
                          },
                          "licensed": {
                            "type": "boolean"
                          },
                          "needs": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "format": "uuid"
                                },
                                "slug": {
                                  "type": "string"
                                },
                                "name": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resource-providers/{providerId}/locations": {
      "get": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "The places help can happen at",
        "operationId": "listResourceProviderLocations",
        "description": "The open locations of the provider's entity, the primary first, every kind in one shape (#2422, NP-04, SP-05, CM-04): a non-profit's (organization_locations.org_id), a business's (the storefront's own), a community's or a public program's. `mine` marks a business manager's own. `can_add`: `here` (POST below, a community or a public program), `entity` (a non-profit or a business adds them in its own workspace, so one address change updates every listing) or false. A person (#2436) has none and adds none (`items` empty, `can_add` false): their help happens where they serve, or online, and their home is never a location. **Checks:** `requireProviderAccess('view_resources')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The provider (resource_providers.id)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ResourceEditorLocation"
                      }
                    },
                    "can_add": {
                      "oneOf": [
                        {
                          "type": "string",
                          "enum": [
                            "here",
                            "entity"
                          ]
                        },
                        {
                          "type": "boolean",
                          "enum": [
                            false
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Add a community's or a public program's place",
        "operationId": "addResourceProviderLocation",
        "description": "A place where a community's or a public program's help happens (a church hall, a school gym), saved as its location so every listing can reuse it (CM-04). The address resolves now (Find help needs its city); it is public unless `is_publicly_visible` is false (a safe home), and a listing's confidential switch hides it too. The first open place is the primary. Up to 50. A non-profit or a business answers 409 `use_entity_locations`: add those in the entity's workspace. A person answers 409 `person_has_no_premises` (#2436). An audit row, no event. #2422. **Checks:** `requireProviderAccess('manage_resources')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The provider (resource_providers.id)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 60,
                    "example": "Oak Park Community Hall"
                  },
                  "address": {
                    "type": "object",
                    "properties": {
                      "line1": {
                        "type": "string",
                        "maxLength": 120
                      },
                      "line2": {
                        "type": "string",
                        "maxLength": 60
                      },
                      "city": {
                        "type": "string"
                      },
                      "region": {
                        "type": "string",
                        "description": "The state, as its code or name."
                      },
                      "postal_code": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "line1",
                      "city",
                      "region",
                      "postal_code"
                    ]
                  },
                  "point": {
                    "type": "object",
                    "properties": {
                      "lat": {
                        "type": "number"
                      },
                      "lng": {
                        "type": "number"
                      }
                    }
                  },
                  "is_publicly_visible": {
                    "type": "boolean",
                    "default": true
                  },
                  "is_primary": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "label",
                  "address"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Added",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceEditorLocation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "409": {
            "description": "`use_entity_locations` (a non-profit or a business), `too_many_locations`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "422": {
            "description": "An address to fix (`details.field`, e.g. `address.postal_code`; `address_unknown_postal_code`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resource-providers/{providerId}/licenses": {
      "get": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "The provider's licenses",
        "operationId": "listProviderLicenses",
        "description": "With the help that relies on each.\n**Checks:** `requireProviderAccess('manage_licenses')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The provider (resource_providers.id)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ProfessionalLicense"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Add a license",
        "operationId": "createProviderLicense",
        "description": "Pending until staff check it against the public record (ST-03).\n**Checks:** `requireProviderAccess('manage_licenses')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The provider (resource_providers.id)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "holder_name": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "attorney",
                      "physician",
                      "nurse",
                      "mental_health",
                      "tax_preparer",
                      "other"
                    ]
                  },
                  "license_number": {
                    "type": "string"
                  },
                  "state": {
                    "type": "string",
                    "example": "CA"
                  }
                },
                "required": [
                  "holder_name",
                  "kind",
                  "license_number",
                  "state"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProfessionalLicense"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "409": {
            "description": "A clash: a stale version, a state that doesn't allow it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "422": {
            "description": "Something to fix, with `details.field`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resource-providers/{providerId}/licenses/{licenseId}": {
      "patch": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Change a license",
        "operationId": "updateProviderLicense",
        "description": "A change to the holder, kind, number or state needs checking again (pending), which holds the live help relying on it (hold `license`) until staff verify it. **Checks:** `requireProviderAccess('manage_licenses')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The provider (resource_providers.id)."
          },
          {
            "name": "licenseId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The license."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "holder_name": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "attorney",
                      "physician",
                      "nurse",
                      "mental_health",
                      "tax_preparer",
                      "other"
                    ]
                  },
                  "license_number": {
                    "type": "string"
                  },
                  "state": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProfessionalLicense"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "409": {
            "description": "A clash: a stale version, a state that doesn't allow it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "422": {
            "description": "Something to fix, with `details.field`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resource-providers/{providerId}/fundraiser-links": {
      "get": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Fundraisers that name the provider's help",
        "operationId": "listProviderFundraiserLinks",
        "description": "Waiting ones first (`requested`, and `needs_confirmation` after a transfer: `from_previous_provider`). `waiting` is the tab's count. **Checks:** `requireProviderAccess('manage_fundraiser_links')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The provider (resource_providers.id)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "requested",
                "confirmed",
                "declined",
                "removed",
                "needs_confirmation"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 48,
              "default": 24
            },
            "description": "Page size (24 by default, 48 at most)."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            },
            "description": "Rows to skip."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "status": {
                            "type": "string"
                          },
                          "estimate_cents": {
                            "type": "integer",
                            "nullable": true
                          },
                          "requested_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "reminded_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "decided_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          },
                          "direct_payout": {
                            "type": "boolean",
                            "description": "Gifts from this fundraiser go straight to this provider (NP-16), read from the fundraiser's beneficiary, as checkout reads it (#2424)."
                          },
                          "client_consent": {
                            "type": "boolean"
                          },
                          "resource_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "resource_title": {
                            "type": "string"
                          },
                          "fundraiser_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "fundraiser_title": {
                            "type": "string"
                          },
                          "fundraiser_slug": {
                            "type": "string"
                          },
                          "fundraiser_is_project": {
                            "type": "boolean",
                            "description": "A project: its page is /p/<slug>; a fundraiser: /f/<slug>."
                          },
                          "organizer_name": {
                            "type": "string",
                            "nullable": true,
                            "description": "The organizer's first name and last initial (\"Maria L.\"). Never an email."
                          },
                          "raised_cents": {
                            "type": "integer",
                            "description": "What the fundraiser has raised."
                          },
                          "confirmed_fee_cents": {
                            "type": "integer",
                            "nullable": true,
                            "description": "The fee the provider confirmed; null keeps the estimate."
                          },
                          "provider_note": {
                            "type": "string",
                            "nullable": true,
                            "description": "The provider's note to the organizer."
                          },
                          "from_previous_provider": {
                            "type": "boolean"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "waiting": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resource-providers/{providerId}/reports": {
      "get": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Reports about the provider's help",
        "operationId": "listProviderReports",
        "description": "Wrong-info and closed reports, with what the reporter said, never who they are (NP-12). Unsafe and scam reports go to staff only. Confirming the info closes them as fixed. **Checks:** `requireProviderAccess('view_reports')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "providerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The provider (resource_providers.id)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "actioned",
                "dismissed"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 48,
              "default": 24
            },
            "description": "Page size (24 by default, 48 at most)."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            },
            "description": "Rows to skip."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "resource_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "resource_title": {
                            "type": "string"
                          },
                          "reason": {
                            "type": "string",
                            "enum": [
                              "wrong_info",
                              "closed"
                            ]
                          },
                          "note": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string"
                          },
                          "action": {
                            "type": "string",
                            "nullable": true
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "handled_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/fundraiser-links/{id}/confirm": {
      "post": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Confirm a fundraiser",
        "operationId": "confirmFundraiserLink",
        "description": "The provider of the help confirms the fundraiser raises money for it; its licenses come up for a re-check (NP-13). It may confirm the fee (`fee_cents`, which donors then see as the fee; omitted, the organizer's estimate stands) and add a note for the organizer (`note`, up to 280 characters, which only the organizer sees). The organizers are told, with the fee and never the note. Publishes fundraiser_resource.confirmed. **Checks:** `requireProviderAccess('manage_fundraiser_links')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The fundraiser link."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "fee_cents": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100000000,
                    "description": "The fee confirmed",
                    "in cents.": null
                  },
                  "note": {
                    "type": "string",
                    "maxLength": 280,
                    "description": "A note to the organizer."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "confirmed"
                      ]
                    },
                    "confirmed_fee_cents": {
                      "type": "integer",
                      "nullable": true
                    },
                    "provider_note": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "409": {
            "description": "A clash: a stale version, a state that doesn't allow it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/fundraiser-links/{id}/decline": {
      "post": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Decline a fundraiser",
        "operationId": "declineFundraiserLink",
        "description": "The reason stays private (the provider and staff only). The organizers are told it was declined. Publishes fundraiser_resource.declined. **Checks:** `requireProviderAccess('manage_fundraiser_links')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The fundraiser link."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 280
                  }
                },
                "required": [
                  "reason"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "declined"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "409": {
            "description": "A clash: a stale version, a state that doesn't allow it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "422": {
            "description": "Something to fix, with `details.field`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resources/{id}": {
      "get": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "A resource",
        "operationId": "getWorkspaceResource",
        "description": "Every field, the change in review, the decisions so far, listing health, and what the viewer may do with it. The `ETag` is the version. **Checks:** `requireProviderAccess('view_resources')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The resource."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resource"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Edit a resource",
        "operationId": "updateWorkspaceResource",
        "description": "A draft saves freely. On published help, small fields go live at once (audit-logged) and material fields open or replace the one pending revision while the live version stays up. The schema's rules are checked now, revision included. A stale version gets 409 `stale_version` with `details.changed_since` (the fields, and whether staff changed them). **Checks:** `requireProviderAccess('manage_resources')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The resource."
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The version you opened, e.g. `\"7\"`. Or send `version` in the body."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ResourceFields"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "version": {
                        "type": "integer"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resource": {
                      "$ref": "#/components/schemas/Resource"
                    },
                    "changed": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "applied": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "in_review": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "409": {
            "description": "A clash: a stale version, a state that doesn't allow it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "422": {
            "description": "Something to fix, with `details.field`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "428": {
            "description": "No version was sent (If-Match or `version`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resources/{id}/history": {
      "get": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Who changed what",
        "operationId": "getWorkspaceResourceHistory",
        "description": "The audit trail, newest first. Staff changes read \"FundlyHub staff\", with their reason.\n**Checks:** `requireProviderAccess('view_resources')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The resource."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "action": {
                            "type": "string"
                          },
                          "at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "by_staff": {
                            "type": "boolean"
                          },
                          "by": {
                            "type": "string",
                            "nullable": true
                          },
                          "fields": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "reason": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resources/{id}/submit": {
      "post": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Send for review",
        "operationId": "submitWorkspaceResource",
        "description": "A draft, changes requested or rejected resource goes to review (in_review); the first submission is a revision too. Refused (422) while it lacks a title, summary, topic or service area (`incomplete`, `details.problems`), a license in a licensed topic (`license_required`), the entity's own checks (`provider_not_verified`: \"Finish verification to publish. Your draft is saved.\"), or after a rejection with nothing changed (`unchanged_since_rejection`). **Checks:** `requireProviderAccess('manage_resources')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The resource."
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The version you opened, e.g. `\"7\"`. Or send `version` in the body."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resource"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "409": {
            "description": "A clash: a stale version, a state that doesn't allow it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "422": {
            "description": "Something to fix, with `details.field`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resources/{id}/pause": {
      "post": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Pause",
        "operationId": "pauseWorkspaceResource",
        "description": "Live help leaves Find help at once. Publishes resource.paused.\n**Checks:** `requireProviderAccess('manage_resources')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The resource."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resource"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "409": {
            "description": "A clash: a stale version, a state that doesn't allow it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resources/{id}/unpause": {
      "post": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Unpause",
        "operationId": "unpauseWorkspaceResource",
        "description": "Back in Find help, unless staff paused it (`paused_by_staff`, 403). Publishes resource.published.\n**Checks:** `requireProviderAccess('manage_resources')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The resource."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resource"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "409": {
            "description": "A clash: a stale version, a state that doesn't allow it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resources/{id}/duplicate": {
      "post": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Duplicate",
        "operationId": "duplicateWorkspaceResource",
        "description": "A new draft with everything but the review state (\"Copy of ...\").\n**Checks:** `requireProviderAccess('manage_resources')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The resource."
          }
        ],
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resource"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resources/{id}/archive": {
      "post": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Remove",
        "operationId": "archiveWorkspaceResource",
        "description": "Archived: out of every list; staff can restore it for 30 days. Publishes resource.hidden when it was public.\n**Checks:** `requireProviderAccess('manage_resources')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The resource."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resource"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "409": {
            "description": "A clash: a stale version, a state that doesn't allow it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resources/{id}/confirm": {
      "post": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Confirm your info",
        "operationId": "confirmWorkspaceResource",
        "description": "Restarts the freshness clock, clears a stale hold, and closes wrong-info and closed reports as fixed. A business manager confirms help at their own locations. **Checks:** `requireProviderAccess('confirm_resources')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The resource."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resource"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "409": {
            "description": "A clash: a stale version, a state that doesn't allow it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resources/{id}/capacity": {
      "put": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Capacity",
        "operationId": "putWorkspaceResourceCapacity",
        "description": "Taking new people, a waitlist, or paused until a date, with a message. Live at once, audit-logged with who (CM-08). **Checks:** `requireProviderAccess('update_resource_capacity')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The resource."
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The version you opened, e.g. `\"7\"`. Or send `version` in the body."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "capacity": {
                    "type": "string",
                    "enum": [
                      "taking",
                      "waitlist",
                      "paused"
                    ]
                  },
                  "capacity_note": {
                    "type": "string",
                    "nullable": true
                  },
                  "paused_until": {
                    "type": "string",
                    "format": "date",
                    "nullable": true
                  }
                },
                "required": [
                  "capacity"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resource"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "409": {
            "description": "A clash: a stale version, a state that doesn't allow it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "422": {
            "description": "Something to fix, with `details.field`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/resources/{id}/stock-note": {
      "put": {
        "tags": [
          "Resources · Workspace"
        ],
        "summary": "Stock note",
        "operationId": "putWorkspaceResourceStockNote",
        "description": "\"Fresh bread Tuesdays\"; null clears it. Live at once, audit-logged with who.\n**Checks:** `requireProviderAccess('update_resource_capacity')`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The resource."
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The version you opened, e.g. `\"7\"`. Or send `version` in the body."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "stock_note": {
                    "type": "string",
                    "maxLength": 140,
                    "nullable": true
                  }
                },
                "required": [
                  "stock_note"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resource"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "The role can't do that (`forbidden`, `details.required_action`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "Not found, or not visible to the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "409": {
            "description": "A clash: a stale version, a state that doesn't allow it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "422": {
            "description": "Something to fix, with `details.field`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{id}/resources": {
      "get": {
        "tags": [
          "Resources · Fundraisers"
        ],
        "summary": "Help we're raising for",
        "operationId": "getFundraiserResources",
        "description": "What the fundraiser shows under \"Help we're raising for\". A visitor sees confirmed links only: the provider's public card, the help's name, the estimate and \"Confirmed by <provider>\"; a business link reads \"The organizer pays the business\" (`giftsGoTo: organizer`). The fundraiser's owner and admins get the organizer's view: also requested, needs_confirmation and declined links, with the payout state. A fundraiser the caller may not open answers 404, as `GET /fundraisers/{id}` does. A visitor's answer may be cached for a minute; anyone signed in gets `private, no-store`.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The fundraiser."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FundraiserResources"
                }
              }
            }
          },
          "403": {
            "description": "Resources are switched off."
          },
          "404": {
            "description": "No such fundraiser, or the caller may not open it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Resources · Fundraisers"
        ],
        "summary": "Name help on a fundraiser",
        "operationId": "nameFundraiserResource",
        "description": "The fundraiser's organizer names live, publicly listed help with a fee, and an estimate. Help in a licensed topic (a lawyer) needs `client_consent: true` (the organizer agrees the provider may confirm they are its client), recorded as the link's consent; consent given for other help is recorded too. One link per fundraiser and help: a repeat answers 409 `already_named` with `details.link_id`. The provider's managers get a bell (Resources) and fundraiser_resource.requested is published after the commit. The link waits on the provider: a reminder at 7 days, removed at 14 if unanswered.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The fundraiser."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "resource_id",
                  "estimate_cents"
                ],
                "properties": {
                  "resource_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "estimate_cents": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 2147483647
                  },
                  "client_consent": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Named. The new link and the organizer's whole view.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "link": {
                      "$ref": "#/components/schemas/FundraiserResourceLink"
                    },
                    "view": {
                      "$ref": "#/components/schemas/FundraiserResources"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not the fundraiser's organizer (`organizer_only`), or Resources are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "No such fundraiser, or the caller may not open it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "409": {
            "description": "`already_named` (`details.link_id`, `details.status`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "422": {
            "description": "`required` (resource_id), `not_listed` (not live and public), `free_help` (nothing to raise for), `consent_required` (licensed help), `estimate_required` or `estimate_invalid`; `details.field` says which.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{id}/resources/{linkId}": {
      "delete": {
        "tags": [
          "Resources · Fundraisers"
        ],
        "summary": "Remove help from a fundraiser",
        "operationId": "removeFundraiserResource",
        "description": "The organizer (or an admin) removes a link: it stays on record as removed and fundraiser_resource.removed is published. Removing a removed link answers the same. While this link holds \"Send gifts straight to\", 409 `payout_on`: turn that off first.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The fundraiser."
          },
          {
            "name": "linkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Removed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "removed"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not the fundraiser's organizer (`organizer_only`), or Resources are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "No such fundraiser or link.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "409": {
            "description": "`payout_on`: gifts go straight to this provider.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{id}/resources/{linkId}/remind": {
      "post": {
        "tags": [
          "Resources · Fundraisers"
        ],
        "summary": "Send the provider a reminder",
        "operationId": "remindFundraiserResourceProvider",
        "description": "The fundraiser's organizer nudges a provider that hasn't answered (board FrPagePending): only while the link is requested (409 `not_waiting` once it answered), and at most once every 3 days (429 `nudge_too_soon` with `details.next_at`). The provider's managers get a bell; the help is never named on a sensitive topic. Audited (`fundraiser_resource.nudged`). Answers the organizer's view.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The fundraiser."
          },
          {
            "name": "linkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The link."
          }
        ],
        "responses": {
          "200": {
            "description": "Sent. The organizer's view, with when the next reminder can go.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FundraiserResources"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not the fundraiser's organizer (`organizer_only`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "No such fundraiser or link, or Resources are off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "409": {
            "description": "`not_waiting`: the provider already answered.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "429": {
            "description": "`nudge_too_soon`, with `details.next_at`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/fundraisers/{id}/resources/{linkId}/payout": {
      "put": {
        "tags": [
          "Resources · Fundraisers"
        ],
        "summary": "Send gifts straight to the provider",
        "operationId": "setFundraiserResourcePayout",
        "description": "The fundraiser's owner turns direct payout on or off. It is not a flag: turning it on changes the fundraiser's own beneficiary (beneficiary_type nonprofit, org_id the provider's non-profit, type charity), the existing non-profit beneficiary path checkout reads on every gift, in one transaction with the link, and remembers the previous beneficiary; turning it off restores exactly that. On needs a confirmed link (`link_not_confirmed`) to an active (`provider_not_active`) non-profit or church (a business or community: 422 `payout_not_offered`), a fundraiser not already raising for a non-profit (`already_nonprofit`), no waiting beneficiary invitation (`beneficiary_invitation_pending`), a linked person when raising for someone else (`beneficiary_person_required`), and the non-profit path's own checks: verified (`nonprofit_not_verified`), USD, no account deletion hold (`account_deletion_hold`) and a payout account that can receive money now (`nonprofit_account_not_ready`, `payments_disabled`). After the first gift or payment, both directions answer 409 `payout_locked`. A transfer, merge or decline later leaves the beneficiary as it is; off still works from that link while nothing is locked. Idempotent.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The fundraiser."
          },
          {
            "name": "linkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "on"
                ],
                "properties": {
                  "on": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The organizer's view after the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FundraiserResources"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Not the fundraiser's owner (`organizer_only`, `owner_required`), or Resources are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "404": {
            "description": "No such fundraiser or link.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "409": {
            "description": "`payout_locked`, `link_not_confirmed`, `provider_not_active`, `already_nonprofit`, `beneficiary_invitation_pending`, `beneficiary_person_required`, or a non-profit path refusal (`nonprofit_not_verified`, `nonprofit_account_not_ready`, `account_deletion_hold`, ...).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          },
          "422": {
            "description": "`payout_not_offered` (a business, community or public program), or `on` is not a boolean (`required`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceError"
                }
              }
            }
          }
        }
      }
    },
    "/me/help": {
      "get": {
        "tags": [
          "Resources · Fundraisers"
        ],
        "summary": "My help",
        "operationId": "getMyHelp",
        "description": "The signed-in person's My help summary, which only they see: the providers they saved (newest first, up to 50), their fundraisers that name help with where gifts go and each link as the organizer sees it (up to 20), and up to 3 open free stuff items (null while free stuff is off for them). Never cached.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MyHelp"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Resources are switched off."
          }
        }
      }
    },
    "/events": {
      "get": {
        "tags": [
          "Events"
        ],
        "summary": "List events",
        "operationId": "listEvents",
        "description": "Live, listed, not suspended events as list rows: upcoming (soonest first, the default) or past (latest first). Feeds /events, city, community and host pages and the Fundly page. Filters take an id or a slug (member and fundraiser: an id). A sponsor's events are the ones it hosts and the ones it sponsors (`sponsor_role` for one of the two). A community's active members also get its members-only events that are not listed on /events (#2495). The first page (no cursor) says how many rows the filters match in all (`total`). No account needed; 404 while Events are switched off (features.events).",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "when",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "upcoming",
                "past"
              ],
              "default": "upcoming"
            }
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "A city place's id or slug."
          },
          {
            "name": "price",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "free",
                "paid"
              ]
            }
          },
          {
            "name": "community",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Id or slug of a hosting community."
          },
          {
            "name": "organization",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Id or slug of a hosting non-profit or church."
          },
          {
            "name": "sponsor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Id or slug of a sponsor that hosts or sponsors."
          },
          {
            "name": "sponsor_role",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "hosting",
                "sponsoring"
              ]
            },
            "description": "With `sponsor` (#2495), only the events it hosts or only the ones it sponsors; both when left out."
          },
          {
            "name": "member",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "A hosting member."
          },
          {
            "name": "fundraiser",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "A Fundly the events raise money for."
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "`next_cursor` of the page before."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of rows.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventList"
                }
              }
            }
          },
          "404": {
            "description": "Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`invalid_filter` (`details.filter`) or `invalid_cursor`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Start an event (a draft)",
        "operationId": "createEvent",
        "description": "A new draft with its main host: an identity the caller acts for (`host`: themselves, a non-profit or church they manage, a community they lead, a sponsor they own; themselves when left out). FundlyHub is never automatically added. A super administrator or ambassador can explicitly select `{kind: platform, id: null}`. Only a super administrator may select another identity with `accept_without_invitation: true`. `time_zone` is required; anything else already typed may come along. A free event gets its RSVP ticket type. The link is made from the title when not given.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EventInput"
                  },
                  {
                    "type": "object",
                    "required": [
                      "time_zone"
                    ],
                    "properties": {
                      "host": {
                        "$ref": "#/components/schemas/EventHostSelection"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The draft.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "slug": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`cannot_host_as`, `cannot_host_as_platform`, or `cannot_accept_host_invitation`: the caller lacks the explicit role or identity grant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "404": {
            "description": "Events are switched off, or (staff) no such host.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`slug_taken`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, `invalid_slug`, `venue_address_unresolved`, `venue_not_an_address`, `unknown_city`, `not_a_host_community`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/slug/{slug}/og-image": {
      "get": {
        "tags": [
          "Events"
        ],
        "summary": "Event link-preview image",
        "operationId": "getEventOgImage",
        "description": "The event's 1200×630 Open Graph picture: its complete cover fitted inside the frame without cropping invitation text or logos, or a card with its title, date and place. Public and cached for five minutes, one answer per URL whoever asks; an event a stranger may not see is the same `404` as an unknown link.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Language to render in. Without it the locale cookie, then `Accept-Language`, decide.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          },
          {
            "name": "v",
            "in": "query",
            "required": false,
            "description": "The cover and preview-layout version, so a new cover or layout is a new URL. Ignored by the server.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "shape",
            "in": "query",
            "required": false,
            "description": "The complete cover fitted inside this shape. Unused space uses the event theme background.",
            "schema": {
              "type": "string",
              "enum": [
                "square",
                "4x3",
                "16x9"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The picture.",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Events are switched off, or no event a stranger may see has that link.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Rendering failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/slug/{slug}/share-poster": {
      "get": {
        "tags": [
          "Events"
        ],
        "summary": "Event square share poster",
        "operationId": "getEventSharePoster",
        "description": "A 1080×1080 picture for feed posts (#2490). Same data, language rules, caching and `404` as the link-preview image.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Language to render in. Without it the locale cookie, then `Accept-Language`, decide.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          },
          {
            "name": "v",
            "in": "query",
            "required": false,
            "description": "The cover's version, so a new cover is a new URL. Ignored by the server.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The picture.",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Events are switched off, or no event a stranger may see has that link.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Rendering failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/slug/{slug}/share-story": {
      "get": {
        "tags": [
          "Events"
        ],
        "summary": "Event story card",
        "operationId": "getEventShareStory",
        "description": "A 1080×1920 picture for Instagram and Facebook Stories (#2490). Same data, language rules, caching and `404` as the link-preview image.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Language to render in. Without it the locale cookie, then `Accept-Language`, decide.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ru",
                "uk",
                "es"
              ]
            }
          },
          {
            "name": "v",
            "in": "query",
            "required": false,
            "description": "The cover's version, so a new cover is a new URL. Ignored by the server.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The picture.",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Events are switched off, or no event a stranger may see has that link.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Rendering failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/slug/{slug}": {
      "get": {
        "tags": [
          "Events"
        ],
        "summary": "The event page",
        "operationId": "getEventBySlug",
        "description": "The event, its days, hosts, ticket types with availability, sponsors, volunteer roles with open slots, linked Fundlies with raised, photos, the computed sale status and the `viewer` block. A live event that is not suspended is public; a draft, an event in review, with changes requested, rejected or suspended answers 404 to anyone but its hosts and staff. An old link answers 301 to the current one. Never cached by a shared cache.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The page.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventPage"
                }
              }
            }
          },
          "301": {
            "description": "An old link: `Location` is the current one."
          },
          "404": {
            "description": "No such event, not visible to the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/volunteer-signups": {
      "post": {
        "tags": [
          "Events"
        ],
        "summary": "Volunteer from the page",
        "operationId": "signUpToVolunteer",
        "description": "A sign-up to a role open to sign-ups, on a live event that has not ended, for the hosts to approve (`requested`). Signed in, the person is the volunteer; signed out, `name` and `email` are required. 5 a minute per address.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EventPersonInput"
                  },
                  {
                    "type": "object",
                    "required": [
                      "role_id"
                    ],
                    "properties": {
                      "role_id": {
                        "type": "string",
                        "format": "uuid"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Signed up.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "requested"
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such public event or role.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed`, `role_not_open`, `role_full`, `already_volunteering`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, `name_and_email_required`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/events/{id}/sponsor-requests": {
      "post": {
        "tags": [
          "Events"
        ],
        "summary": "\"Sponsor this dinner\"",
        "operationId": "requestToSponsorEvent",
        "description": "A business asks to sponsor a live event that has not ended; the hosts see it in the Sponsors tab. 5 a minute per address.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "business_name",
                  "contact_name",
                  "email"
                ],
                "properties": {
                  "business_name": {
                    "type": "string"
                  },
                  "contact_name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Sent.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "new"
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such public event.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed`: ended, cancelled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/events/{id}/report": {
      "post": {
        "tags": [
          "Events"
        ],
        "summary": "Report an event",
        "operationId": "reportEvent",
        "description": "\"Something wrong with this event? Report\". Signed in with a verified email; one report per person and event (a second replaces the first). Hosts cannot report their own event. Staff review reports; nothing is taken down automatically.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reason"
                ],
                "properties": {
                  "reason": {
                    "type": "string",
                    "minLength": 5,
                    "maxLength": 500
                  },
                  "details": {
                    "type": "string",
                    "maxLength": 2000,
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Reported.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Email not verified (`EMAIL_NOT_VERIFIED`)."
          },
          "404": {
            "description": "No such public event.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`own_event`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}": {
      "patch": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Edit an event",
        "operationId": "updateEvent",
        "description": "Saved as the host types. Editable until the event ends (not when rejected, cancelled, or, for hosts, suspended). A venue sets the city to the venue's. On a live event a changed place is published as `event.rescheduled`; a live event must keep a title and a place. Answers with the page.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The page after the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Delete a draft",
        "operationId": "deleteEvent",
        "description": "An event that never went live (draft, changes requested or rejected). It is kept, marked deleted, and answers 404 from then on.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Done."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/slug-check": {
      "get": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Check an event link",
        "operationId": "checkEventSlug",
        "description": "May this event use the link: not invalid, not reserved, not another event's (now or before). The event's own earlier links are free for it.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "slug",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The answer.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "available": {
                      "type": "boolean"
                    },
                    "reason": {
                      "type": "string",
                      "enum": [
                        "invalid",
                        "reserved",
                        "taken"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/days": {
      "put": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Save the days",
        "operationId": "saveEventDays",
        "description": "The whole list (at most 14), each ending after it starts; sorted by start. A day keeps its id when the list names it. Removing a day a ticket type is for answers 409 `day_in_use`. A live event keeps at least one day; a changed date or time on it is published as `event.rescheduled`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "days"
                ],
                "properties": {
                  "days": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "starts_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "ends_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The days.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "days": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EventDay"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/fundraisers": {
      "put": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Save the Fundlies and their shares",
        "operationId": "saveEventFundraisers",
        "description": "The whole list: 1 to 10 Fundlies, whole-percent shares of 1 to 100, adding up to no more than 100, exactly 100 on a live event (`shares_must_total_100`). A Fundly newly linked must be live and taking gifts (`fundraiser_not_open`, `details.fundraiser_ids`). Other refusals: `too_many_fundraisers`, `duplicate_fundraiser`, `share_out_of_range`, `shares_over_100`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "fundraisers"
                ],
                "properties": {
                  "fundraisers": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "fundraiser_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "share_percent": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The shares.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "fundraisers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EventFundraiserShare"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/submit": {
      "post": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Submit for review",
        "operationId": "submitEvent",
        "description": "Needs a verified email, a title, a date, a place (a venue, online, or to be announced), Fundly shares adding up to 100 and a ticket type (`event_incomplete`, `details.problems` are i18n keys). Hosts send it to staff review (`event.submitted`); staff with manage_events publish it at once (`event.approved`, not reviewed).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The new status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "in_review",
                        "published"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/duplicate": {
      "post": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Duplicate an event",
        "operationId": "duplicateEvent",
        "description": "A new draft with the event's details, days, Fundly shares, ticket types (not stopped or code-only ones) and volunteer roles, hosted by the host the caller acts for.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The copy.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "slug": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/postpone": {
      "post": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Postpone a live event",
        "operationId": "postponeEvent",
        "description": "With new days, or none for \"new date coming\". Tickets stay valid. Published as `event.postponed`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "days": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "starts_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "ends_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The page.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/cancel": {
      "post": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Cancel a live event",
        "operationId": "cancelEvent",
        "description": "Sales stop and the page says it is cancelled; it stays up so shared links still explain. Published as `event.cancelled`. Refunds arrive with tickets (phase 6).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The page.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/ticket-types": {
      "post": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Add a ticket type",
        "operationId": "createEventTicketType",
        "description": "At most 20. A free event's types are $0 (`free_event_price`); the value of the dinner is at most the price; \"only with a code\" needs `access_code`; \"members of a host community\" needs a community host (`no_host_community`); a \"one day each\" event gives each type its day (`day_required`, `unknown_day`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EventTicketTypeInput"
                  },
                  {
                    "type": "object",
                    "required": [
                      "name"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The type.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventTicketType"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/ticket-types/{typeId}": {
      "patch": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Change a ticket type",
        "operationId": "updateEventTicketType",
        "description": "Only while it has sold nothing (`ticket_type_has_sales`) and is not stopped (`ticket_type_stopped`); the same rules as adding.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "typeId",
            "in": "path",
            "required": true,
            "description": "The ticket type.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventTicketTypeInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The type.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventTicketType"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Delete a ticket type",
        "operationId": "deleteEventTicketType",
        "description": "Only one that never sold (`ticket_type_has_sales`); a free event keeps one open RSVP type (`rsvp_type_required`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "typeId",
            "in": "path",
            "required": true,
            "description": "The ticket type.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Done."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/ticket-types/{typeId}/stop": {
      "post": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Stop selling a ticket type",
        "operationId": "stopEventTicketType",
        "description": "Its tickets stay valid. The way to end a type that has sold.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "typeId",
            "in": "path",
            "required": true,
            "description": "The ticket type.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The type.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventTicketType"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/hosts": {
      "post": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Invite a co-host",
        "operationId": "inviteEventHost",
        "description": "A member, non-profit or church, community or sponsor business. It shows on the page once it accepts (`event_host.invited`); one the caller acts for is added accepted at once (`event_host.accepted`). An explicit super-admin override accepts immediately without sending an invitation. Only a super administrator or ambassador can add FundlyHub as an explicit platform host. A declined host can be invited again. At most 10.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventHostSelection"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The host row.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "invited",
                        "accepted"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`cannot_host_as_platform` or `cannot_accept_host_invitation`: the caller lacks the required explicit role.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Save the co-host list",
        "operationId": "saveEventHosts",
        "description": "The editor's whole host list, including any explicitly selected platform row, saved atomically by draft autosave or live Save changes. Omitted rows are removed; existing rows keep their status unless a super administrator explicitly accepts a pending invitation with `accept_without_invitation: true`. Adding platform requires super_admin or ambassador; an authorized editor can keep or remove an existing platform row. Non-staff must keep one accepted host (`last_host`). Invitations and acceptance events are sent only after commit, once; repeating the saved list sends no duplicate invitation or acceptance.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "hosts"
                ],
                "properties": {
                  "hosts": {
                    "type": "array",
                    "maxItems": 10,
                    "items": {
                      "$ref": "#/components/schemas/EventHostSelection"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "What the save changed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "added": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "invited",
                              "accepted"
                            ]
                          },
                          "target": {
                            "type": "object",
                            "properties": {
                              "kind": {
                                "type": "string"
                              },
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              }
                            }
                          }
                        }
                      }
                    },
                    "removed": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "format": "uuid"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "`cannot_host_as_platform` or `cannot_accept_host_invitation`: the caller lacks the required explicit role.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "404": {
            "description": "No such event, not a host of it, a host that does not exist, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or `last_host`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or `too_many_hosts`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/hosts/{hostId}": {
      "delete": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Remove a co-host",
        "operationId": "removeEventHost",
        "description": "An authorized editor can remove any host including an explicit FundlyHub row; the event keeps one accepted host (`last_host`, staff excepted).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "hostId",
            "in": "path",
            "required": true,
            "description": "The host row.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Done."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/volunteers": {
      "get": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "The Volunteers tab",
        "operationId": "listEventVolunteers",
        "description": "The roles with filled and open slots, and everyone in them.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Roles and volunteers.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "roles": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EventVolunteerRole"
                      }
                    },
                    "volunteers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EventVolunteer"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/volunteer-roles": {
      "post": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Add a volunteer role",
        "operationId": "createEventVolunteerRole",
        "description": "At most 30.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EventVolunteerRoleInput"
                  },
                  {
                    "type": "object",
                    "required": [
                      "name"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The role.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventVolunteerRole"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/volunteer-roles/{roleId}": {
      "patch": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Change a volunteer role",
        "operationId": "updateEventVolunteerRole",
        "description": "Slots never drop below the people confirmed (`slots_below_confirmed`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "roleId",
            "in": "path",
            "required": true,
            "description": "The role.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventVolunteerRoleInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The role.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventVolunteerRole"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Delete a volunteer role",
        "operationId": "deleteEventVolunteerRole",
        "description": "With everyone in it.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "roleId",
            "in": "path",
            "required": true,
            "description": "The role.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Done."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/volunteer-roles/{roleId}/volunteers": {
      "post": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Add a volunteer",
        "operationId": "addEventVolunteer",
        "description": "A member (`profile_id`, invited) or someone without an account (`name` and `email`, confirmed; `role_full` when every slot is filled).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "roleId",
            "in": "path",
            "required": true,
            "description": "The role.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventPersonInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The volunteer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventVolunteer"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/volunteers/{volunteerId}": {
      "patch": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Change a volunteer",
        "operationId": "updateEventVolunteer",
        "description": "Name, email, phone and note.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "volunteerId",
            "in": "path",
            "required": true,
            "description": "The volunteer.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventPersonInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The volunteer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventVolunteer"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Remove a volunteer",
        "operationId": "removeEventVolunteer",
        "description": "",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "volunteerId",
            "in": "path",
            "required": true,
            "description": "The volunteer.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Done."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/volunteers/{volunteerId}/approve": {
      "post": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Approve a sign-up",
        "operationId": "approveEventVolunteer",
        "description": "A `requested` sign-up becomes confirmed (`not_requested`, `role_full`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "volunteerId",
            "in": "path",
            "required": true,
            "description": "The volunteer.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The volunteer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventVolunteer"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/volunteers/{volunteerId}/decline": {
      "post": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Decline a sign-up or an invitation",
        "operationId": "declineEventVolunteer",
        "description": "`not_pending` otherwise.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "volunteerId",
            "in": "path",
            "required": true,
            "description": "The volunteer.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The volunteer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventVolunteer"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/sponsors": {
      "get": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "The Sponsors tab",
        "operationId": "listEventSponsors",
        "description": "Every sponsor, with the hosts' bookkeeping, and the requests from the page, newest first.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sponsors and requests.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sponsors": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EventSponsor"
                      }
                    },
                    "requests": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EventSponsorRequest"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Add a sponsor",
        "operationId": "createEventSponsor",
        "description": "At most 50; one presenting sponsor (`presenting_sponsor_taken`); a FundlyHub sponsor once (`sponsor_already_added`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventSponsorInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The sponsor.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventSponsor"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/sponsors/order": {
      "put": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Reorder the sponsors",
        "operationId": "reorderEventSponsors",
        "description": "Every sponsor id once, in the new order (`order_mismatch`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ids"
                ],
                "properties": {
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The sponsors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sponsors": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EventSponsor"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/sponsors/{sponsorId}": {
      "patch": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Change a sponsor",
        "operationId": "updateEventSponsor",
        "description": "A FundlyHub sponsor's name, logo and page come from its profile (`fundlyhub_sponsor_profile`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "sponsorId",
            "in": "path",
            "required": true,
            "description": "The sponsor row.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventSponsorInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The sponsor.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventSponsor"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Remove a sponsor",
        "operationId": "deleteEventSponsor",
        "description": "",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "sponsorId",
            "in": "path",
            "required": true,
            "description": "The sponsor row.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Done."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/sponsor-requests/{requestId}": {
      "patch": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Answer a sponsor request",
        "operationId": "updateEventSponsorRequest",
        "description": "Mark it replied, added or dismissed. Stays open after the event.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "description": "The request.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "status"
                ],
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "new",
                      "replied",
                      "added",
                      "dismissed"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventSponsorRequest"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Delete a sponsor request",
        "operationId": "deleteEventSponsorRequest",
        "description": "",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "description": "The request.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Done."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/photos": {
      "get": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "The gallery",
        "operationId": "listEventPhotos",
        "description": "Every photo, those to review and hidden too.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Photos.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "photos": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EventPhoto"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Add a photo",
        "operationId": "addEventPhoto",
        "description": "Uploaded with POST /storage/upload. Hosts add it shown (optionally as the cover); a confirmed volunteer in a role that may upload photos may add one too, and it waits as `to_review`. At most 200.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "is_cover": {
                    "type": "boolean"
                  },
                  "focal_x": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "nullable": true,
                    "description": "The crop tool's focal point (#2499); left out, the server works one out from the photo."
                  },
                  "focal_y": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The photo.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventPhoto"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/photos/order": {
      "put": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Reorder the gallery",
        "operationId": "reorderEventPhotos",
        "description": "Every photo id once, in the new order (`order_mismatch`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ids"
                ],
                "properties": {
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Photos.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "photos": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EventPhoto"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/photos/{photoId}": {
      "patch": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Show, hide or make the cover",
        "operationId": "updateEventPhoto",
        "description": "The cover is one shown photo (`cover_must_show`); only a hidden photo has a reason (`reason_for_hidden_only`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "photoId",
            "in": "path",
            "required": true,
            "description": "The photo.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "to_review",
                      "shown",
                      "hidden"
                    ]
                  },
                  "hidden_reason": {
                    "type": "string",
                    "nullable": true
                  },
                  "is_cover": {
                    "type": "boolean"
                  },
                  "focal_x": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "nullable": true,
                    "description": "Move the focal point (#2499); one half alone moves only that half."
                  },
                  "focal_y": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The photo.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventPhoto"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Delete a photo",
        "operationId": "deleteEventPhoto",
        "description": "",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "photoId",
            "in": "path",
            "required": true,
            "description": "The photo.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Done."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/recap": {
      "patch": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Write the recap",
        "operationId": "updateEventRecap",
        "description": "Any time a live event is not cancelled; published once it has ended.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventRecapInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The recap.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/recap/publish": {
      "post": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Publish the recap",
        "operationId": "publishEventRecap",
        "description": "Once the event has ended (`not_allowed`, `events.viewer.reasons.not_ended` before). Published as `event.recap_published`, with whether to email the guests.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email_guests": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The page.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such event, not a host of it, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` (the rules: `details.reason` is the viewer block's key), or a clash named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule named by `code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/event-hosts/{id}/accept": {
      "post": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Accept a co-host invitation",
        "operationId": "acceptEventHostInvitation",
        "description": "By someone who acts for the invited host. The host then shows on the page (`event_host.accepted`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The invitation (host row).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "event_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such invitation for the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_invited`: already answered.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/event-hosts/{id}/decline": {
      "post": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Decline a co-host invitation",
        "operationId": "declineEventHostInvitation",
        "description": "By someone who acts for the invited host.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The invitation (host row).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Declined.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "event_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such invitation for the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_invited`: already answered.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/me/events": {
      "get": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Your events",
        "operationId": "getMyEvents",
        "description": "Hosting: every event (any state but deleted) with an accepted host the caller acts for, latest first (`items`); with `as`, only the events that one identity hosts (a workspace's Events tab, #2494). Going (#2487): every event the caller holds tickets for, as the buyer or a guest named on a ticket, as `upcoming` (soonest first) and `past` (latest first), each row with their `tickets`.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "tab",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "hosting",
                "going"
              ],
              "default": "hosting"
            }
          },
          {
            "$ref": "#/components/parameters/EventHostAs"
          }
        ],
        "responses": {
          "200": {
            "description": "Rows.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "description": "The hosting tab.",
                      "items": {
                        "$ref": "#/components/schemas/EventListRow"
                      }
                    },
                    "upcoming": {
                      "type": "array",
                      "description": "The going tab: rows with `tickets`.",
                      "items": {
                        "$ref": "#/components/schemas/EventListRow"
                      }
                    },
                    "past": {
                      "type": "array",
                      "description": "The going tab: rows with `tickets`.",
                      "items": {
                        "$ref": "#/components/schemas/EventListRow"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`invalid_tab`, `invalid_as`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/me/event-host-invitations": {
      "get": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Co-host invitations for you",
        "operationId": "getMyEventHostInvitations",
        "description": "Invitations naming the caller or a non-profit, church, community or sponsor they act for, newest first; with `as`, only those naming that one identity (#2494). Each invitation also reaches the people who can answer it as a bell notice and an email (`event_host_invited`, metadata `hostId`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/EventHostAs"
          }
        ],
        "responses": {
          "200": {
            "description": "Invitations.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "as": {
                            "type": "object",
                            "properties": {
                              "kind": {
                                "type": "string"
                              },
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "name": {
                                "type": "string",
                                "nullable": true
                              }
                            }
                          },
                          "invited_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "event": {
                            "$ref": "#/components/schemas/EventListRow"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`invalid_as`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/me/event-candidates": {
      "get": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Find an Event member, co-host or sponsor identity",
        "operationId": "getMyEventCandidates",
        "description": "A fresh authenticated identity lookup for Event editors. Names and profile handles are searched directly; no email or private biography is searched or returned. Inactive/deleting members are excluded. Sponsor choices do not require discoverable perks: public sponsor pages are available, while private applications require current sponsor-team or sponsor-specific staff authority. Returned identity fields are minimal. Responses use private, no-store caching and vary by Cookie and Authorization.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 80
            },
            "description": "Fewer than two characters return no choices."
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "member",
                "organization",
                "community",
                "sponsor"
              ],
              "default": "all"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching identities, without private contact or sponsor bookkeeping fields.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "items"
                  ],
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EventCandidate"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "Unknown identity kind.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/me/event-identities": {
      "get": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Who you can host as",
        "operationId": "getMyEventIdentities",
        "description": "The identities the caller can host an event as (#2494): themself, and each non-profit, church, community and sponsor business they act for; staff publishing access and separate strict role-based host capabilities. Platform choice is for super administrators or ambassadors; consent override is for super administrators only. The app shows its Events tabs and \"Host an event\" only once this answers 200: a 404 means Events are switched off for the caller.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Identities.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "items",
                    "staff",
                    "can_accept_host_invitations",
                    "can_host_as_platform"
                  ],
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "kind": {
                            "type": "string",
                            "enum": [
                              "member",
                              "organization",
                              "community",
                              "sponsor"
                            ]
                          },
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "staff": {
                      "type": "boolean"
                    },
                    "can_accept_host_invitations": {
                      "type": "boolean"
                    },
                    "can_host_as_platform": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/me/event-venues": {
      "get": {
        "tags": [
          "Events · Hosts"
        ],
        "summary": "Saved venues",
        "operationId": "getMyEventVenues",
        "description": "The open premises (with an address) of the non-profits, churches, communities and sponsors the caller acts for, to pick as a venue (`venue_place_id`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Venues.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "label": {
                            "type": "string",
                            "nullable": true
                          },
                          "owner": {
                            "type": "object",
                            "properties": {
                              "kind": {
                                "type": "string"
                              },
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "name": {
                                "type": "string",
                                "nullable": true
                              }
                            }
                          },
                          "place": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/orders": {
      "post": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "Start checkout",
        "operationId": "createEventOrder",
        "description": "Holds seats for 10 minutes: under the event's row lock, the seats left are counted (capacity, each ticket type, per day for \"one day each\") and a held order with one ticket per seat is written. Prices, the value of the dinner and the Fundly shares are copied onto it. Signed out (when the event takes guests without an account), `buyer_name` and `buyer_email` are required and the answer carries the order link's `access_token`, once. A buyer's earlier held order for the event is released. 5 a minute per address.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "lines"
                ],
                "additionalProperties": false,
                "properties": {
                  "lines": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "object",
                      "required": [
                        "ticket_type_id",
                        "quantity"
                      ],
                      "properties": {
                        "ticket_type_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "quantity": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 100
                        }
                      }
                    }
                  },
                  "event_day_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "The day, for a \"one day each\" event."
                  },
                  "access_code": {
                    "type": "string",
                    "description": "For an \"only with a code\" ticket type."
                  },
                  "buyer_name": {
                    "type": "string",
                    "description": "Signed out: the buyer's name."
                  },
                  "buyer_email": {
                    "type": "string",
                    "format": "email",
                    "description": "Signed out: the buyer's email."
                  },
                  "language": {
                    "type": "string",
                    "enum": [
                      "en",
                      "ru",
                      "uk",
                      "es"
                    ]
                  },
                  "ref": {
                    "type": "string",
                    "description": "A referral code the buyer arrived with."
                  },
                  "show_attending": {
                    "type": "boolean",
                    "description": "Show the buyer's face among who is going."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Held.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "order": {
                      "$ref": "#/components/schemas/EventOrder"
                    },
                    "access_token": {
                      "type": "string"
                    },
                    "hold_minutes": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`unauthorized`: this event needs an account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*), `order_in_progress`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule on the input (the code names it).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/event-orders/{id}": {
      "get": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "An order",
        "operationId": "getEventOrder",
        "description": "The buyer's order (by account or the order link) or, for the event's hosts and staff, any of its orders.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "token",
            "in": "query",
            "required": false,
            "description": "The order link's token (or send it as `X-Order-Token`), for a buyer without an account. The buyer's first ticket code works too.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Order-Token",
            "in": "header",
            "required": false,
            "description": "The order link's token, for a buyer without an account.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The order.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventOrder"
                }
              }
            }
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "Fill in an order",
        "operationId": "updateEventOrder",
        "description": "While held: guests' names and emails, dietary needs, a gift, covering the card fee. Totals are recomputed; a PaymentIntent already made follows the new total.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "X-Order-Token",
            "in": "header",
            "required": false,
            "description": "The order link's token, for a buyer without an account.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "buyer_name": {
                    "type": "string"
                  },
                  "buyer_email": {
                    "type": "string",
                    "format": "email"
                  },
                  "language": {
                    "type": "string",
                    "enum": [
                      "en",
                      "ru",
                      "uk",
                      "es"
                    ]
                  },
                  "show_attending": {
                    "type": "boolean"
                  },
                  "gift_cents": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10000000,
                    "description": "A gift, split by the shares like ticket money."
                  },
                  "cover_fee": {
                    "type": "boolean",
                    "description": "Cover the card fee (the donation rule)."
                  },
                  "tickets": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "id"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "guest_name": {
                          "type": "string",
                          "nullable": true
                        },
                        "guest_email": {
                          "type": "string",
                          "format": "email",
                          "nullable": true
                        },
                        "dietary": {
                          "type": "string",
                          "nullable": true,
                          "enum": [
                            "none",
                            "vegetarian",
                            "vegan",
                            "gluten_free",
                            "other"
                          ]
                        },
                        "dietary_note": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The order.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventOrder"
                }
              }
            }
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule on the input (the code names it).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/event-orders/{id}/pay": {
      "post": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "Pay for an order",
        "operationId": "payEventOrder",
        "description": "Free: confirmed at once (requested when the hosts approve each reservation). Paid: a PaymentIntent on the platform account (no destination; `metadata.kind = event_order`, `metadata.order_id`; manual capture when approval is on, charged only when a host approves), and its client secret. The money is split into one ordinary gift per Fundly when the payment succeeds (the Stripe webhook).",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "X-Order-Token",
            "in": "header",
            "required": false,
            "description": "The order link's token, for a buyer without an account.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The order, and the payment to confirm (null when free).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "order": {
                      "$ref": "#/components/schemas/EventOrder"
                    },
                    "payment": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "client_secret": {
                          "type": "string"
                        },
                        "payment_intent_id": {
                          "type": "string"
                        },
                        "amount_cents": {
                          "type": "integer"
                        },
                        "capture": {
                          "type": "string",
                          "enum": [
                            "automatic",
                            "manual"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*), `payment_in_progress`; a Fundly that cannot take gifts: `events.orders.reasons.fundraiser_cannot_receive`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`amount_too_small`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/event-orders/{id}/confirm-payment": {
      "post": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "Settle an order right after its card payment",
        "operationId": "confirmEventOrderPayment",
        "description": "Called by checkout right after the card is confirmed, so the ticket shows without waiting for the Stripe webhook. The server reads the order's own PaymentIntent from Stripe (never one the caller names) and, when it succeeded, records the order paid through the same idempotent path as the webhook (the order paid once, its money split once per Fundly); a card authorized for an order that needs the hosts' approval makes it a request. The webhook that arrives afterwards changes nothing. Any other payment state, or Stripe being unreachable, leaves the order as it is: keep reading `GET /event-orders/{id}`. The buyer only: by account or the order link's token.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "X-Order-Token",
            "in": "header",
            "required": false,
            "description": "The order link's token, for a buyer without an account.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The order as it is now.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventOrder"
                }
              }
            }
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/event-orders/{id}/cancel": {
      "post": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "Cancel an order",
        "operationId": "cancelEventOrder",
        "description": "Withdraw a request (the card's hold is released), or cancel before the free-cancellation date (a free RSVP: until the event starts), refunded in full through each gift's refund path. The seats go back and the waitlist is offered them. The buyer only: by account, the order link's token, or `buyer_code`, the code of the order's first ticket (what the ticket email's link carries). Anyone else, and a wrong code, gets 404.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "X-Order-Token",
            "in": "header",
            "required": false,
            "description": "The order link's token, for a buyer without an account.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "buyer_code": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{22}$",
                    "description": "The order's first ticket's code, for a buyer without an account or the order's token."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The order.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventOrder"
                }
              }
            }
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "502": {
            "description": "`refund_failed`: Stripe refused; nothing changed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/event-orders/{id}/refund-request": {
      "post": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "Ask the hosts for a refund",
        "operationId": "requestEventRefund",
        "description": "After the free-cancellation date and until 30 days after the event: the hosts (or staff) refund or decline it. One open request per order. The buyer proves the order as for cancel (account, token or `buyer_code`).",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "X-Order-Token",
            "in": "header",
            "required": false,
            "description": "The order link's token, for a buyer without an account.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reason"
                ],
                "properties": {
                  "reason": {
                    "type": "string",
                    "enum": [
                      "cant_attend",
                      "event_changed",
                      "duplicate",
                      "other"
                    ]
                  },
                  "note": {
                    "type": "string",
                    "nullable": true
                  },
                  "buyer_code": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{22}$",
                    "description": "The order's first ticket's code, for a buyer without an account or the order's token."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The order.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventOrder"
                }
              }
            }
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule on the input (the code names it).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/event-orders/{id}/receipt": {
      "get": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "The receipt of an order",
        "operationId": "getEventOrderReceipt",
        "description": "Who may see the order may see its receipt.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "token",
            "in": "query",
            "required": false,
            "description": "The order link's token (or send it as `X-Order-Token`), for a buyer without an account. The buyer's first ticket code works too.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Order-Token",
            "in": "header",
            "required": false,
            "description": "The order link's token, for a buyer without an account.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The receipt.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventReceipt"
                }
              }
            }
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/event-tickets/{code}": {
      "get": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "A ticket",
        "operationId": "getEventTicket",
        "description": "Whoever holds the code. Answers `Referrer-Policy: no-referrer`, never cached, never indexed.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "The ticket's code: 16 random bytes, base64url (22 characters). It is the ticket.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{22}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The ticket.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventTicketPage"
                }
              }
            }
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/event-tickets/{code}/send": {
      "post": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "Send a guest their ticket",
        "operationId": "sendEventTicket",
        "description": "The buyer (by account, the order link, or `buyer_code`, the order's first ticket's code) sends a guest's ticket to the guest's email.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "The ticket's code: 16 random bytes, base64url (22 characters). It is the ticket.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{22}$"
            }
          },
          {
            "name": "X-Order-Token",
            "in": "header",
            "required": false,
            "description": "The order link's token, for a buyer without an account.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "name": {
                    "type": "string"
                  },
                  "buyer_code": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sent.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "sent_to": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule on the input (the code names it).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/event-tickets/{code}/wallet": {
      "get": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "A ticket's Apple Wallet pass",
        "operationId": "getEventTicketWalletPass",
        "description": "An `eventTicket` .pkpass with the ticket's QR code, the date, the venue and a reminder near it. 503 `wallet_unavailable` until the Pass Type ID certificate set is configured.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "The ticket's code: 16 random bytes, base64url (22 characters). It is the ticket.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{22}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The pass.",
            "content": {
              "application/vnd.apple.pkpass": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "503": {
            "description": "Wallet is not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/calendar.ics": {
      "get": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "The calendar file",
        "operationId": "getEventCalendar",
        "description": "One VEVENT per day, a stable UID and a SEQUENCE that grows with every change. A hidden address shows only with `?ticket=` a ticket of the event.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "ticket",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The file.",
            "content": {
              "text/calendar": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/waitlist": {
      "post": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "Join the waitlist",
        "operationId": "joinEventWaitlist",
        "description": "A sold-out event with the waitlist on. When seats come back the next people in line whose seats fit get them for 24 hours. Signed out, `name` and `email`; the answer carries the place's `token`, once.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ticket_type_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "event_day_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "quantity": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10
                  },
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "language": {
                    "type": "string",
                    "enum": [
                      "en",
                      "ru",
                      "uk",
                      "es"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "On the list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entry": {
                      "$ref": "#/components/schemas/EventWaitlistEntry"
                    },
                    "token": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`unauthorized`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*), `already_waiting`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule on the input (the code names it).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/sale-alert": {
      "post": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "Notify me when tickets go on sale",
        "operationId": "requestEventSaleAlert",
        "description": "While an event's tickets are not on sale yet (`sale_status` `not_on_sale_yet`), ask to be told when they are. Signed in, one click (the account; `viewer.sale_alert` then reads true); signed out, an `email`. One per person or email per event; asking again answers `already`. When sales open (the sales start passes, or a host or staff opens them) each one gets one email, and a member a bell notice, in the Events email category (one-click unsubscribe).",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Signed out only; lowercased."
                  },
                  "language": {
                    "type": "string",
                    "enum": [
                      "en",
                      "ru",
                      "uk",
                      "es"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Already on the list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "state": {
                      "type": "string",
                      "enum": [
                        "already"
                      ]
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "On the list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "state": {
                      "type": "string",
                      "enum": [
                        "added"
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` `events.alerts.reasons.on_sale` or `events.alerts.reasons.not_waiting`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`email_required` (signed out with no email), or a body that is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/waitlist/me": {
      "delete": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "Leave the waitlist",
        "operationId": "leaveEventWaitlist",
        "description": "An offer given back goes to the next person in line.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "token",
            "in": "query",
            "required": false,
            "description": "The order link's token (or send it as `X-Order-Token`), for a buyer without an account. The buyer's first ticket code works too.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Order-Token",
            "in": "header",
            "required": false,
            "description": "The order link's token, for a buyer without an account.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Left."
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/event-waitlist/{id}/claim": {
      "post": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "Claim a waitlist offer",
        "operationId": "claimEventWaitlistOffer",
        "description": "The offer becomes a held order to pay, kept until the offer runs out.",
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The waitlist place's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "X-Order-Token",
            "in": "header",
            "required": false,
            "description": "The order link's token, for a buyer without an account.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The order.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventOrder"
                }
              }
            }
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/event-volunteers/{id}/confirm": {
      "post": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "Confirm a volunteer invitation",
        "operationId": "confirmEventVolunteerInvitation",
        "description": "The member a host invited to a role says yes. A full role takes no more.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The volunteer row's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Confirmed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_invited`, `role_full`, `not_allowed`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/event-volunteers/{id}/decline": {
      "post": {
        "tags": [
          "Events · Tickets"
        ],
        "summary": "Decline a volunteer invitation",
        "operationId": "declineEventVolunteerInvitation",
        "description": "The member a host invited says no.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The volunteer row's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Declined.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_invited`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/people": {
      "get": {
        "tags": [
          "Events · People"
        ],
        "summary": "People",
        "operationId": "getEventPeople",
        "description": "Every order with its tickets, the counts (going, members and guests, checked in, requests, refund requests, waitlist, revenue) and the waitlist.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "going",
                "requested",
                "checked_in",
                "not_checked_in",
                "refunds",
                "cancelled"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "People.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventPeople"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`invalid_filter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Events · People"
        ],
        "summary": "Add people",
        "operationId": "addEventPeople",
        "description": "A member or someone without an account: a comp or paid outside FundlyHub (confirmed at once, no money), or a payment link (held 48 hours and emailed). Hidden ticket types may be used. A comp may instead explicitly request complimentary admission. A genuinely unconfigured free event first restores its canonical public RSVP types (one per saved day for one-day-each events); otherwise a hidden free admission type is reused or created atomically without changing configured ticket sales or registration. Select a saved event day for one-day-each admission. Audited.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "kind",
                  "quantity"
                ],
                "oneOf": [
                  {
                    "required": [
                      "ticket_type_id"
                    ],
                    "not": {
                      "properties": {
                        "complimentary_admission": {
                          "enum": [
                            true
                          ]
                        }
                      },
                      "required": [
                        "complimentary_admission"
                      ]
                    }
                  },
                  {
                    "required": [
                      "complimentary_admission"
                    ],
                    "properties": {
                      "kind": {
                        "enum": [
                          "comp"
                        ]
                      },
                      "complimentary_admission": {
                        "enum": [
                          true
                        ]
                      }
                    },
                    "not": {
                      "required": [
                        "ticket_type_id"
                      ]
                    }
                  }
                ],
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "comp",
                      "paid_outside",
                      "payment_link"
                    ]
                  },
                  "ticket_type_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "complimentary_admission": {
                    "type": "boolean",
                    "description": "Explicit free admission for kind=comp only; mutually exclusive with ticket_type_id. Restores canonical public RSVPs only for an unconfigured free event; otherwise uses hidden host-only admission. Uses real saved-day ticket IDs for one-day-each events."
                  },
                  "quantity": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 20
                  },
                  "event_day_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "profile_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "language": {
                    "type": "string",
                    "enum": [
                      "en",
                      "ru",
                      "uk",
                      "es"
                    ]
                  },
                  "send_email": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Added.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string"
                    },
                    "payment_link_token": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule on the input (the code names it).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/people.csv": {
      "get": {
        "tags": [
          "Events · People"
        ],
        "summary": "People, as a spreadsheet",
        "operationId": "getEventPeopleCsv",
        "description": "One row per ticket.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "CSV.",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/approve-all": {
      "post": {
        "tags": [
          "Events · People"
        ],
        "summary": "Approve every request",
        "operationId": "approveAllEventOrders",
        "description": "One by one; a card that can't be charged declines only its own request.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "What happened to each.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "status": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/waitlist/{entryId}/offer": {
      "post": {
        "tags": [
          "Events · People"
        ],
        "summary": "Offer a seat to someone in line",
        "operationId": "offerEventWaitlistSeat",
        "description": "Their seats for 24 hours, emailed.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "entryId",
            "in": "path",
            "required": true,
            "description": "The waitlist place's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Offered.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*), `not_waiting`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/message": {
      "post": {
        "tags": [
          "Events · People"
        ],
        "summary": "Message every guest",
        "operationId": "messageEventGuests",
        "description": "An email (and bell) to everyone with a ticket. Audited.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "subject",
                  "message"
                ],
                "properties": {
                  "subject": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "message": {
                    "type": "string",
                    "maxLength": 5000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Queued.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "queued": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule on the input (the code names it).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/refund-requests/{requestId}/decline": {
      "post": {
        "tags": [
          "Events · People"
        ],
        "summary": "Decline a refund request",
        "operationId": "declineEventRefundRequest",
        "description": "The order stays as it is; the buyer hears it, with the note. Audited.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "description": "The refund request's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "note": {
                    "type": "string",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Declined.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/event-orders/{id}/approve": {
      "post": {
        "tags": [
          "Events · People"
        ],
        "summary": "Approve a request",
        "operationId": "approveEventOrder",
        "description": "The order's event's hosts and staff. A paid request is captured (charged) and split into gifts; a free one is confirmed. A card that can't be charged declines it. Audited.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Approved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/event-orders/{id}/decline": {
      "post": {
        "tags": [
          "Events · People"
        ],
        "summary": "Decline a request",
        "operationId": "declineEventOrder",
        "description": "The card's hold is released; nothing is charged. Audited.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Declined.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/event-orders/{id}/refund": {
      "post": {
        "tags": [
          "Events · People"
        ],
        "summary": "Refund an order",
        "operationId": "refundEventOrder",
        "description": "All of it (every ticket, the gift and a covered fee) or some tickets, until 30 days after the event. Split by the same shares across the gifts; a gift already paid out has its transfer reversed by its part; each gift's ledger reverses through the existing refund path. Any open refund request is closed as refunded. Audited, with the hosts' `note`, which the buyer's refund email also carries.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "all": {
                    "type": "boolean"
                  },
                  "ticket_ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "note": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 1000,
                    "description": "Why, in the hosts' words."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Refunded.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "refunded_cents": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`unknown_tickets`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "502": {
            "description": "`refund_failed`: Stripe refused; nothing changed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/check-in/list": {
      "get": {
        "tags": [
          "Events · People"
        ],
        "summary": "The door list",
        "operationId": "getEventCheckInList",
        "description": "The day's guest list with codes, for the door phone to keep and scan offline. Hosts and staff, and volunteers whose role checks people in (from a day before the event until it ends). Never cached.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "day",
            "in": "query",
            "description": "The day (else the one under way, else the first).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventCheckInList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/check-in/search": {
      "get": {
        "tags": [
          "Events · People"
        ],
        "summary": "Find a ticket at the door",
        "operationId": "searchEventCheckIn",
        "description": "By code (exact) or name.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "day",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matches.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "day_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "tickets": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/check-ins": {
      "post": {
        "tags": [
          "Events · People"
        ],
        "summary": "Check in",
        "operationId": "createEventCheckIns",
        "description": "One check-in, or the batch a phone made offline with its own times (`offline: true`). The first check-in of a ticket on a day wins: a repeat answers `already_checked_in` with its time. An offline undo removes only that phone's own check-in (its `client_ref`).",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "items"
                ],
                "properties": {
                  "event_day_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "offline": {
                    "type": "boolean"
                  },
                  "items": {
                    "type": "array",
                    "maxItems": 2000,
                    "items": {
                      "type": "object",
                      "required": [
                        "code"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "undo": {
                          "type": "boolean"
                        },
                        "client_ref": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Each item's result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventCheckInResults"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "422": {
            "description": "`validation_error`, or a rule on the input (the code names it).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{id}/check-ins/{ticketId}": {
      "delete": {
        "tags": [
          "Events · People"
        ],
        "summary": "Undo a check-in",
        "operationId": "deleteEventCheckIn",
        "description": "From the door screen, for the day.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "ticketId",
            "in": "path",
            "required": true,
            "description": "The ticket's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "day",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Undone (or it was not checked in).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ticket_id": {
                      "type": "string"
                    },
                    "day_id": {
                      "type": "string"
                    },
                    "result": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such order, ticket or event for the caller, or Events are switched off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          },
          "409": {
            "description": "`not_allowed` with `details.reason` (events.orders.reasons.* or events.viewer.reasons.*).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventError"
                }
              }
            }
          }
        }
      }
    },
    "/org-admin/{slug}/fundraisers/{id}/page-listing": {
      "patch": {
        "tags": [
          "Organization Admin"
        ],
        "summary": "Set whether this Fundly is listed on its beneficiary nonprofit page",
        "operationId": "setOrgFundlyPageListing",
        "description": "The Fundly must belong to this exact scoped nonprofit, have a nonprofit beneficiary, and not be deleted. Updates only display metadata, with an atomic audit. Hiding the card does not change its public URL, Donate eligibility, impact, gift totals or admin finance views. Requires org.update_settings; blocked during impersonation.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "listed"
                ],
                "properties": {
                  "listed": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved authoritative display flag; private, no-store.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "id",
                    "nonprofit_page_listed"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "nonprofit_page_listed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Sign in first."
          },
          "403": {
            "description": "Missing org.update_settings in the required scope, or an impersonation session."
          },
          "404": {
            "description": "Fundly not found in the required scope or deleted."
          },
          "422": {
            "description": "Body must contain only the named boolean flag."
          },
          "429": {
            "description": "Too many requests."
          }
        }
      }
    }
  }
}