Free stuff
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" } }.
Browse free stuff near a place
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.
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
A city's slug.
lat,lng of the browser.
"38.68,-121.18"Category ids, comma-separated.
"baby_kids,kitchen"Within this many miles of the point (1, 2, 5, 10 or 25 in the filters).
5Pickup methods; an item offering any of them matches.
"porch,public_place"24480Responses
Items.
Give something away
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.
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
Posted: the giver's view of it, status held or available.
The categories
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.
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
"en""ru""uk""es"Responses
Categories.
An item
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.
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 item.
"uuid"Query Parameters
lat,lng of the browser, for the distance band.
Responses
The item.
Remove an item
The giver removes it; everyone who asked hears it is no longer available. Needs only a sign-in (it takes something away).
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 item.
"uuid"Responses
Removed.
Edit an item
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.
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 item.
"uuid"Request Body
Responses
The giver's view.
Relist an expired item
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.
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 item.
"uuid"Request Body
Responses
The giver's view.
Ask for it
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.
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 item.
"uuid"Request Body
Responses
Asked.
Withdraw my ask
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.
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 item.
"uuid"Responses
Withdrawn.
Choose who gets it
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.
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 item.
"uuid"The ask.
"uuid"Request Body
Responses
The giver's view.
Block the other person on an ask
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.
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 item.
"uuid"The ask.
"uuid"Responses
Blocked.
Unblock the other person on an ask
Removes the block the caller made on the other person of this ask. Asks it closed stay closed. Idempotent.
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 item.
"uuid"The ask.
"uuid"Responses
Unblocked.
Didn't show, choose someone else
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.
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 item.
"uuid"The ask.
"uuid"Responses
The giver's view.
Picked up
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.
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 item.
"uuid"Responses
The giver's view.
The pickup thread
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.
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 item.
"uuid"Query Parameters
"uuid"Responses
The thread.
Send a pickup message
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.
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 item.
"uuid"Request Body
Responses
Sent: the thread.
Report an item or a person
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.
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 item.
"uuid"Request Body
Responses
The same open report, made before.
Save an item
Saves an item that is up, for My help -> Free stuff (it drops off when the item closes). Idempotent. Needs only a sign-in.
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 item.
"uuid"Responses
Saved.
Unsave an item
Removes a save. Idempotent.
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 item.
"uuid"Responses
Not saved.
My help -> Free stuff
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.
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
"giving""getting""saved""giving"24480Responses
The tab.