POST /api/intent

Request	`POST /api/intent`
Authentication	Session cookie required
Handler	`flowfinds-organ/app/api/intent/route.ts`

What it does

The product surface's single conversational entry point. `surface` decides which of two paths runs. On `home` or `supplier` the request is handed to the commerce agent, which requires a resolved commerce identity — the signed-in user plus an `ff_dash_session` cookie linking to the engine — and answers with cited evidence. On the default surface it resolves a navigation intent instead, and answers a small set of counting questions directly for a signed-in user. Responses are always `Cache-Control: no-store`.

Authentication

Session cookie required. Send the ff_session cookie. Without one the engine treats the caller as a new visitor with no holds and no claims, and returns a new cookie to use from then on.

Parameters

Parameter	In	Type	Required	Description
`text`	body	`string`	Required	The founder's message. The agent refuses anything over 3,000 characters.
`surface`	body	`string`	Optional	`home`, `supplier` or omitted for the default intent resolver.
`ff_dash_session`	cookie	`string`	Optional	Links the signed-in user to their engine session. Required for the assistant surfaces.

Request

The cookie jar carries the session between calls. Angle-bracketed values are the parameter types from the table above.

cURLJavaScriptPython

curl -s -b cookies.txt -c cookies.txt \
  -X POST -H 'Content-Type: application/json' \
  -d '{"text":"<string>","surface":"<string>"}' \
  "https://flowfinds.ai/api/intent"

const res = await fetch("https://flowfinds.ai/api/intent", {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "text": "<string>",
    "surface": "<string>"
  }),
});
const data = await res.json();

import requests

s = requests.Session()
r = s.post("https://flowfinds.ai/api/intent", json={
    "text": "<string>",
    "surface": "<string>"
  })
data = r.json()

Recorded example

curl -s -b cookies.txt -c cookies.txt \
  -X POST -H 'Content-Type: application/json' \
  -d '{"text":"What is my break-even CPA?","surface":"home"}' \
  "$FLOWFINDS_ORIGIN/api/intent"

Responses

`200` — The assistant answered.

Field	Type	Description
`kind`	`string`	`answer`, `route`, `clarify` or `error`.
`message`	`string`	The answer, at most 1,800 characters.
`href`	`string`	Where to navigate, on `kind: "route"`.
`evidence`	`array`	Only the tool results the answer actually cited: `id`, `source`, `status`, `observed_at`.
`uncertainties`	`string[]`	Up to four things the agent could not establish.
`run_id`	`string`	The run identifier.
`engine`	`string`	`commerce-reasoning-v1`.
`degraded`	`boolean`	True when the answer came from the deterministic fallback rather than the model.

`200` — The intent resolver answered.

Field	Type	Description
`kind`	`string`	`clarify` among others.
`confidence`	`number`	How confident the resolution is.
`message`	`string`	The answer.

Errors

Status	Reason	When
`400`	—	The body is not JSON.
`401`	—	An assistant surface was asked for without a resolvable commerce identity.

POST /api/pages — Generate a page from an intent.
POST /api/journey — Issue a single-use journey carrier.
POST /api/journey/[id]/consume — Redeem a journey carrier once.
GET /api/walkthrough — The walkthrough's steps and this user's position in it.
POST /api/walkthrough/advance — Move forward or back a step.
POST /api/walkthrough/dismiss — Dismiss the walkthrough.
POST /api/auth/request-link — Request a magic sign-in link.
GET /api/auth/callback — Redeem a magic link.

Back to the API reference index, or read the cookbook for recipes that compose this endpoint with others.