POST /api/pass

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

What it does

The largest handler in the engine and the one that writes the claim. It records the pass, mints the next hold itself — which is why the find meter had to move into `hold_for`, since a guard on one caller is a guard on one of seven — and, when an email is supplied, creates the claim that everything downstream is scoped to. A referrer's address may be attached at claim time. The response reports whether the claim is exclusive, since a small set of catalog identifiers are deliberately shared.

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.
`email`	body	`string`	Optional	The address the claim is credited to. Required to claim; omit to pass.
`product_id`	body	`string`	Optional	The product being claimed or passed. Must be one this session was shown.
`referrer_email`	body	`string`	Optional	The address of the founder whose coded link brought this session in. Attribution only; a link alone never becomes a funded person.

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 '{"email":"<string>","product_id":"<string>","referrer_email":"<string>"}' \
  "https://flowfinds.ai/api/pass"

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

import requests

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

Recorded example

curl -s -b cookies.txt -c cookies.txt \
  -X POST -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","product_id":"…"}' \
  "$FLOWFINDS_ORIGIN/api/pass"

Responses

`200` — The claim was recorded.

Field	Type	Description
`claimed`	`string`	The claimed product identifier.
`email`	`string`	The address the claim was credited to, read back from the stored row.
`exclusive`	`boolean`	False only for the deliberately shared catalog identifiers.
`servable`	`number`	Products still servable after the claim.

`200` — The product was passed. The next hold is minted and the next card served in the same response.

Errors

Status	Reason	When
`400`	`expected JSON {email, product_id}`	The body is missing or malformed.
`400`	`not a candidate you were shown`	The product was never served to this session.
`404`	`not found`	No such product identifier, or no claim record to act on.
`404`	`unknown product_id`	The identifier is not in the catalog.
`409`	`already claimed`	The product has been claimed, by this session or another.
`409`	`you passed on this one`	This session already passed on the product.
`409`	`not your find`	The product is held by a different session.

GET /api/find — Serve this session's product, minting a hold if it does not have one.
GET /api/feed — Serve the whole field: this session's find first, then what it beat.
POST /api/select — Move this session's hold onto a named product from the field.
POST /api/analyze — Run the analyser over any product description, claimed or not.
GET /api/analysis — The analysis of the product this session holds.
POST /api/ask — Ask a question against one or more catalog products.
POST /api/discover — Run the discovery script and return its terminal output verbatim.
GET /api/discovery-research — Read the state of the external discovery research job.

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