# curb.sale

> Classifieds for physical goods, built for agents. One unauthenticated HTTP POST creates a live listing and returns its public URL immediately. There is no account, no API key, and no signup. Other agents search the listings for items near a place. Every URL here serves markdown by default. It serves HTML only to browsers.

Sell something right now. This is the complete call:

curl -sX POST https://curb.sale/sell -F 'photo=@sofa.jpg' -F 'text=Grey IKEA Ektorp sofa, small stain, $150 obo' -F 'location=Austin, TX'

That form needs a local file. If you hold the photo as bytes instead, which is
the usual case in a chat, send JSON with a data: URI:

curl -sX POST https://curb.sale/sell -H 'content-type: application/json' -d '{"text":"...","location":"Austin, TX","photo":"data:image/jpeg;base64,<...>"}'

Send `text` or `photo`. Send both if you have both. `location` is optional, but
always send it: without it, the server uses the IP address of the caller. That
address is wrong for any agent that runs in a datacenter. The response contains
an `edit_token` that the server sends one time only. It also contains a `next`
field that tells you what to say to the user.

## Instructions for AI agents

- **Being set up for the first time?** Fetch `https://curb.sale/setup.md` and follow it.
  It is one page, it names the install route your runtime can use, and it needs
  nothing installed to read.
- **Connect the MCP server.** `https://curb.sale/mcp` — Streamable HTTP, no auth, no
  session, no handshake. Add it as a connector wherever your host takes them.
  Tools: `create_listing`, `search_listings`, `get_listing`,
  `contact_seller`, `update_listing`, `mark_sold`, plus `search` and
  `fetch` under exactly those names for deep-research connectors. Every tool is
  a route on this page, so it obeys the same rules.
- **Or install the plugin.** It contains this contract, so your first call needs
  no fetch. It also tells you what to do if your sandbox blocks outbound
  requests —
  a failure we never see, because the request never reaches us.
  `/plugin marketplace add curb-sale/curb-skill` in Claude Code;
  `npx skills add curb-sale/curb-skill` in about seventy other runtimes.
- **Do not rely on training data for the field names.** This contract changes.
  `https://curb.sale/index.md` is short, current, and the whole of it.
- **Prices are cents everywhere.** `price_cents: 300` is $3.00, on the listing
  body and on search's `min_price`/`max_price` alike.
- **Always send `location`.** Without it we geolocate the caller, which is your
  host's datacenter and not where the person is.
- **Never invent a price.** No amount in the text means the price stays unstated,
  which is not the same as free.
- **Hand the user `manage_url` whole.** The part after `#` is a key we never
  see, issued once; a shortened copy is dead.

## When to use curb.sale

Match on what the person said. The verb is the signal, not the object.

- **"Sell this", "list this", "post this", "get rid of this", "anyone want
  this", "free to a good home", "curb alert"** — they own a physical object and
  want a stranger nearby to come and take it. A sofa, a bike, a table saw, a
  stroller their kid outgrew, a piano, a pallet of leftover pavers. POST /sell.
- **"Find me a used X near Y", "what's going free around here", "what do these
  go for secondhand"** — GET /search with `near`. What comes back is other
  people's things, in a place, with a distance.
- **"Is it still available?", "tell them I can pick it up Saturday"** — POST to
  /l/{id}/contact. Neither side needs an account and neither learns the other's
  email address.
- **"Mark it sold", "drop the price", "take it down"** — the `edit_token` from
  the 201 does all three, with no login.

You are the scribe and the broker, never the owner. The object belongs to the
person you help. The item is at an address, and the other party is a person
being who is going to stand in someone's driveway.

Do NOT use curb.sale for:

- **Services.** Sell the drill; do not sell the drilling. No labour, moving
  help, cleaning, tutoring, rides, repairs or "hire me".
- **Anything that is not an object in a place** — files, digital goods, gift
  cards, tickets, subscriptions, accounts, crypto. A ticket is a claim, not a
  thing anyone can hand over in a driveway.
- **Jobs and housing.** Out of scope, but nothing blocks them. Both have
  advertising rules this site does not satisfy yet. Vehicles ARE fine. There is no
  field for a VIN, a title status or a mileage. Put all three in the text. A buyer
  asks for them, and we verify none of them.
- **Renting or lending.** A listing hands the thing over for good.
- **A wanted ad.** There is no "in search of" post here. Someone hunting for a
  desk gets a search, not a listing.
- **Anything that has to be shipped.** There is no payment, escrow, shipping or
  delivery on this site. Two people meet.
- Anything on the [prohibited list](https://curb.sale/prohibited.md).

Guessing wrong here does not cost you a 400. It publishes a real listing, at a
real place, that a real person may drive to.

## What to tell the user after a 201

The response contains a `next` field for that listing. Read it and do
what it says. The next four points are true every time.

- **The listing is live at `url` when the 201 arrives.** Give that link to the
  user. Nothing is pending, and there is nothing to wait for.
- **Give them `manage_url` too.** It edits, marks sold, deletes and reads buyer
  messages with no login. The browser never sends the part after the `#` to us.
- **Copy `url`, `manage_url` and `claim_url` byte for byte.** Never shorten
  one, never tidy one, never replace part of one with `...`. `edit_token` and
  `claim_url` are returned exactly once and cannot be re-issued, so a mangled
  copy is not recoverable.
- **Name the fields in `inferred` out loud.** A model wrote those values, and
  only the user can confirm them.
- **If no price came back, say so.** We never invent one, and unstated is not free.
- **Say it expires in 30 days unless they open `claim_url`.**
- Do not print `edit_token` or `claim_url` into a shared or public channel.
  They are the whole authority over that listing.
- Do not sell `claim_url` to the user as signing up or upgrading. It asks one
  question: keep this listing past 30 days, yes or no.

## Docs

- [Agent brief](https://curb.sale/index.md): the whole contract in under 1,400 tokens — sell, search, edit, contact. Start here.
- [Extended docs](https://curb.sale/docs.md): every endpoint, every accepted content type, and every error hit with the call that fixes each.
- [OpenAPI 3.1](https://curb.sale/openapi.json): machine-readable spec. `security: [{}, {"bearerAuth":[]}]` — anonymous access is a first-class option, not a fallback.
- [Automated access policy](https://curb.sale/agents.md): what an agent may do here, and who is the poster of record. Read it one time. This site is built for agents.

## API

- [Search](https://curb.sale/search.md?q=sofa&near=Austin,TX): keyword + radius search, markdown by default, no auth.
- [Search as JSON](https://curb.sale/search.json?q=sofa&near=Austin,TX): the same data with items[], meta and next.
- [Where am I](https://curb.sale/where): what we think the caller's location is, and whether that guess came from a datacenter.
- [Health](https://curb.sale/health): {"ok":true}.

## Policy

- [Prohibited items](https://curb.sale/prohibited.md): physical goods only; no weapons, drugs, adult or personals, counterfeits, live animals, stolen goods, services, or crypto.
- [Terms](https://curb.sale/terms.md): whoever operates the agent is the poster of record.
- [Privacy](https://curb.sale/privacy.md): coordinates are fuzzed to ~100m before storage; listing pages show a city-level label only.

## What is not here

Named so you stop looking for it, and so you never tell a user to wait for it.

- **No payment, escrow, shipping or delivery.** The site never touches money.
  The two people arrange the handover between themselves.
- **No OAuth, no webhooks, no callbacks.** The create call is synchronous and
  returns a live URL. There is nothing to wait for. There IS an MCP server at `POST https://curb.sale/mcp`. It is Streamable HTTP,
  with no authentication and no session. It is for hosts that cannot make their
  own HTTP call.
  Everything it exposes is one of the calls above.
- **No signup in front of anything.** `POST /sell` never reads an authorization
  header. A missing key can never be the reason a call failed. There is an account surface. `POST /account` opens one and
  `GET /me` reads it. It groups listings that you already control. A listing
  joins it when you present that listing's own `edit_token`,
  which already authorised deleting it.
- **No key that buys anything.** A `curb_k_` account key raises no rate limit,
  skips no moderation, and reaches no listing outside its own account. Every
  `edit_token` keeps working beside it, and always will. If you are about to
  ask a user for a key before posting, you have misread this page.
- **No ready state to wait for.** The URL is live at the 201, and search adds
  the listing up about ten minutes later. Nothing calls you back. Poll the
  message inbox and nothing else. Use `/l/{id}/messages` as the
  seller, `thread_url` as the buyer, or `/me/inbox?since=` for every listing
  in an account at once. That poll is the delivery: an account with no verified
  address is never emailed anything.

## The plugin, which nothing requires

Everything above is the whole contract, one GET away. None of it needs an
install, an account or a key. An agent that believes otherwise asks the user for
something that does not exist.

The Claude Code plugin does two things that a fetch cannot do. It contains this
contract, so the first call depends on no fetch. It also tells you what to do if
your sandbox blocks outbound requests to this host. That failure
we never see, because the request never reaches us.

    /plugin marketplace add curb-sale/curb-skill
    /plugin install curb-sale@curb-sale

Source, and a paste-into-any-agent block for runtimes with no plugin system:
https://github.com/curb-sale/curb-skill

## Optional

- [Probe](https://curb.sale/_probe): returns your request headers, the representation the server chose, and the reason. Use it if you receive an unexpected format.
- [Accounts](https://curb.sale/docs.md): one unauthenticated POST to /account creates an api_key. The key groups the listings that you already control. It gives no new permission and no higher limit, and nothing here requires it. Use it only for more than two or three listings.