POST /api/walkthrough/advance

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

What it does

`expectedStepIndex` is a compare-and-swap: the move is refused with 409 when the caller's idea of the current step disagrees with the stored one, so two tabs cannot advance the walkthrough twice. Moving back returns the `href` of the page that step produced, resolved from the user's own generated pages, or `/` when there is none.

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
`expectedStepIndex`	body	`integer`	Required	The step the caller believes it is on.
`direction`	body	`string`	Optional	`back` to rewind. Any other value is refused.

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 '{"expectedStepIndex":"<integer>","direction":"<string>"}' \
  "https://flowfinds.ai/api/walkthrough/advance"

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

import requests

s = requests.Session()
r = s.post("https://flowfinds.ai/api/walkthrough/advance", json={
    "expectedStepIndex": "<integer>",
    "direction": "<string>"
  })
data = r.json()

Recorded example

curl -s -b cookies.txt -c cookies.txt \
  -X POST -H 'Content-Type: application/json' \
  -d '{"expectedStepIndex":2}' \
  "$FLOWFINDS_ORIGIN/api/walkthrough/advance"

Responses

`200` — The move was applied.

Field	Type	Description
`ok`	`boolean`	True.
`stepIndex`	`number`	The new position.
`href`	`string \| undefined`	Where to navigate when rewinding.

Errors

Status	Reason	When
`400`	—	The body is malformed, `expectedStepIndex` is not an integer, or `direction` is neither absent nor `back`.
`404`	`disabled`	The walkthrough feature flag is off.
`409`	—	`expectedStepIndex` does not match the stored step. The body carries `reason`.

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