One funnel for every fabrication process: quote → refine → checkout → track.
Live processes: fdm_print and resin_print (3D printing),
cnc, sheetmetal, laser_cut,
decal (custom stickers), print (paper — cards, flyers,
posters), and apparel, US shipping. AFN speaks UFP — the Universal Fabrication Protocol.
The canonical schema reference is the protocol spec;
the machine-readable version is openapi.json.
curl -X POST https://agenticfabricationnetwork.ai/v1/agents -H 'content-type: application/json' -d '{"name":"my-agent"}'
# → { "api_key": "ufp_sk_..." } (shown once — store it)
# Send on every call: Authorization: Bearer ufp_sk_...
| Path | Auth | ||
|---|---|---|---|
| POST | /v1/agents | — | Self-serve API key issuance |
| GET | /v1/capabilities | — | Processes, materials, cuts, size/qty ranges — live JSON |
| POST | /v1/files | key | Upload artwork/STL/STEP/DXF (multipart file) or register a URL (JSON {url}) |
| POST | /v1/quotes | key | Fabrication request → ranked offers with prices, ETAs, previews. Streams: status "quoting" answers fast with the quickest vendors; the rest land on re-read |
| GET | /v1/quotes/:id | key | Re-read a quote — LIVE state: offers stream in while status is quoting; previews resolve asynchronously |
| POST | /v1/quotes/:id/refine | key | Narrow with added constraints (incl. a processes lane filter — null clears it), or change the spec ({spec:{material,color,finish,quantities}} — lanes requote warm; a finish rides finish-capable lanes, printer lanes keep the color); empty body = re-read |
| POST | /v1/quotes/:id/preview | key | The SOFT quote: refine's exact body, planned but never launched — how many distinct fabricators (and which lanes) the network would ask for the refined part, plus the exclusion notes. Creates nothing (no child quote, no vendor call, no supersede, no demand row): fire one per edit. 200, never 201 |
| GET | /v1/quotes/:id/price-curve | key | Price by quantity: every shop on the board priced per unit at ?quantities=1,2,5,10,25,50,100,250,500,1000 (the default; up to 16 whole numbers in 1..10000) from the shop's own pricing with the network's markup, plus lead, transit and arrival. Model prices only — no shop is contacted, nothing is written; the board's quoted price stays the ceiling at the chosen quantity (live). Cached 30 s |
| POST | /v1/quotes/:id/offers/:offerId/check | key | The check on demand: ask the offer's own shop to confirm exactly this option (material, gauge, finish, quantity, destination). Body {wait_s?} (default 45, max 60). 200 with the verdict landed on the same offer (manufacturability_check passed / repriced / failed — a failed offer cannot be ordered and is no longer listed in the quote's offers; the response says so in message); 202 + pending: true while the shop is still answering — poll the quote. For offers whose check reads unchecked (no shop asked for that option yet) or checking |
| POST | /v1/checkout | key | Create order + hosted payment link for the user. Asks the offer's one shop itself when it still needs confirming (check, default true; waits wait_s, default 120); 409 price_went_up once when the confirmed price is higher than max_total_cents |
| POST | /v1/payment-method/setup | key | Get the link a person opens to save a card on this key and set its limits (see Paying without a person) |
| GET | /v1/payment-method | key | The card saved on this key (brand, last four), its two limits, and what is left of the current 24 hours. PATCH lowers a limit; DELETE turns the card off |
| GET | /v1/orders | key | Your agent's recent orders (newest first) |
| GET | /v1/orders/:id | key | Status, ETA, tracking, event log, and status_url |
| GET | /status/:token | — | The status link (status_url): an order's progress as a page, for anyone holding the link. /status/:token/json is the same as JSON. Progress only: no order id, no price, no address (see Order updates) |
| POST | /v1/orders/:id/review | key | Verified-purchase vendor review: {stars, comment?, facets?} — one per order, resubmit to update |
| GET | /v1/parts/:id | key | Inspect a part number; reorder via spec.part_number on /v1/quotes |
| GET | /quotes/:id/design | — | Download just the bare design file |
| GET | /v1/ufp/spec.schema.json | — | JSON Schema of the .ufp part spec (ufp.json spec: material, color, finish, quantities, thickness_in, tapping, inserts, bends) — the exact record shapes refine accepts. Manifest schema: /v1/ufp/ufp.schema.json |
vendor_rating — {stars, review_count, facets}
built from verified-purchase reviews only. The count is always the honest number of reviews on file.POST /v1/attestations, vendor-key authed), and honest, cited
materials intelligence — specs, stronger/hotter/outdoor ladders, finishes,
caveats first (/docs/materials.md).POST /v1/quotes
{
"process": "decal", // or "fdm_print" — or omit: AFN detects
// the file kind and routes it (see below)
"spec": {
"file_id": "f_...", // from POST /v1/files
"size_in": { "width": 3, "height": 3 }, // decal, optional (default 3x3)
"cut": "triangle", // FREE-FORM — pass the user's words. Known cuts
// (contour|square|oval|kiss_cut) match exactly;
// anything else returns closest-match offers with
// a substitutions note, and the ask is logged
"material": "vinyl", // free-form too; omit = constraint-compliant options
"quantities": [1] // ask for what the user wants, even 1 — vendors
// with a higher minimum quote AT their minimum
// and set requested_quantity on the offer
},
"constraints": {
"ship_to_zip": "78701", // omit if unknown — prices stay all-in, shipped to
// the network's assumed US destination, declared
// on routing.ship_to { zip, assumed: true }
"deadline": "2026-07-13", // drop offers that can't arrive in time
"processes": ["sheetmetal"], // lane filter — quote ONLY these processes;
// on refine: inherited, and null clears it
// ("show everything again")
"outdoor_rated": true,
"submersible": true, // "must survive pool water"
"max_budget_cents": 3500, // all-in cap ("under $35")
"lead_days": 10, // "within 10 days" of the day the quote is read
"materials": ["delrin", "pla"], // acceptable materials — family or specific words;
// applies when spec.material is absent
"vendors": ["slant3d"], // only these shops (wire slugs)
"vendors_exclude": ["a3d"] // never these shops; applied after vendors
},
"selection": { // optional — the picked checkout (see below)
"vendor": "slant3d",
"process": "fdm_print",
"spec": { "material": "pla", "color": "black", "finish": null, "thickness_in": null },
"shipping_speed": "standard" // the shipping option's own word, not an id
}
}
For fdm_print: spec.file_id is an STL or STEP (converted
server-side); optional material (pla|petg|asa),
color, quantities.
For print: spec.file_id is print-ready artwork (PDF preferred,
PNG/JPEG accepted); optional product
(business_cards|flyers|posters — omit to quote every kind the artwork fits),
free-form size ("letter", "24x36"), free-form paper
("matte", "glossy", "recycled"), sides (single|double),
quantities. Deadline, budget, and durability constraints filter print
offers like any other process; product kinds, sizes, and stocks are discoverable
via GET /v1/capabilities.
For sheetmetal: spec.file_id is a DXF flat pattern or STEP model;
free-form material (canonical mild_steel|aluminum_5052|stainless_304 —
"steel", "5052", "stainless" resolve), optional thickness_in (quoted at the
nearest stocked gauge), optional units (mm|in, DXF only, default mm),
optional bend_count (> 0 prices CNC bending), free-form finish
(as_cut default, deburred, powder_coat),
quantities. Filterable criteria: outdoor_rated drops bare mild
steel (it rusts) while aluminum/stainless pass — and upgrades unpinned mild steel to a
protective powder_coat finish; submersible matches nothing (no
vendor claim); deadline and budget narrow as usual. Material attributes, per-material
thicknesses_in, and finishes are discoverable via
GET /v1/capabilities.
Omit process and AFN detects the file kind — artwork (png/jpg/svg/pdf),
stl, step, dxf — and quotes every process that can
make it, fanning out over a small default material set per process. The response adds a
routing object: {detected_file_kind, candidates, also_possible,
viewer_mesh_url}.
also_possible lists processes AFN can't quote yet (e.g. pcb)
with a reason; each is logged as a demand signal that drives vendor sourcing.
viewer_mesh_url (mesh/BREP uploads only) serves a face-classified binary
viewer mesh (AFVM v1) that derives lazily — poll it until 200.
Passing process explicitly behaves exactly as before.
price_basis: vendor_api (live vendor quote),
cached_matrix (AFN's continuously refreshed price table), or estimate.
An estimate row carrying manufacturability_check is the shop's own price
under its manufacturability check — never call it an estimate (checkout answers
409 offer_not_ready with retry_after_s while the status is
checking); only an estimate row without that field is a caveated
estimate. Checkout is the network's own rule, the same for every client: an offer can be
ordered only when the shop's own system has accepted the part at that price — the check has
passed, price_basis is vendor_api, and price_refresh is
absent or confirmed. While price_refresh is pending
checkout answers 409 offer_not_ready; a failed check or a price the shop never
confirmed answers 400 with code: offer_check_failed. A shop that
cannot confirm the part — it declines it, errors, or does not answer within two minutes of
being asked — is a failed offer: it leaves offers on the next read, and its id is
refused at checkout the same way. An offer that reads unchecked with
reason: network_restarted was being asked when the network restarted: the price
stands, the check on demand asks again, and a client that was showing it as being checked tells
its user "A new version of AFN has been released, please refresh the page". A shop's
confirmation of an offer is good for 15 minutes: while it stands the offer carries
confirmed_until; after it the offer is not failed and not removed — it keeps its
place and the price the shop last confirmed, reads unchecked with
reason: confirmation_lapsed, checkout answers 409 offer_not_ready,
and the check on demand asks that one shop again. Such an offer also says
stale: true and, like every offer a shop has answered, when
(answered_at). Every shipping option carries eta_days (calendar days
from this read); on a stale offer it also carries eta_approximate: true: the
arrival is our own count from today, so write "~N days" and do not state
eta_date as a date until the shop confirms again.
A shop's answer is shown for 24 hours (expires_at), to everyone
with the same request: the same design bytes (never the file's name) with the same
everything asked. Inside them a new quote of that request holds a copy of those answers and
no shop is asked again; if someone is asking about it right now, the new quote shows our
instant prices with answers_pending: { retry_after_s }. A returning visitor's
board calls POST /v1/quotes/:id/reopen: the same quote inside the 24 hours, a
new one past them (reopened: same, copied,
asked, waiting or press_needed). A plain read never
starts a shop ask. A quote asked for with instant_only: true is
instant prices only: no shop is asked about the part, the quote is complete at once
(routing.instant_only), its offers read unchecked, the check on
demand answers without asking the shop, and checkout answers 400 with
code: instant_only_quote — to order, quote the same part again without the flag.
A quote asked for with lazy: true is our instant prices first: no shop is asked
to make it or by any refine of it (routing.lazy), its offers read
unchecked, the check on demand asks the one shop of the offer it is run on, and
that offer can be ordered once the check passes. A shop we hold no instant price for has no
offer on such a quote.
Every offer carries a preview —
the vendor's own product render of the artwork with those exact options; poll the quote until
preview.status is ready.POST /v1/checkout
{
"offer_id": "of_...",
"shipping_option_id": "express", // from the offer's shipping_options
"ship_to": { "name": "...", "street1": "...", "city": "...", "state": "TX", "zip": "78701" },
"contact": { "email": "buyer@example.com" },
"notify_emails": ["shop-floor@example.com"], // optional — one more address for the updates
"coupon_code": "AFN-XXXXXX" // optional — only if the user gave you one
}
# → { "order_id": "ord_...", "checkout_url": "https://checkout.stripe.com/...", "total_cents": 4230,
# "status_url": "https://agenticfabricationnetwork.ai/status/..." }
The checkout confirms what needs confirming itself, and the pay rule. An offer
whose shop has not confirmed it, or confirmed it more than 15 minutes ago, has that one shop
asked by the checkout (check, default true; an ask already running
for it is joined, never doubled), and the call waits up to wait_s seconds
(default 120). When the wait runs out first the answer is 409 offer_not_ready
with retry_after_s: send the same call again. Send
max_total_cents — the most the buyer agreed to pay (the offer's
subtotal_cents plus the speed's cost_cents, before any coupon). The
same or a lower confirmed price goes straight to the payment link
(confirmed_total_cents says what was compared); a higher one is refused
once with 409
{ error: "price_went_up", old_total_cents, new_total_cents, confirmed_until },
nothing is created and nothing is charged. Tell the buyer, then send the call again (with the
new max_total_cents when you sent one): the new price stands for 15 minutes and
no shop is asked again. Left out, the price the buyer was last told is what the confirmed
price is compared with.
Hand checkout_url to your user — never collect card details yourself. AFN is the
merchant of record and places the vendor order automatically after payment.
Lifecycle: pending_payment → paid → placing → placed → in_production → shipped → delivered.
Mail. A paid order sends mail as it moves: received, accepted by the maker,
work begun, shipped, delivered, or refunded when the maker cannot take it. Nothing is mailed
for an order that was never paid. The buyer's own address always gets it.
notify_emails on POST /v1/checkout and
POST /v1/carts/:id/checkout names one more: two addresses in all, the
buyer always one of them. More than that, or anything that is not a plain address,
is refused with 400 code notify_emails_invalid before anything is
made. The named address gets the same updates without the price, the order id, or any link
that can rate the shop, answer the shop or manage the part. A shop's question and the review
email go to the buyer only. A named address is never given to a shop.
The review email goes to the buyer one day after the shop's tracking says delivered. Where a shop gives no tracking it goes three days after the quoted arrival date. It is sent once.
The status link. Every checkout and order answer carries
status_url, and every order email carries the same link. Anyone holding it can
open it — no key, no sign-in — so it is safe to pass on. It shows the order's progress and
nothing else: the status in plain words, what is being made, the shop, the arrival date, the
tracking number and the dated steps. It never shows the order id, a price, an email, a name,
an address or a message, and it cannot change anything. A cart checkout's link shows every
order of it; each order has its own link too.
GET https://agenticfabricationnetwork.ai/status/<token> # the page
GET https://agenticfabricationnetwork.ai/status/<token>/json # the same as JSON
# → { "status": "shipped", "status_label": "Shipped", "summary": "...", "shop": "...",
# "eta_date": "2026-11-20", "tracking": { "carrier": "ups", "tracking_number": "1Z..." },
# "steps": [ { "status": "paid", "label": "Paid", "at": "..." }, ... ], "updated_at": "..." }
Reading the link never asks a shop anything, however often it is opened (60 reads a minute per address).
There are three ways for a program to pay.
1. A saved card on your key. A person saves a card once and sets the most the
key may spend per order and per day. After that, send pay: "saved" with the
checkout and the order is charged in the same call. See "Saved card" below.
2. Your agent has its own card. Some agents carry a card of their own: a
one-time card from a Link wallet, or a card issued for the agent by its company (for example
through Stripe Issuing, or a bank's agent card such as Mercury's). If your agent can also
drive a browser, it can pay today with no setup: call POST /v1/checkout
(MCP create_checkout), open checkout_url, and enter the card on
Stripe's payment page like any buyer. The order is placed when Stripe tells AFN the payment
went through. Give the agent's card a limit that fits the order; AFN does not see or limit
that card. A payment page can be paid for 30 minutes; after that, check out again.
3. A Stripe shared payment token. Planned. When it is on,
GET /v1/capabilities will say so (payment.shared_payment_token).
pending_payment, and nothing is sent to a shop.Setting it up (once, by a person). Call
POST /v1/payment-method/setup (MCP setup_saved_payment) and give the
person the setup_url it returns. On that page they set the most the key may spend
per order (up to $5,000) and per day (up to $10,000; a day is any 24 hours in a row), give
their email, agree, and enter the card on Stripe's page. The link works for one hour.
Whoever holds the key can spend up to those limits on that card, so keep the
key as safe as the card. The person gets an email for every payment, with a link that turns
the card off at once. Only a person can raise a limit, by going through the link again; the
key alone can lower a limit (PATCH /v1/payment-method) or turn the card off
(DELETE, MCP revoke_saved_payment).
GET /v1/payment-method (MCP get_saved_payment) reads the card's
brand and last four digits, the limits and what is left of the current 24 hours.
POST /v1/checkout
{
"quote_id": "q_...", "selection": true,
"pay": "saved",
"idempotency_key": "your-own-unique-string", // the same key never charges twice
"max_total_cents": 4230, // the most the buyer agreed to
"ship_to": { "name": "...", "street1": "...", "city": "...", "state": "TX", "zip": "78701" },
"contact": { "email": "buyer@example.com" }
}
# → { "order_id": "ord_...", "checkout_url": "...", "total_cents": 4230,
# "payment": { "method": "saved", "status": "paid", "card": { "brand": "visa", "last4": "4242" },
# "remaining_today_cents": 95770 } }
What the answer says. payment.status is paid (Stripe
confirmed the charge; the order is being placed), processing (the charge was sent
and Stripe's confirmation has not arrived yet: read GET /v1/orders/:id; nothing
is sent to a shop before it does), or needs_page — nothing was charged to the
saved card and checkout_url is a payment page for a person.
payment.reason says why: bank_challenge (the card's bank wants its
owner to approve), card_declined, nothing_to_charge (the total is
$0), price_being_confirmed, or tax_needs_page (sales tax is worked
out on the page).
What is required, and what is refused. With pay there is no page
to collect an address or show a total, so idempotency_key, ship_to,
the buyer's email and max_total_cents are all required
(400, code saved_payment_needs_address or
saved_payment_needs_max_total). The price rule is the same as on any checkout: a
confirmed price higher than max_total_cents is refused once with
409 price_went_up and nothing is charged. The other refusals, each with nothing
created and nothing charged: 402 no_saved_payment,
402 saved_payment_paused (several payments were refused: a person saves a card
again), 402 over_order_cap (cap_cents, total_cents),
402 over_daily_cap (remaining_cents, frees_at),
409 payment_busy (another payment on the key is being reserved: send the same
call again after retry_after_s), and 503 saved_payment_not_ready
(saved-card payment is switched off here: GET /v1/capabilities
payment.saved is false). For any of them, checking out without pay
gives a payment link. A key may try pay six times a minute.
A cart. POST /v1/carts/:id/checkout takes pay: "saved"
too, with buyer.email in place of contact.email. The whole cart is
one charge, and the per-order limit binds the cart's total.
On MCP. A saved card is reachable only when your connection sends the key
(Authorization: Bearer ufp_sk_…). The key is never a tool argument. With it,
create_checkout and checkout_cart take pay: "saved" and
the address fields, and setup_saved_payment, get_saved_payment and
revoke_saved_payment are offered. Without it, pay answers the
ordinary payment link and says a key is needed.
A quote can carry the pick itself: selection names ONE option by what it is —
the shop (vendor), and optionally process, the resolved options in
spec (material, color, finish,
thickness_in; a field left out or null does not narrow the pick),
quantity and shipping_speed — never by an offer id, because offer ids
change when a quote is priced again. Send it on POST /v1/quotes, or on
POST /v1/quotes/:id/refine ("selection": null clears it; left out,
the quote keeps the one it has). A refine body holding only selection is written
on the same quote: the same quote_id comes back and nothing is priced again.
Choosing starts that one shop's check: when the pick comes to exactly one
option whose shop answered more than 15 minutes ago (or was never asked), that one shop is
asked to confirm it as part of storing the pick, and the answer already shows it
(selection_match.check). It happens only when the body carried nothing but the
pick (cart_item_id and on_behalf_of aside) or the pick now comes to
a different option; the stored pick sent again beside other changes starts nothing. One shop
is asked once however many copies of the same answers choose that option: the others wait
for it or take its answer. Send on_behalf_of (your own opaque name for the
person) when you serve many people, so each has their own count of these asks. Quotes
refined from it inherit the pick, and the quote's .ufp part
file carries it, so a re-uploaded file comes back with the pick in place.
Every quote read then carries selection (as stored) and
selection_match: { status: "one" | "none" | "many", matched, offer_id,
shipping_option_id, speed_fallback, confirmed_until?, check?, price_changed? }, the pick
resolved against the offers on that read after every constraint.
check: { state: "running" | "fresh" | "not_started", code?, retry_after_s? } says
what its one shop is doing: fresh = its answer is under 15 minutes old;
running = it is being asked now (a checkout waits for it);
not_started = nobody is being asked and code says why
(ask_limited: the pick is kept and the shop is asked when the buyer pays;
quote_expired: reopen the quote, the pick is kept).
price_changed is the cart line's own object, for a page with no cart. speed_fallback: true means the picked speed is not among
the speeds the offer shows on that read; shipping_option_id then names its cheapest
shown speed, for display only — a checkout by the pick never orders it.
POST /v1/checkout
{ "quote_id": "q_...", "selection": true, "max_total_cents": 4230 }
# → the same response as above, for the one offer the pick names
An agent's whole loop is two calls: store the pick (its one shop starts confirming), then
this checkout — a payment link, or price_went_up once, or
offer_not_ready (send it again).
selection: true with quote_id, in place of offer_id and
shipping_option_id, orders the offer and speed selection_match names
— only when its status is one. None or several answers 400 with
code: selection_not_unique (the message says how many matched) and nothing is
created. A pick whose shipping speed the offer does not show answers 400 with
code: selection_speed_unavailable: another speed is never ordered in its place. The matched offer goes through the same checkout rule as any other.
check: true (on either form) runs the shop's manufacturability check first when
the offer is still unchecked, waits up to two minutes for the shop's answer, then
goes on or refuses as the rule says. To place exactly one order with no mistakes: list only
that shop in constraints.vendors, state the material, finish and shipping speed
in selection, read selection_match, then check out with
selection: true. The answer is the payment link, as always — the user pays there.
A cart is a list of parts, and each part is a quote: its material, quantity, rules
and its pick (selection) live on that quote, so nothing is configured twice.
The cart id (cart_…) is an anonymous token: whoever holds it can read and change
the cart. There are no accounts and no way to list carts.
POST /v1/carts
{ "items": [ { "quote_id": "q_..." }, { "file_url": "https://example.com/lid.step" } ] }
# → { "cart_id": "cart_...", "items": [ ... ], "by_shop": [ ... ], "total_cents": 0 }
GET /v1/carts/:id[?reconfirm=true][&reopen=true[&pressed=true]] # the cart: parts, picks, by-shop groups, totals
POST /v1/carts/:id/items # { quote_id | file_id | file_url, label? }
DELETE /v1/carts/:id/items/:itemId
PUT /v1/carts/:id/items/:itemId/quote # { quote_id } — point a part at another quote
POST /v1/carts/:id/fork # { item_ids?, for_link?, recheck?, into_cart_id? } — copy a shared cart
POST /v1/carts/:id/checkout # one payment link, one order per part
GET /v1/checkouts/:id # every order of that checkout
A part added by quote_id contacts no shop. A part added as a file gets one
ordinary quote, exactly as POST /v1/quotes would price it. Reading a cart contacts
no shop unless the read asks for it (?reconfirm=true, below). A cart holds at most 24 parts. To change a part, refine its quote and pass
cart_item_id in the refine body: the cart follows the part to the new quote by
itself.
GET /v1/carts/:id returns each part with its quote's status,
constraints_asked, selection and selection_match; when the
pick comes to exactly one option, picked (the shop, the price, the shipping speed,
the arrival date) and checkout:
{ state: "ready" | "needs_check" | "checking" | "not_orderable", reason, code?, confirmed_until? }.
code is the reason as one word, on every part that is not ready:
confirmation_lapsed, never_confirmed, rechecking,
shop_asks_off, ask_limited (needs_check — ask_limited:
the option is chosen and its shop is asked when the buyer pays); shop_checking,
confirming_price (checking); instant_only, check_failed,
outside_rules, price_unconfirmed, option_gone,
already_ordered, quote_expired, speed_not_shown,
cannot_be_placed, shop_not_connected (not_orderable). With
rechecking or shop_asks_off, ?reconfirm=true starts
nothing for that part. Every cart answer carries now, the network's own clock.
by_shop groups the picked parts by the shop that makes them, with subtotals and
shipping; total_cents is what they cost together. Each shop group carries
shipping: { mode, saved_cents, reason }: mode is
"ships_separately" (each part is its own order with the shop and its own
shipment, at its own shipping price) or "combined" (the shop takes the parts as
one order and ships them together); saved_cents is what that took off the
shipping and is 0 whenever the parts ship separately; reason says
it in plain words.
How long a price holds in a cart. A shop's confirmation of a picked option is
good for 15 minutes; a ready part says until when in checkout.confirmed_until
(count down to it from the cart's now, not from your own clock).
After it the part is not thrown out: it keeps its pick and its price and reads
needs_check. A plain read contacts no shop.
GET /v1/carts/:id?reconfirm=true asks the one shop of each picked part that needs
confirming — nobody else — and answers at once with those parts reading
checking; read again for the result. Choosing an option starts the same ask for
that one part, and the cart checkout starts it for every part that still needs it. When the
shop's answer moved the price or the arrival, the part carries
price_changed: { old_total_cents, new_total_cents, direction, old_eta_date?, new_eta_date?, changed_at }
(direction: up, down, or same when only
the arrival moved) — show it before the buyer pays. With check: false the
checkout contacts no shop: it refuses a part whose confirmation is older than 15 minutes
(offer_not_ready) and names it. A part
whose prices are past their 24-hour expiry is given a new quote of the same file,
configuration and pick by the read itself (quoted_anew: true): holding someone's
answers to the same request when any are under 24 hours old, else at our instant prices. No
shop is contacted for that, and the pick's shop confirms it when asked.
GET /v1/carts/:id?reopen=true ("someone came back to this cart") is the only
cart read that asks the shops about such a part again: once, one part at a time, from the
key's quote limit. The answer says reopen: none_needed,
asked, or press_needed (the old parts were already asked about
again once and nothing was done to the cart since; send &pressed=true when a
person asks for today's prices). A picked part also says picked.stale,
picked.answered_at, picked.eta_days and
picked.eta_approximate, as its offer does.
Hiding and showing a shop. On a quote that already holds a shop's answers,
putting the shop on vendors_exclude (or narrowing vendors) keeps
those answers and contacts nobody; showing the shop again brings them back with no shop
contacted. Only a shop that was never asked about this part is asked then, and it alone.
Sharing a cart. Never hand out the id of a cart someone is still working
on: whoever holds it can change it. To share a cart, copy it with
POST /v1/carts/:id/fork and { "for_link": true } and share the id
of the copy. That copy is a shared cart (status: "shared"): whoever
holds its id can read it and copy it, and nothing else. Adding or removing a part, moving a
part to another quote, changing or picking on one of its parts' quotes, the check on demand
on one of them and every checkout answer 400 with
code: cart_shared, so the link gives the same cart to everyone who opens it.
Whoever opens a shared cart calls POST /v1/carts/:id/fork and works on the
new cart it returns (copied: true; a cart never says which cart it was
copied from): the same parts in the same order, each configured and picked as it was. Each
part of that answer says quoted_anew: true when a new quote had to
be made for it, false when the shared one was copied.
{ "item_ids": [...] } copies only those parts, so a link to one part is a cart
of one. { "into_cart_id": "cart_…" } adds the copied parts to an open cart you
hold and answers with that cart, in one call; it is refused, with nothing made, when that
cart would hold more than 24 parts, and with 404 and
code: "into_cart_unknown" when that cart is not known (an unknown cart to copy
is a plain 404 with no code). No shop is contacted to make a copy, and the answer
comes back at once with every part priced. Each part says whose prices it shows in
price_source: "shared" (shop prices copied with nobody
asked: the sharer's, or the shops' own answers to the same request from the last 24
hours), "instant" (our instant prices, when the shared prices had expired or
were still coming in) or "own" (the cart's own quote, its shops asked). A pick
that matches no option on the copy reads selection_match.status: "none". The
buyer, the address, the email and any coupon never travel with a cart.
A link opened inside 24 hours asks nobody. A shop's answer is shown for 24
hours. A part whose answers are that young is copied with them as they stand (past 15
minutes they read stale, and the shop of the option someone chooses confirms
it before they pay). A part whose answers are older is copied at our instant prices —
unless anyone's quote of the same request (the same design by content, process, spec and
constraints, the destination included) answered under 24 hours ago, which is copied
instead. For a copy that is not for_link, each such old part is then asked
about again as POST /v1/quotes for that part would ask its shops, one part of
the cart at a time, a picked part first (its picked option is confirmed with its shop as
part of that). Each such part says where it stands in recheck:
"queued", "asking" or "done"; its
quote_id changes when its turn comes, so read it off the cart. However many
people open the same link, each shop is asked once per part: the first opener's quote asks,
and everyone else copies its answers for 24 hours. What each way costs in shop contact:
for_link: true none, ever; recheck: false none (use it to read a
shared cart); otherwise none for a link under 24 hours old, and one ordinary quote per
older part that nobody has answers for.
Limits on copying. Counted before anything is made: 60 copies a minute and
2000 a day per API key. With on_behalf_of (a client's own opaque id for the
person it is acting for) that person's counts bind: 12 copies a minute and 100 a day, and
30 re-check quotes a minute and 200 a day; the key's own copy count is then 600 a minute
with none by the day. The quotes a re-check will really start are also spent from the
same per-key limit as POST /v1/quotes; a part whose request someone is
already asking about starts none. Over a limit the answer is 429 rate_limited with
retry_after_seconds; nothing is made and no shop is asked. An open cart nobody
has changed for 90 days answers 404; a shared cart never does.
POST /v1/carts/:id/checkout
{ "idempotency_key": "a-unique-string-per-attempt",
"buyer": { "email": "you@example.com" },
"ship_to": { "name": "...", "street1": "...", "city": "...", "state": "TX", "zip": "78701" } }
# → { "checkout_id": "co_...", "checkout_url": "https://...", "total_cents": 8423,
# "orders": [ { "order_id": "ord_...", "item_id": "ci_...", "vendor": "...", "total_cents": 2140 }, ... ] }
The cart checkout confirms what needs confirming itself. Each picked part
whose shop confirmed it more than 15 minutes ago, or never, has that one shop asked
(check, default true; one shop per part, an ask already running is
joined), and the call waits up to wait_s seconds (default 120). When the wait
runs out first the answer is cart_not_ready with those parts reading
offer_not_ready: send the same call again with the same
idempotency_key (a refused call never uses it). Send
max_total_cents — the cart's total_cents as the buyer saw it. The
rule is judged on the total: the same or lower goes to the payment link; higher is refused
once with 409
{ error: "price_went_up", old_total_cents, new_total_cents, confirmed_until, items }
(items names the parts that rose), nothing is created and the key is not used.
All or nothing: every part needs a pick that comes to exactly one option the checkout rule
allows. If any part cannot be ordered the answer is 400 with
code: cart_not_ready and refusals naming each such part and why —
nothing is created and nothing is charged. only_selected: true leaves the parts
with nothing picked in the cart and orders the rest. Otherwise there is one checkout, one
ordinary order per part, and one payment page whose total is the sum of the
orders. After payment each order is placed with its own shop and sends its own emails; if a
shop cannot take its order, that order alone is refunded. The same
idempotency_key with the same body and the same cart returns the same checkout
and payment link, never a second set of orders; after any change (address, buyer, coupon, a
part, a pick) send a new key — the old one is refused with
code: idempotency_key_reused. A part already paid for by itself, or whose quote
has expired, is refused like any other part that cannot be ordered. A coupon applies once, to the cart total. buyer and
ship_to may be left out: the payment page then collects them once for every
order.
A saving is shown and charged only where the shop order is really one order. By default
nothing is combined: a connector that implements only placeOrder gets one order
per part, each shipped by itself at its own quoted shipping price. A connector opts in with
two things together:
placeOrders(input) — several parts, one ship-to, one shipping speed and one
combined price ceiling, placed as one vendor order, all or nothing. It
returns one vendorOrderRef, plus a reference per part where the shop gives
one.combinesShipping: { rule } — "flat_per_order" (shipping is
charged once per order: the highest of the parts' own charges at the chosen speed, not one
per part), "minimum_per_order" (the shipping line is the shop's order-minimum
top-up, owed once on the parts' combined subtotal, not once per part), or
"quoted_per_cart" (only the shop can price the parts together: the cart
prices them separately and says the combined price is pending).A declaration without placeOrders is never applied. A combination applies only
when every part of the shop's group uses the same shipping speed, and it never costs more than
shipping the parts separately. Each part stays its own order with its own status, emails and
refund; the orders share the shop's one order reference. Declare a rule only after it was
exercised against the real shop. No connector on the network declares one today.
AFN speaks standard MCP over Streamable HTTP — one endpoint serves ChatGPT, Claude, Gemini,
Cursor, Copilot, and every other MCP client. Tools:
get_fabrication_quote, refine_quote, create_checkout,
get_order_status, leave_review, and for carts
create_cart, get_cart, add_to_cart,
remove_from_cart, checkout_cart; and, for a connection that
sends its API key, setup_saved_payment, get_saved_payment,
revoke_saved_payment (see Paying without a person).
ChatGPT additionally renders an embedded offer-comparison
widget; every other client gets the same results as complete text.
| Client | Setup |
|---|---|
| ChatGPT | Settings → Apps & Connectors → create a connector with the /mcp URL |
| Claude Code / Desktop / claude.ai | claude mcp add --transport http ufp <mcp-host>/mcp (or add a custom connector in claude.ai settings) |
| Gemini CLI | add {"ufp": {"httpUrl": "<mcp-host>/mcp"}} under mcpServers in ~/.gemini/settings.json |
| Cursor / VS Code Copilot / others | add a remote (Streamable HTTP) MCP server pointing at <mcp-host>/mcp |
| Custom agents (LangChain, Agents SDK, ADK…) | use plain REST with openapi.json — same funnel, same offers |
https URL or a base64 data: URL in the design_file
tool parameter — AFN fetches and stores it either way.