POST /api/discovery-research

Request	`POST /api/discovery-research`
Authentication	Session cookie required
Handler	`backend/external_discovery.py`

What it does

Queues a research run against the supplied query and returns immediately with 202. Poll the GET form for the state. The run is rate-limited; exceeding the limit raises a 429 carrying the limit that was hit.

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.
`query`	body	`string`	Required	What to research.

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 '{"query":"<string>"}' \
  "https://flowfinds.ai/api/discovery-research"

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

import requests

s = requests.Session()
r = s.post("https://flowfinds.ai/api/discovery-research", json={
    "query": "<string>"
  })
data = r.json()

Recorded example

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

Responses

`202` — The run was accepted and started.

Errors

Status	Reason	When
`400`	—	The body is not JSON, or `query` is missing.
`401`	—	The session has no account.
`429`	—	The research rate limit was hit. The body names the limit.

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.
POST /api/discover — Run the discovery script and return its terminal output verbatim.

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