ForthClear Developer & Agent API

Two things live here: publishing your surplus inventory from your own system, and reading the catalog or requesting a quote as an AI agent.

For agents — no key required

The whole catalog is readable anonymously, and since 2026-08-16 so is asking for a quote. Discovery documents:

EndpointWhat it is
/.well-known/ucpUniversal Commerce Protocol discovery
/.well-known/acpAgentic Commerce Protocol discovery
/acp/feed.jsonProduct feed, cursor-paginated, up to 200/page
/api/ucp/catalog/productsCatalog with filters, offset-paginated
/agents/sitemap.xmlEvery listing, plus a markdown rendition of each
/openapi.jsonOpenAPI 3.1 schema (GPT Actions compatible)
POST /mcpMCP Streamable HTTP. Documentation. Tools: schema.json

Request a quote

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?"
  }'
Anonymous is fine, within limits. No key means 5 requests per hour per IP, and the quote creates an isolated lead — it will never attach to an existing ForthClear account by email alone. Send an 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.

For sellers — publish inventory from your own system

One key, used by both transports. Generate it under Settings → API Keys; it is shown once.

Create a listing

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
  }'
Three things worth knowing before your first call. Only 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.

Why is a new listing missing from the public catalog?

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.

Keep it in sync

CallUse
PATCH /api/products/:id/quantityStock changed, or sold out (send 0)
PUT /api/products/:idPrice 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.

MCP tools for sellers

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.