POST /api/discover

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

What it does

Runs the sourcing script and hands back what the terminal would have shown, line by line, plus the exit code. The engine does not summarise the run: `log` and `stderr` are the script's own words, so the operator sees the same thing a shell would show. `status` is `ok` only on a zero exit code.

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.
`q`	body	`string`	Optional	A query to discover against. When absent, the scheduled discovery script is run instead and `ran` names the script path.
`mode`	body	`string`	Optional	Selects the discovery mode the script runs in.
`use_research_brief`	body	`boolean`	Optional	Seed the run from the nightly research brief rather than from the query alone.

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 '{"q":"<string>","mode":"<string>","use_research_brief":"<boolean>"}' \
  "https://flowfinds.ai/api/discover"

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

import requests

s = requests.Session()
r = s.post("https://flowfinds.ai/api/discover", json={
    "q": "<string>",
    "mode": "<string>",
    "use_research_brief": "<boolean>"
  })
data = r.json()

Recorded example

curl -s -b cookies.txt -c cookies.txt \
  -X POST -H 'Content-Type: application/json' \
  -d '{"q":"…"}' \
  "$FLOWFINDS_ORIGIN/api/discover"

Responses

`200` — The run completed, successfully or not.

Field	Type	Description
`status`	`string`	`ok` on exit code 0, otherwise `refused`.
`query`	`string \| null`	The query as run.
`ran`	`string \| null`	Path of the script that was run, relative to the repository root, when no query was supplied.
`exit_code`	`number`	The process exit code.
`log`	`string[]`	Non-empty stdout lines, unedited.
`stderr`	`string[]`	Non-empty stderr lines, unedited.

Errors

This endpoint has no failure path of its own. An uncaught exception anywhere in the engine is still returned as structured JSON by the shared guard.

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/pass — Claim the held product, or pass on it and be shown the next one.
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.
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.