fn_live_ / fn_test_ bearer keys as the REST API. Long runs
follow a start-then-poll shape — search returns immediately, get_session is cheap
to poll — and tools return bounded, structured summaries with ids and URLs to go
deeper, never megabytes of rows.
Setup
Claude Code:fn_test_ key in CI — test mode behaves identically
(replay-backed), so agent integration is testable at $0.
The tools
search — ask a question, get a session id at once
Input: { query, max_spend_usd } (both required — the budget ceiling applies exactly
as on REST). Returns
{ session_id, status: "running", estimated_wait: "minutes — poll get_session" }
immediately. A decline-to-spend returns { status: "abstained", reason, parsed } —
$0, stated, never a protocol error.
get_session — poll for progress and the answer
Input: { session_id } (also accepts an extraction id — one lookup tool serves both
run types). Once answered, returns a bounded digest: qualified, records,
sources with per-source receipt status, spend_usd, the top qualified rows (≤ 25,
with source attribution), unchecked (stated), and result_url for the full catalog.
Never the whole corpus.
follow_up — narrows, asks, and priced re-aims
Input: { session_id, text, confirm?, max_spend_usd? }. Narrows and asks return the
answer with row citations, free. A re-aim returns
{ status: "proposal", proposal: { estimated_usd, passes, expires_at } } — your agent
decides (or carries the quote back to its human), then calls again with
confirm: true. Pre-authorize with max_spend_usd to skip the round-trip. This is
the same proposal flow as REST, surfaced as structured results
on purpose: a calling agent can relay the price before money moves.
extract — the URL-first path
Input: { url, entity, guidance?, max_spend_usd }. One known catalog link, straight
to the extraction agent — no fan-out. Returns { extraction_id, status }; poll with
get_session.
refresh — fresh data at marginal cost
Input: { id, max_spend_usd, max_age_s? } where id is sess_… or ext_…. Returns
the new run id, served_from: "record" when recency made it free, and the diff when
it re-ran.
list_sessions · whoami
list_sessions { limit?, status? } → recent runs, one line each.
whoami {} → { account, key_name, balance_usd, open_reserves_usd, caps } — lets an
agent check affordability before proposing spend to its human.
Error behavior
REST error envelopes map into tool results withcode preserved — a 402 comes back
as { status: "insufficient_credit", balance_usd, top_up_url }, never as a protocol
error, so the calling agent can relay it and recover.
Deliberate absences
Monitors are not in the v1 toolset: standing spend should be created by a human in the dashboard or by code via REST — not by an agent mid-conversation.For agents reading these docs
Every page on this site has a.md variant at the same URL plus .md, and the site
serves /llms.txt — start there.