POST /api/journey

Request	`POST /api/journey`
Authentication	No authentication
Handler	`flowfinds-organ/app/api/journey/route.ts`

What it does

Stores the state of a journey — the active route, the insight and the organ state — behind a 128-bit single-use identifier bound to a hash of the caller's address and user agent. The identifier travels through a redirect (including through sign-in) as `?jc=<carrierId>`, so state survives a navigation without being carried in a URL anyone can read or replay.

Authentication

No authentication. The response does not depend on a session.

Parameters

Parameter	In	Type	Required	Description
`activeRoute`	body	`string`	Required	The route the journey is on.
`insight`	body	`string`	Required	The insight to carry across.
`organState`	body	`string`	Required	The serialised organ state.
`headline`	body	`string`	Optional	The headline to restore.
`routeTitle`	body	`string`	Optional	The route's title.
`revealed`	body	`boolean`	Optional	Whether the route had been revealed.

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 '{"activeRoute":"<string>","insight":"<string>","organState":"<string>","headline":"<string>","routeTitle":"<string>","revealed":"<boolean>"}' \
  "https://flowfinds.ai/api/journey"

const res = await fetch("https://flowfinds.ai/api/journey", {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "activeRoute": "<string>",
    "insight": "<string>",
    "organState": "<string>",
    "headline": "<string>",
    "routeTitle": "<string>",
    "revealed": "<boolean>"
  }),
});
const data = await res.json();

import requests

s = requests.Session()
r = s.post("https://flowfinds.ai/api/journey", json={
    "activeRoute": "<string>",
    "insight": "<string>",
    "organState": "<string>",
    "headline": "<string>",
    "routeTitle": "<string>",
    "revealed": "<boolean>"
  })
data = r.json()

Recorded example

curl -s -b cookies.txt -c cookies.txt \
  -X POST -H 'Content-Type: application/json' \
  -d '{"activeRoute":"/","insight":"…","organState":"…"}' \
  "$FLOWFINDS_ORIGIN/api/journey"

Responses

`200` — The carrier was issued.

Field	Type	Description
`carrierId`	`string`	The single-use identifier.

Errors

Status	Reason	When
`400`	`invalid payload`	`activeRoute`, `insight` or `organState` is missing or not a string.
`400`	`malformed body`	The body is not JSON.

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