# An API for AI agents to order physical work One endpoint takes physical work in plain English: made, printed, packed, potted or shipped, to one address or a parcel to each person. Établi plans it into legs, independent workshops bid on each, and the agent places orders against the contracts. It can start without a key or an account. - **Start:** `POST https://api.etabli.io/v1/quotes/preview`, no key - **MCP:** `https://api.etabli.io/mcp`, no key - **The rule:** Ask the person before you share their name and email - **Docs:** [API docs](https://etabli.io/docs) · [llms.txt](https://etabli.io/llms.txt) · [OpenAPI](https://api.etabli.io/openapi.json) ## Try it, with no key A job an agent might get: a sample kit to each buyer on a list. The agent sends the request as the person put it: The request: > Pack a sample kit for each of the 150 buyers on our list: three of our hot sauces, a printed card and a gift box. Ship one to each buyer within 3 weeks. Up to $28 a kit. Preview the plan, curl: ```bash curl -sX POST https://api.etabli.io/v1/quotes/preview \ -H "Content-Type: application/json" \ -d '{"request":"Pack a sample kit for each of the 150 buyers on our list: three of our hot sauces, a printed card and a gift box. Ship one to each buyer within 3 weeks. Up to $28 a kit."}' ``` Preview the plan, TypeScript: ```ts const response = await fetch("https://api.etabli.io/v1/quotes/preview", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ request: "Pack a sample kit for each of the 150 buyers on our list: three of our hot sauces, a printed card and a gift box. Ship one to each buyer within 3 weeks. Up to $28 a kit.", }), }); const plan = await response.json(); for (const leg of plan.legs) { console.log(leg.key, leg.title, `${leg.questions.length} open questions`); } ``` Preview the plan, Python: ```python import requests plan = requests.post( "https://api.etabli.io/v1/quotes/preview", json={"request": "Pack a sample kit for each of the 150 buyers on our list: three of our hot sauces, a printed card and a gift box. Ship one to each buyer within 3 weeks. Up to $28 a kit."}, timeout=120, ).json() for leg in plan["legs"]: print(leg["key"], leg["title"], len(leg["questions"]), "open questions") ``` No key and no account. Planning takes up to a minute; nothing is ordered or sent to workshops. Ask the person before you send their name and email anywhere. When the person wants workshops to bid, draft it, still with no key: `POST /v1/projects` with the same request and answers returns a line to show them, with a claim link. They check the plan and publish it on etabli.io. [Draft and claim](https://etabli.io/docs#draft-and-claim) has the calls. ## The plan it returns ### One leg, 150 parcels What the live API returned for the request above, on 9 October 2026; its dates count from that day. Each preview is written fresh, so yours will be worded differently. The plan has no price of Établi's own: the only prices on it are the most the request said it would pay. One leg: one workshop does it all. **Hot sauce sample kits for 150 buyers.** Assemble 150 gift-boxed sample kits, each with three of our hot sauces and a printed card, and ship one kit to each buyer on our list by 2026-10-30. #### Leg 1 of 1 · Hot sauce sample kit assembly and shipping (`kitting`) Source the gift boxes and printed cards, pack three of our sauces into each kit and ship one kit to each of 150 buyers. - **Who does it:** US kitting and fulfillment house that assembles gift and sample boxes for food and beverage brands, handles glass bottles and liquids, can source gift boxes and print insert cards, and ships small runs of a few hundred parcels to individual addresses. - **Where the workshop can be:** United States - **Provided:** - Bottled hot sauces, 450 bottles (150 each of three sauces), likely glass: Buyer ships to the workshop's receiving address; workshop inspects on arrival and reports damaged or leaking bottles within 2 business days. - Recipient address list (150 addresses): One kit per address, assumed all within the US. - Card artwork: Print-ready file; size, stock and message to be confirmed. - Printed cards, 150 (workshop supplies): Printed from buyer artwork. - Gift boxes, 150 (workshop supplies): Style and branding to be confirmed; must hold three bottles. - Protective inserts or dividers, bottle seals or bags, and shipping cartons or mailers (workshop supplies): Sized to prevent breakage and leaks of glass bottles in transit. - **Work:** Receive and inspect 450 sauce bottles, reporting any damage or leaks within 2 business days. Print 150 cards from buyer artwork and source 150 gift boxes. Assemble one sample kit and send a photo for approval before the full run. Then pack each kit with one bottle of each of the three sauces (sealed or bagged, separated by dividers or inserts), one card and one gift box, place it in a protective shipping carton or mailer, label it to its recipient and ship with tracking. - **Result:** 150 sample kits, each shipped as its own tracked parcel to a separate recipient address and delivered by 2026-10-30. - **Most you'll pay:** - $28.00 a piece - Includes gift box, printed card, inserts, dividers and bottle sealing or bagging, shipping carton or mailer, kit assembly and packing, receiving inspection and approval sample photo - Excludes hot sauces (buyer-supplied) - **When:** By Fri, Oct 30, 2026 - **Proof:** Photos and tracking number - **Where:** 150 individual recipient addresses in the US, one kit per address, from the buyer's list - **Rules:** - Sauces arrive factory-sealed and are not opened, so no food facility certification is required. - Photo of one packed kit must be approved before packing the full run. - Report damaged or leaking bottles within 2 business days of arrival. - Packaging must keep glass bottles unbroken and leak-free in parcel transit. - Tracking number required for every parcel. We assumed: - All 150 recipients are in the continental US or otherwise domestic US addresses. - Each kit is shipped by ground parcel service; a packed kit weighs about 2–3 lb. - Card is a standard single card (e.g. 5x7 in, heavy stock, full color) unless the buyer specifies otherwise. - Hot sauces are factory-sealed retail bottles. Open questions, with Établi's suggested answers: 1. **Should the $28 per kit include postage to each buyer?** Suggested: Yes, $28 is all-in including postage to each US address. Why we ask: Ground postage for a 2–3 lb box of glass bottles is often $10–16, which decides whether the rest of the kit fits the budget. 2. **What gift box do you want, and should it be printed or branded?** Suggested: A plain kraft or black stock gift box with a three-bottle insert, branded only with a logo sticker. Why we ask: A plain stock box costs far less and ships faster than a custom-printed one, which may not be ready in three weeks. 3. **What size, stock and print sides should the card be?** Suggested: 5x7 in, 16 pt matte stock, printed full color on both sides. Why we ask: Card format affects print cost and whether the artwork needs adjusting. 4. **When will your 450 bottles arrive at the workshop?** Suggested: Bottles will arrive by 2026-10-16. Why we ask: Packing, approval and ground transit all must fit before 2026-10-30, so late arrival may make the date infeasible. 5. **Who pays for bottles that arrive damaged versus bottles broken during packing or shipping?** Suggested: Buyer covers bottles damaged on arrival if reported within 2 business days; the workshop covers bottles broken during packing or outbound shipping and reships those kits. Why we ask: Breakage of buyer-supplied glass is the most common dispute, and the split changes how workshops price risk. The response, abridged (each leg's `spec` has all eight fields, and `sourcing` says who to look for): ```json { "title": "Hot sauce sample kits for 150 buyers", "summary": "Assemble 150 gift-boxed sample kits, each with three of our hot sauces and a printed card, and ship one kit to each buyer on our list by 2026-10-30.", "legs": [ { "key": "kitting", "title": "Hot sauce sample kit assembly and shipping", "role": "Source the gift boxes and printed cards, pack three of our sauces into each kit and ship one kit to each of 150 buyers.", "spec": { "price": { "ceilingCents": 2800, "per": "unit", "includes": [ "Gift box", "Printed card", "Inserts, dividers and bottle sealing or bagging", "Shipping carton or mailer", "Kit assembly and packing", "Receiving inspection", "Approval sample photo" ], "excludes": [ "Hot sauces (buyer-supplied)" ] }, "deadline": { "kind": "fixed_date", "businessDays": null, "date": "2026-10-30" }, "…": "work, output, proof, where, rules" }, "questions": [ { "field": "price.includes", "text": "Should the $28 per kit include postage to each buyer?", "suggestedAnswer": "Yes, $28 is all-in including postage to each US address." } ], "inputsFrom": [], "sourcing": { "countries": [ "US" ], "…": "lookFor, searchTerms" } } ], "engine": "claude:claude-opus-5-5" } ``` ## The agent's loop 1. **Preview** the request, with no key. Read the legs and their open questions. 2. **Ask the person** the questions (this plan has 5 open questions); each comes with a suggested answer they can take. Preview again with their answers. 3. **Draft it** with no key, and show the person the claim line it returns, word for word. Keep the project key: nothing goes to workshops until the person claims and publishes the project on etabli.io. 4. **Follow it** with the project key: `next` says what to do now, and `Retry-After` when to look again. Bids take days; the person gets a status link, and Établi contacts them to confirm the offers they choose and arrange payment. (A company with a buyer key can run this part itself: publish, compare offers and award a contract per leg.) 5. **Place orders** against each contract. Here, that's one per buyer on the list, each with that buyer's address and an idempotency key, so a retry never sends a second kit. One parcel to one person, curl: ```bash # One kit to one buyer on the list. One call per buyer. curl -sX POST https://api.etabli.io/v1/contracts/$CONTRACT_ID/orders \ -H "Authorization: Bearer $ETABLI_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: kit-buyer-0042" \ -d '{ "quantity": 1, "reference": "buyer-0042", "address": { "name": "Alex Kim", "line1": "100 Main St", "city": "Springfield", "region": "IL", "postalCode": "62701" } }' ``` One parcel to one person, TypeScript: ```ts // One kit to one buyer on the list. One call per buyer. const order = await fetch(`https://api.etabli.io/v1/contracts/${contractId}/orders`, { method: "POST", headers: { Authorization: `Bearer ${process.env.ETABLI_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "kit-buyer-0042", // a retry never orders twice }, body: JSON.stringify({ "quantity": 1, "reference": "buyer-0042", "address": { "name": "Alex Kim", "line1": "100 Main St", "city": "Springfield", "region": "IL", "postalCode": "62701" } }), }).then((response) => response.json()); ``` ## Four ways in | Way | Needs | Use it when | | --- | --- | --- | | [REST API](https://etabli.io/docs) | Nothing to preview or draft; a buyer key to award and order yourself | The agent writes code or runs commands. | | [MCP server](https://etabli.io/mcp) | Nothing at `/mcp` (previews and drafts); a buyer key at `/mcp/full` | The agent works through tools: Claude, ChatGPT, Cursor, VS Code, Codex. | | Skill | `npx skills add https://etabli.io` | The agent should know when Établi fits and how to order with it. | | [A link for the person](https://etabli.io/quote) | Nothing | The person should finish it: `https://etabli.io/quote?q=` opens the plan with the request filled in. | ## Rules for agents - Show the person the claim line word for word, and never claim a project for them: only they can publish it. - Ask the person before sending their name and email anywhere (a draft's `contact`, `POST /v1/quote-requests`, or the `request_firm_prices` tool). - Confirm with the person before awarding a contract or placing an order: both commit real money. - Don't quote a price before the bids are in. Établi has no price list, and a preview has no price of its own. - Send an `Idempotency-Key` with every order. - Money is integer US cents. Errors are `{"error": {"code", "message", "details"}}`; a 429 says when to retry in `Retry-After`; a 422 `policy_violation` is work Établi won't take. - Allow up to a minute for a preview: Établi writes the plan when you ask. ## Use it from your agent Add Établi's MCP server (`https://api.etabli.io/mcp`, no key) and the same steps become tools: `preview_quote`, `create_project` (a draft the person claims on etabli.io) and `get_project`; with a buyer key, awarding and ordering. Or install the skill, which tells an agent when Établi fits. - **Claude Code:** `claude mcp add --transport http etabli https://api.etabli.io/mcp` - **Codex:** `codex mcp add etabli --url https://api.etabli.io/mcp`. Or add it to `~/.codex/config.toml`, which the Codex CLI, the IDE extension and the ChatGPT desktop app share: ```toml [mcp_servers.etabli] url = "https://api.etabli.io/mcp" ``` - **Cursor:** [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=etabli&config=eyJ1cmwiOiJodHRwczovL2FwaS5ldGFibGkuaW8vbWNwIn0=). Or open [cursor.com/install-mcp](https://cursor.com/install-mcp?name=etabli&config=eyJ1cmwiOiJodHRwczovL2FwaS5ldGFibGkuaW8vbWNwIn0%3D) in a browser. - **VS Code (Copilot):** [Add to VS Code](https://vscode.dev/redirect/mcp/install?name=etabli&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.etabli.io%2Fmcp%22%7D). Or run `code --add-mcp '{"name":"etabli","type":"http","url":"https://api.etabli.io/mcp"}'`. - **Gemini CLI:** `gemini mcp add --transport http etabli https://api.etabli.io/mcp` - **Skill (70+ agents):** `npx skills add https://etabli.io`. Installs Établi's skill, `order-physical-work`, into the agents on your machine: when to use Établi and how to order with it. Every other client, and the tools: [the MCP server](https://etabli.io/mcp). The API: [docs](https://etabli.io/docs). ## Use something else when… - **The thing is already for sale.** Buy it: through the store's own API, or agentic checkout (OpenAI and Stripe's ACP, Google's UCP). - **It's a gift and you don't have the addresses.** A gifting API such as Goody sends a gift that the recipient accepts and addresses themselves. - **It's your design on a stock product, made one at a time.** Print-on-demand (Printful, Printify) has fixed products and prices and ships each order as it comes. - **It's a letter or a postcard.** Print-and-mail APIs such as Lob are built for that. Choosing between these? [Three ways an AI agent can buy physical goods](https://etabli.io/use/how-ai-agents-buy-physical-goods). ## Good to know - Orders go to US addresses and are priced in US dollars. Workshops can be in any country a leg allows. - Prices come from workshops' bids, with Établi's fee included in each offer. Établi has no price list; the most you say you'd pay caps the bids. [Pricing](https://etabli.io/pricing). - When no workshop on Établi fits a leg yet, Établi finds suitable ones and asks them to bid, which can take a few days. A person at Établi approves every message first. - An agent needs no account: it previews the plan and drafts the project, and the person claims and publishes it on etabli.io. Buyer keys are for companies that run the whole loop through the API themselves: [request API access](https://etabli.io/#access). - Online payment isn't live yet: while Établi is in early access, it arranges payment with each buyer and workshop directly. ## More guides - [Dropship houseplants in your own pots](https://etabli.io/use/dropship-houseplants-api) - [Printed packaging, split across warehouses](https://etabli.io/use/custom-packaging-api) - [Get products manufactured](https://etabli.io/use/manufacturing-api) - [Three ways agents buy physical goods](https://etabli.io/use/how-ai-agents-buy-physical-goods) The API, auth and every endpoint: [docs](https://etabli.io/docs). For agents, everything in one file: [llms-full.txt](https://etabli.io/llms-full.txt). --- This is the markdown version of https://etabli.io/use/api-for-ai-agents. Every page on etabli.io has one at the same path plus .md (https://etabli.io/index.md for the home page). For agents: an overview at https://etabli.io/llms.txt, and everything in one file at https://etabli.io/llms-full.txt.