Skip to content

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​

GET
/free-stuff

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​

or
BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Query Parameters

city

A city's slug.

Type
string
near

lat,lng of the browser.

Type
string
Example"38.68,-121.18"
category

Category ids, comma-separated.

Type
string
Example"baby_kids,kitchen"
distance

Within this many miles of the point (1, 2, 5, 10 or 25 in the filters).

Type
number
Example5
pickup

Pickup methods; an item offering any of them matches.

Type
string
Example"porch,public_place"
limit
Type
integer
Default
24
Maximum
48
offset
Type
integer
Default
0

Responses​

Items.

application/json
JSON
{
"items": [
],
"total": 0,
"limit": 0,
"offset": 0,
"city": {
"slug": "string",
"name": "string",
"region": "string"
},
"nearby": true,
"from": "string"
}

Playground​

Server
Variables
Key
Value

Samples​


Give something away​

POST
/free-stuff

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​

BearerAuth

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.

Type
HTTP (bearer)

Request Body​

application/json
JSON
"string"

Responses​

Posted: the giver's view of it, status held or available.

application/json
JSON
"string"

Playground​

Server
Authorization
Body

Samples​


The categories​

GET
/free-stuff/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​

or
BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Query Parameters

lang
Type
string
Valid values
"en""ru""uk""es"

Responses​

Categories.

application/json
JSON
{
"categories": [
{
"id": "string",
"name": "string",
"maxDays": 0
}
]
}

Playground​

Server
Variables
Key
Value

Samples​


An item​

GET
/free-stuff/{id}

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​

or
BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The item.

Type
string
Required
Format
"uuid"

Query Parameters

near

lat,lng of the browser, for the distance band.

Type
string

Responses​

The item.

application/json
JSON
"string"

Playground​

Server
Variables
Key
Value

Samples​


Remove an item​

DELETE
/free-stuff/{id}

The giver removes it; everyone who asked hears it is no longer available. Needs only a sign-in (it takes something away).

Authorizations​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The item.

Type
string
Required
Format
"uuid"

Responses​

Removed.

application/json
JSON
{
"removed": true
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Edit an item​

PATCH
/free-stuff/{id}

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The item.

Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"title": "string",
"description": "string",
"categoryId": "string",
"condition": "string",
"pickup": {
"address": "string",
"point": {
},
"note": "string"
},
"pickupMethods": [
"string"
],
"availableUntil": "string",
"selectionMode": "string",
"photos": [
]
}

Responses​

The giver's view.

application/json
JSON
"string"

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​


Relist an expired item​

POST
/free-stuff/{id}/relist

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The item.

Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"availableUntil": "string"
}

Responses​

The giver's view.

application/json
JSON
"string"

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​


Ask for it​

POST
/free-stuff/{id}/requests

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The item.

Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"note": "string",
"pickupPref": "string"
}

Responses​

Asked.

application/json
JSON
{
"requestId": "string",
"autoChosen": true,
"item": "string"
}

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​


Withdraw my ask​

DELETE
/free-stuff/{id}/requests/mine

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The item.

Type
string
Required
Format
"uuid"

Responses​

Withdrawn.

application/json
JSON
{
"withdrawn": true
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Choose who gets it​

POST
/free-stuff/{id}/requests/{requestId}/choose

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The item.

Type
string
Required
Format
"uuid"
requestId*

The ask.

Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"pickupNote": "string"
}

Responses​

The giver's view.

application/json
JSON
"string"

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​


Block the other person on an ask​

POST
/free-stuff/{id}/requests/{requestId}/block

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The item.

Type
string
Required
Format
"uuid"
requestId*

The ask.

Type
string
Required
Format
"uuid"

Responses​

Blocked.

application/json
JSON
"string"

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Unblock the other person on an ask​

DELETE
/free-stuff/{id}/requests/{requestId}/block

Removes the block the caller made on the other person of this ask. Asks it closed stay closed. Idempotent.

Authorizations​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The item.

Type
string
Required
Format
"uuid"
requestId*

The ask.

Type
string
Required
Format
"uuid"

Responses​

Unblocked.

application/json
JSON
"string"

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Didn't show, choose someone else​

POST
/free-stuff/{id}/requests/{requestId}/no-show

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The item.

Type
string
Required
Format
"uuid"
requestId*

The ask.

Type
string
Required
Format
"uuid"

Responses​

The giver's view.

application/json
JSON
"string"

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Picked up​

POST
/free-stuff/{id}/given

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The item.

Type
string
Required
Format
"uuid"

Responses​

The giver's view.

application/json
JSON
"string"

Playground​

Server
Authorization
Variables
Key
Value

Samples​


The pickup thread​

GET
/free-stuff/{id}/messages

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The item.

Type
string
Required
Format
"uuid"

Query Parameters

requestId
Type
string
Format
"uuid"

Responses​

The thread.

application/json
JSON
{
"thread": {
"requestId": "string",
"status": "string",
"role": "string",
"with": {
"firstName": "string"
},
"canWrite": true,
"blockedByMe": true
},
"messages": [
{
"id": "string",
"mine": true,
"body": "string",
"sentAt": "string",
"readAt": "string"
}
]
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Send a pickup message​

POST
/free-stuff/{id}/messages

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The item.

Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"body": "string",
"requestId": "string"
}

Responses​

Sent: the thread.

application/json
JSON
{
"thread": {
"requestId": "string",
"status": "string",
"role": "string",
"with": {
"firstName": "string"
},
"canWrite": true,
"blockedByMe": true
},
"messages": [
{
"id": "string",
"mine": true,
"body": "string",
"sentAt": "string",
"readAt": "string"
}
]
}

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​


Report an item or a person​

POST
/free-stuff/{id}/reports

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The item.

Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"reason": "string",
"note": "string",
"requestId": "string",
"messageId": "string"
}

Responses​

The same open report, made before.

application/json
JSON
{
"id": "string",
"duplicate": true
}

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​


Save an item​

PUT
/me/free-stuff-saves/{id}

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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The item.

Type
string
Required
Format
"uuid"

Responses​

Saved.

application/json
JSON
{
"saved": true
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Unsave an item​

DELETE
/me/free-stuff-saves/{id}

Removes a save. Idempotent.

Authorizations​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The item.

Type
string
Required
Format
"uuid"

Responses​

Not saved.

application/json
JSON
{
"saved": true
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


My help -> Free stuff​

GET
/me/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​

BearerAuth

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.

Type
HTTP (bearer)

Parameters​

Query Parameters

tab
Type
string
Valid values
"giving""getting""saved"
Default
"giving"
limit
Type
integer
Default
24
Maximum
48
offset
Type
integer
Default
0

Responses​

The tab.

application/json
JSON
{
"tab": "string",
"total": 0,
"items": [
{
"additionalProperties": "string"
}
]
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Powered by VitePress OpenAPI

Built with VitePress