Resources · Workspace
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.
Resources in the menus
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).
Responses
OK
Providers I can see or manage
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".
Authorizations
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.
Responses
OK
Cities and ZIP codes for a service area
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).
Authorizations
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.
Parameters
Query Parameters
80"city"Responses
OK
The provider of a non-profit, business, community or person
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).
Authorizations
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.
Parameters
Query Parameters
"nonprofit""business""community""person"Required for every kind but person.
"uuid"Responses
OK
Make the provider for an entity I manage, or for myself
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.
Authorizations
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.
Request Body
Responses
Made (200 when it existed)
A provider in the workspace
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').
Authorizations
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.
Parameters
Path Parameters
The provider (resource_providers.id).
"uuid"Responses
OK
The provider's resources
Drafts and changes requested first, archived only with status=archived (or archived=true).
Checks: requireProviderAccess('view_resources').
Authorizations
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.
Parameters
Path Parameters
The provider (resource_providers.id).
"uuid"Query Parameters
One status.
Title contains.
"true"Page size (24 by default, 48 at most).
14824Rows to skip.
0Responses
OK
Start a draft
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').
Authorizations
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.
Parameters
Path Parameters
The provider (resource_providers.id).
"uuid"Request Body
Responses
OK
Near-identical help under a linked church or community
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.
Authorizations
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.
Parameters
Path Parameters
"uuid"Request Body
Responses
OK
The topics the editor picks from
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').
Authorizations
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.
Parameters
Path Parameters
The provider (resource_providers.id).
"uuid"Query Parameters
"en""ru""uk""es"Responses
OK
The places help can happen at
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').
Authorizations
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.
Parameters
Path Parameters
The provider (resource_providers.id).
"uuid"Responses
OK
Add a community's or a public program's place
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').
Authorizations
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.
Parameters
Path Parameters
The provider (resource_providers.id).
"uuid"Request Body
Responses
Added
The provider's licenses
With the help that relies on each.
Checks: requireProviderAccess('manage_licenses').
Authorizations
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.
Parameters
Path Parameters
The provider (resource_providers.id).
"uuid"Responses
OK
Add a license
Pending until staff check it against the public record (ST-03).
Checks: requireProviderAccess('manage_licenses').
Authorizations
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.
Parameters
Path Parameters
The provider (resource_providers.id).
"uuid"Request Body
Responses
OK
Change a license
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').
Authorizations
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.
Parameters
Path Parameters
The provider (resource_providers.id).
"uuid"The license.
"uuid"Request Body
Responses
OK
Fundraisers that name the provider's help
Waiting ones first (requested, and needs_confirmation after a transfer: from_previous_provider). waiting is the tab's count. Checks: requireProviderAccess('manage_fundraiser_links').
Authorizations
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.
Parameters
Path Parameters
The provider (resource_providers.id).
"uuid"Query Parameters
"requested""confirmed""declined""removed""needs_confirmation"Page size (24 by default, 48 at most).
14824Rows to skip.
0Responses
OK
Reports about the provider's help
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').
Authorizations
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.
Parameters
Path Parameters
The provider (resource_providers.id).
"uuid"Query Parameters
"open""actioned""dismissed"Page size (24 by default, 48 at most).
14824Rows to skip.
0Responses
OK
Confirm a fundraiser
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').
Authorizations
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.
Parameters
Path Parameters
The fundraiser link.
"uuid"Request Body
Responses
OK
Decline a fundraiser
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').
Authorizations
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.
Parameters
Path Parameters
The fundraiser link.
"uuid"Request Body
Responses
OK
A resource
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').
Authorizations
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.
Parameters
Path Parameters
The resource.
"uuid"Responses
OK
Edit a resource
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').
Authorizations
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.
Parameters
Header Parameters
The version you opened, e.g. "7". Or send version in the body.
Path Parameters
The resource.
"uuid"Request Body
Responses
OK
Who changed what
The audit trail, newest first. Staff changes read "FundlyHub staff", with their reason.
Checks: requireProviderAccess('view_resources').
Authorizations
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.
Parameters
Path Parameters
The resource.
"uuid"Query Parameters
100Responses
OK
Send for review
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').
Authorizations
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.
Parameters
Header Parameters
The version you opened, e.g. "7". Or send version in the body.
Path Parameters
The resource.
"uuid"Responses
OK
Pause
Live help leaves Find help at once. Publishes resource.paused.
Checks: requireProviderAccess('manage_resources').
Authorizations
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.
Parameters
Path Parameters
The resource.
"uuid"Responses
OK
Unpause
Back in Find help, unless staff paused it (paused_by_staff, 403). Publishes resource.published.
Checks: requireProviderAccess('manage_resources').
Authorizations
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.
Parameters
Path Parameters
The resource.
"uuid"Responses
OK
Duplicate
A new draft with everything but the review state ("Copy of ...").
Checks: requireProviderAccess('manage_resources').
Authorizations
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.
Parameters
Path Parameters
The resource.
"uuid"Responses
OK
Remove
Archived: out of every list; staff can restore it for 30 days. Publishes resource.hidden when it was public.
Checks: requireProviderAccess('manage_resources').
Authorizations
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.
Parameters
Path Parameters
The resource.
"uuid"Responses
OK
Confirm your info
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').
Authorizations
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.
Parameters
Path Parameters
The resource.
"uuid"Responses
OK
Capacity
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').
Authorizations
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.
Parameters
Header Parameters
The version you opened, e.g. "7". Or send version in the body.
Path Parameters
The resource.
"uuid"Request Body
Responses
OK
Stock note
"Fresh bread Tuesdays"; null clears it. Live at once, audit-logged with who.
Checks: requireProviderAccess('update_resource_capacity').
Authorizations
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.
Parameters
Header Parameters
The version you opened, e.g. "7". Or send version in the body.
Path Parameters
The resource.
"uuid"Request Body
Responses
OK