# mongrl

> mongrl is a headless marketplace API. You build the storefront (any stack); mongrl runs sellers, listings, search, checkout with Stripe, orders, payouts, shipping and messages behind it. Each marketplace is run by its team in the mongrl console.

Rules for building on mongrl:

- Call the API from your storefront's server, never from the browser: it holds the secret key (`sk_…`) and each user's session token (`X-User-Session`). Browsers can't call the API across origins.
- Generate a typed client from the OpenAPI spec (https://dev.mongrl.com/openapi.json) instead of writing requests by hand. Never guess an endpoint or field.
- Money is an integer in minor units with an ISO 4217 currency (`{"amount": 125000, "currency": "SEK"}` is 1 250,00 kr).
- Errors are RFC 9457 problems (`application/problem+json`): show `detail` to people and map `errors[].location` onto form fields.
- Send an `Idempotency-Key` header on writes you might retry, above all placing an order.
- Orders move by named transitions: offer exactly the ones in `available_transitions`.
- The thing on sale is a "listing". Emailed links land on pages the storefront must build (see "Pages your shop needs").

## Start here

- [What mongrl is](https://dev.mongrl.com/start/introduction.md): The pieces of a mongrl marketplace and who does what, before you write any code.
- [Quickstart](https://dev.mongrl.com/start/quickstart.md): Get a key, generate a typed client from the spec and run your first search from your server.
- [Build with an AI agent](https://dev.mongrl.com/start/agents.md): Point Claude, Cursor or any coding agent at mongrl and get a storefront that runs against real types, not guesses.

## Guides

- [Authentication](https://dev.mongrl.com/guides/authentication.md): Secret and publishable keys, user sessions, and why everything goes through your server.
- [Accounts and sign-in](https://dev.mongrl.com/guides/accounts.md): Sign-up, sign-in with a password or an emailed link, email confirmation, password reset and the profile.
- [Browsing and search](https://dev.mongrl.com/guides/browsing.md): The shop page, search, filters, sorting, prices in the visitor's currency, listing pages, photos, categories, brands and favourites.
- [Selling](https://dev.mongrl.com/guides/selling.md): The sell form, drafts, photos, publishing, valuations, storage and the seller's listings.
- [Checkout and orders](https://dev.mongrl.com/guides/checkout.md): Quote, place the order, take the payment with Stripe, and follow the order until the seller is paid.
- [Shipping and delivery](https://dev.mongrl.com/guides/delivery.md): How a listing reaches the buyer, how delivery is priced from the marketplace's shipping table, and letting buyers book a delivery time.
- [Payouts](https://dev.mongrl.com/guides/payouts.md): Let sellers set up payouts with Stripe's embedded onboarding, and show them where their money is.
- [Messages](https://dev.mongrl.com/guides/messages.md): Questions about a listing, messages about an order, and support from the marketplace's team.
- [Content pages](https://dev.mongrl.com/guides/pages.md): Render the pages the marketplace's team builds in the console (the home page, About, How it works) from blocks filled in with live data.
- [Pages your shop needs](https://dev.mongrl.com/guides/storefront-pages.md): The pages mongrl's emails link to, and the settings that make the links work.

## Reference

- [Conventions](https://dev.mongrl.com/reference/conventions.md): Errors, money, ids and dates, paging, idempotency, rate limits, languages and versioning: how every endpoint behaves.
- [Marketplace](https://dev.mongrl.com/reference/api/marketplace.md): Who the key belongs to and its rules: currencies, languages, what a listing needs, the shipping table, showrooms and warehouses.
- [Listings and search](https://dev.mongrl.com/reference/api/listings.md): Listings on sale, searched and filtered, and their photos.
- [Categories and catalogue terms](https://dev.mongrl.com/reference/api/catalogue.md): The category tree and catalogue terms such as brands and designers.
- [Accounts and sessions](https://dev.mongrl.com/reference/api/accounts.md): Sign-up, sign-in (password or emailed link), email confirmation, password reset and the profile.
- [Favourites](https://dev.mongrl.com/reference/api/favourites.md): Listings a user has saved.
- [Selling](https://dev.mongrl.com/reference/api/selling.md): A seller's own listings: drafts, photos, publishing, valuations and storage.
- [Orders](https://dev.mongrl.com/reference/api/orders.md): Quotes, placing orders, the payment, delivery times and moving orders on.
- [Payouts](https://dev.mongrl.com/reference/api/payouts.md): The seller's payout setup with Stripe.
- [Messages](https://dev.mongrl.com/reference/api/messages.md): Conversations between buyers, sellers and the marketplace.
- [Pages](https://dev.mongrl.com/reference/api/pages.md): Content pages the marketplace edits in the console (the home page, About…), built from blocks and filled in with live data.
- [Newsletter](https://dev.mongrl.com/reference/api/newsletter.md): Newsletter sign-ups from the shop.

## Machine-readable

- [OpenAPI spec (JSON)](https://dev.mongrl.com/openapi.json): every public endpoint and schema; generate your client from it
- [OpenAPI spec (YAML)](https://dev.mongrl.com/openapi.yaml)
- [AGENTS.md](https://dev.mongrl.com/AGENTS.md): rules to keep in a storefront repo

## Optional

- [llms-full.txt](https://dev.mongrl.com/llms-full.txt): every page above in one file
- [llms-small.txt](https://dev.mongrl.com/llms-small.txt): the guides without the generated API reference