API reference

FlowFinds is two HTTP surfaces. The sourcing engine serves everything under /api/… — finding a product, holding it, pricing it, building the store and running what happens after the sale. The product surface serves the conversational routes: the commerce assistant, generated pages, the walkthrough and sign-in. Both are documented here, from their handlers.

This reference is generated from a single typed array. Each page below is one entry in lib/api-spec.ts, so the reference cannot describe an endpoint the spec does not hold, and an endpoint added to the spec appears here without anybody writing a page.

Authentication in one paragraph

There is no API key. The engine identifies a caller by an ff_session cookie: if the request carries one it is used, and if it does not, the handler mints a fresh identifier, serves the request under it, and returns it in Set-Cookie. Every session-scoped resolver then filters on that value, which is why a client is, in practice, a cookie jar. Read the authentication guide for the full treatment.

# The first call mints a session. Keep the cookie jar for every call after it.
curl -s -c cookies.txt -b cookies.txt "$FLOWFINDS_ORIGIN/api/find"

# The same jar now carries ff_session, so the hold and the claim resolve.
curl -s -c cookies.txt -b cookies.txt "$FLOWFINDS_ORIGIN/api/offer"

Reading a response

The consequence for a client is concrete: check status in the body before you check the HTTP code. A great many of the engine’s refusals are successful HTTP responses that say, in a named field, why they could not do what was asked. Errors covers the codes; GET /api/reasons serves the closed set of reason strings.

Internal and administrative paths

These exist in the running server and are listed so the surface is accounted for rather than quietly trimmed. They are not part of the developer interface: they are authenticated separately, called by a payment provider, or serve generated HTML rather than JSON. Their shapes follow the console or the provider that calls them, so no contract is documented for them here.

What this reference covers

The extracted surface lists 99 distinct paths across the engine's handler files, many of them repeated across scratch copies of `server.py`. This reference documents the developer-facing paths in full and accounts for the remainder — the admin console, the marketing lane, the payment-provider callbacks and the prefixes that serve generated HTML — as internal entries rather than omitting them.

Next

• Quickstart — from nothing to a first successful call.
• Agents and tools — the tools the commerce agent can call, and the evidence each one returns.
• Cookbook — recipes that compose these endpoints into a working sequence.

90 endpoints are documented above. Start with GET /api/find.

Next: Quickstart · Agents and tools · Cookbook