POST /api/pages

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

What it does

Turns a normalised intent into a stored page and returns its permanent path. A guest user is minted if there is none, so the page has an owner from the moment it exists. Repeating an intent reuses the existing page rather than creating a second one, and `reused` says which happened. When generation cannot produce a page the response is 200 with `kind: "fallback"` and a route to send the visitor to instead — a failure to generate is not a failure to answer.

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 intent. Refused as `empty intent` when blank.

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>"}' \
  "https://flowfinds.ai/api/pages"

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

import requests

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

Recorded example

curl -s -b cookies.txt -c cookies.txt \
  -X POST -H 'Content-Type: application/json' \
  -d '{"text":"show me my supplier terms"}' \
  "$FLOWFINDS_ORIGIN/api/pages"

Responses

`200` — A page exists.

Field	Type	Description
`kind`	`string`	`generated`.
`href`	`string`	`/p/<slug>`.
`reused`	`boolean`	True when an existing page was returned.
`headline`	`string`	The page's headline.
`insight`	`string`	The one-line insight.

`200` — Generation declined.

Field	Type	Description
`kind`	`string`	`fallback`.
`href`	`string`	Where to send the visitor instead.
`reason`	`string`	Why generation declined.

Errors

Status	Reason	When
`400`	—	The body is malformed, or the intent is empty.
`429`	`quota exceeded`	The owner's page quota is used up.

POST /api/intent — Ask the commerce assistant, or resolve a navigation 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.