Two things live here: publishing your surplus inventory from your own system, and reading the catalog or requesting a quote as an AI agent.
The whole catalog is readable anonymously, and since 2026-08-16 so is asking for a quote. Discovery documents:
| Endpoint | What it is |
|---|---|
/.well-known/ucp | Universal Commerce Protocol discovery |
/.well-known/acp | Agentic Commerce Protocol discovery |
/acp/feed.json | Product feed, cursor-paginated, up to 200/page |
/api/ucp/catalog/products | Catalog with filters, offset-paginated |
/agents/sitemap.xml | Every listing, plus a markdown rendition of each |
/openapi.json | OpenAPI 3.1 schema (GPT Actions compatible) |
POST /mcp | MCP Streamable HTTP. Documentation. Tools: schema.json |
curl -X POST https://app.forthclear.io/api/ucp/quotes \
-H "Content-Type: application/json" \
-d '{
"product_id": "product_2683",
"quantity": 500,
"buyer": { "email": "buyer@example.com" },
"message": "Interested in the full lot — what is your best price?"
}'
X-MCP-API-Key for a higher allowance, or a buyer-scoped
X-Agent-Token to file quotes against a real account. Quantities above the listed
stock are accepted deliberately: if you want 500 of something we list 200 of, we want to hear it.
One key, used by both transports. Generate it under Settings → API Keys; it is shown once.
curl -X POST https://app.forthclear.io/api/products \
-H "X-MCP-API-Key: $FORTHCLEAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Wera Kraftform screwdriver set — overstock lot",
"description": "Surplus stock, new in box. 200 sets available.",
"category": "tools",
"condition": "overstock",
"price": 18.50,
"quantity": 200,
"imageUrl": "https://your-cdn.example/lot.jpg",
"promotePublicly": true
}'
name and description are required — omit
price or quantity and you get a listing priced at 1, with 1 unit, rather
than an error. There is no upsert: posting the same sku twice creates
two listings; use PUT to change an existing one. Omitting
imageUrl triggers an automatic image search, and the request fails with 400
if nothing suitable is found — so pass one if you can.
promotePublicly: true is what puts a listing into the agent-facing surfaces above. Without it the listing stays in-app only.
A successful create request can still leave a listing visible only in the app. Set promotePublicly to true when you want it in the agent-facing catalog and feeds. If you omit imageUrl, the API tries to find an image and the create request can fail when it finds none. Supply an image URL for the actual goods when you can. Also send the intended price and quantity explicitly: omitting them creates a listing with the defaults described above.
| Call | Use |
|---|---|
PATCH /api/products/:id/quantity | Stock changed, or sold out (send 0) |
PUT /api/products/:id | Price or details changed |
Every create, update or quantity call also counts as an availability confirmation, so an integration that syncs at least every 90 days never receives a staleness email.
The same key against POST /mcp unlocks create_listing,
bulk_update_listings (reprice up to 200 SKUs per call), set_listing_shipping (shipping price, lot type and ship-from), bulk_mark_shipped,
bulk_export_orders, get_quote_requests, respond_to_quote and
seller_inbox_summarise. Full schemas: /api/mcp/schema.json.