POST /api/intent/apply

Request	`POST /api/intent/apply`
Authentication	Session cookie required
Handler	`backend/server.py`

What it does

Commits a proposal by echoing it back. The engine refuses `stale_proposal` when the proposal no longer matches what it would propose now, and `no_proposal_echoed` when the caller sent none — an apply that trusted the request alone could commit a change the founder never saw. An irreversible change is refused unless `confirm_irreversible` is set. The response carries `because` and `source_row` read back from the applied record, and `reversible` so the screen can offer the revert honestly.

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
`ff_session`	cookie	`string`	Optional	The session identifier. Omit it on the first call and store the value the response sets; every later call must send the same one or the engine treats the caller as a new visitor with no holds and no claims.
`surface`	body	`string`	Required	The surface being edited.
`requested`	body	`string`	Required	The original request.
`proposed`	body	`object`	Required	The proposal returned by `POST /api/intent`, echoed verbatim.
`confirm_irreversible`	body	`boolean`	Optional	Required when the change cannot be reverted.

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 '{"surface":"<string>","requested":"<string>","proposed":"<object>","confirm_irreversible":"<boolean>"}' \
  "https://flowfinds.ai/api/intent/apply"

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

import requests

s = requests.Session()
r = s.post("https://flowfinds.ai/api/intent/apply", json={
    "surface": "<string>",
    "requested": "<string>",
    "proposed": "<object>",
    "confirm_irreversible": "<boolean>"
  })
data = r.json()

Recorded example

curl -s -b cookies.txt -c cookies.txt \
  -X POST -H 'Content-Type: application/json' \
  -d '{"surface":"…","requested":"…","proposed":{ }}' \
  "$FLOWFINDS_ORIGIN/api/intent/apply"

Responses

`200` — The intent was applied.

Field	Type	Description
`status`	`string`	`applied`, or `regenerate_failed` when the change committed but the store rebuild did not.
`surface`	`string`	The surface that was edited.
`applied`	`object`	The intents book entry now in force for the product.
`because`	`string`	The justification, read back from the record.
`source_row`	`object`	The dated row that justified the change.
`reversible`	`boolean`	Whether `POST /api/intent/revert` can undo it.
`store_status`	`string`	The manifest status after regeneration.

Errors

Status	Reason	When
`409`	`stale_proposal`	The echoed proposal no longer matches the engine's current one.
`409`	`no_proposal_echoed`	No proposal was sent back.
`409`	`irreversible_without_confirmation`	The change is irreversible and `confirm_irreversible` was not set.
`409`	`build_in_progress`	A build is already running for this product.
`500`	`apply_build_raised`	The regeneration raised.

GET /api/store — The state of the session's storefront.
POST /api/store — Start generating the storefront for the session's product.
POST /api/store/publish — Verify and publish the storefront, regenerating it if verification demands.
POST /api/intent — Ask the engine what it would change on a surface, and why.
POST /api/intent/order — Override the section the storefront leads with.
POST /api/intent/revert — Undo the last applied intent.
POST /api/ai/edit — Edit the storefront in natural language.
GET /api/editor/ — Read editor state and store metrics.

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