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:

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. 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.

Keep it in sync

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.

MCP tools for sellers

The same key against POST /mcp unlocks create_listing, bulk_update_listings (reprice up to 200 SKUs per call), bulk_mark_shipped, bulk_export_orders, get_quote_requests, respond_to_quote and seller_inbox_summarise. Full schemas: /api/mcp/schema.json.