Developer Docs

import { Free2AIClient } from "@free2aitools/sdk";

// No authentication is currently required for the public API.
const client = new Free2AIClient();

// search() returns a typed SearchResponse; `results` is SearchResult[].
const res = await client.search({ q: "code generation", limit: 5 });
for (const r of res.results) {
  console.log(r.name, r.fni_score); // real, typed fields
}
// Free2AITools provides structured discovery and evidence;
// the caller or Agent makes the final decision.

#!/usr/bin/env bash
# Canonical workflow: search -> derive ids from results -> inspect entity ->
# compare candidates -> the CALLER decides. No id is hard-coded; all ids come
# from the search response. Prerequisite: jq (https://jqlang.github.io/jq/).
set -euo pipefail
BASE="${F2AI_BASE:-https://free2aitools.com}"

# 1) Search. --fail-with-body surfaces 4xx/5xx; we branch on the status code.
http_code=$(curl -sS -o /tmp/f2ai_search.json -w '%{http_code}' \
  "$BASE/api/v1/search?q=code+generation&limit=5") || true
case "$http_code" in
  200) ;;                                  # ok
  400) echo "bad request (400) - fix the query"; exit 1 ;;
  404) echo "not found (404)"; exit 1 ;;
  429|503) echo "transient ($http_code) - retry after Retry-After seconds"; exit 75 ;;
  *)   echo "server error ($http_code)"; exit 1 ;;
esac

# 2) Derive ids from the result set. Fail honestly if fewer than 2 are returned
#    (do NOT silently fall through to an empty compare).
mapfile -t IDS < <(jq -r '.results[].id' /tmp/f2ai_search.json)
if [ "${#IDS[@]}" -lt 2 ]; then
  echo "search returned ${#IDS[@]} result(s); need >= 2 to compare. Stopping."
  exit 1
fi

# 3) Inspect one candidate (evidence is in the entity response: FNI factors +
#    specs). REST has no separate /explain endpoint. URL-encode '/' in the id.
ID_ENC=$(printf '%s' "${IDS[0]}" | jq -sRr @uri)
curl -sS "$BASE/api/v1/entity/$ID_ENC" | jq '.entity.fni.factors'

# 4) Compare the first two candidates side by side.
curl -sS "$BASE/api/v1/compare?ids=${IDS[0]},${IDS[1]}" | jq '.'

# 5) The caller/agent makes the final selection from this evidence.
echo "Review the factors above and choose. Free2AI does not decide for you."

// Node 18+ (built-in fetch) — the direct REST path, no additional dependency.
// You can also use the official TypeScript SDK: npm install @free2aitools/sdk (see the SDK section above).
// Canonical workflow: search -> ids from results -> entity (evidence) ->
// compare -> the caller decides. Retries ONLY 429/503, max 2, honors Retry-After.
const BASE = process.env.F2AI_BASE || "https://free2aitools.com";

async function call(path, { timeoutMs = 10000 } = {}) {
  let attempt = 0;
  for (;;) {
    const ctrl = new AbortController();
    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
    let res;
    try {
      res = await fetch(BASE + path, { signal: ctrl.signal });
    } finally {
      clearTimeout(timer);
    }
    // Status check BEFORE parsing the body.
    if (res.status === 400 || res.status === 404) {
      throw new Error(`non-retryable ${res.status} for ${path}`);
    }
    if ((res.status === 429 || res.status === 503) && attempt < 2) {
      const ra = Number(res.headers.get("retry-after"));
      const delay = Number.isFinite(ra) && ra > 0 ? ra * 1000 : 500 * (attempt + 1);
      await new Promise((r) => setTimeout(r, Math.min(delay, 5000)));
      attempt++;
      continue;
    }
    if (!res.ok) throw new Error(`request failed ${res.status} for ${path}`);
    return res.json();
  }
}

export async function pickCandidates(query = "code generation") {
  const search = await call(`/api/v1/search?q=${encodeURIComponent(query)}&limit=5`);
  const results = Array.isArray(search.results) ? search.results : [];
  if (results.length < 2) {
    throw new Error(`need >= 2 results to compare; got ${results.length}`);
  }
  // Use the ids the server returned. Preserve null (not-measured) vs 0 (measured).
  const ids = results.map((r) => r.id);
  const entity = await call(`/api/v1/entity/${encodeURIComponent(ids[0])}`);
  const factors = entity?.entity?.fni?.factors ?? null; // may be null; no fabrication
  const comparison = await call(`/api/v1/compare?ids=${ids[0]},${ids[1]}`);
  // The caller/agent reasons over this evidence and makes the final choice.
  return { ids, factors, comparison };
}

# python -m pip install requests
# Any standards-compliant HTTP client may be used.
# Canonical workflow: search -> ids from results -> entity (evidence) ->
# compare -> the caller decides. Retries ONLY 429/503, max 2, honors Retry-After.
import os
import time
import requests

BASE = os.environ.get("F2AI_BASE", "https://free2aitools.com")


def call(path, timeout=(5, 10)):
    attempt = 0
    while True:
        resp = requests.get(BASE + path, timeout=timeout)
        if resp.status_code in (400, 404):
            resp.raise_for_status()  # non-retryable client error
        if resp.status_code in (429, 503) and attempt < 2:
            ra = resp.headers.get("Retry-After")
            try:
                delay = float(ra) if ra is not None else 0.5 * (attempt + 1)
            except ValueError:
                delay = 0.5 * (attempt + 1)
            time.sleep(min(delay, 5.0))
            attempt += 1
            continue
        resp.raise_for_status()  # raises on remaining 5xx; no indefinite retry
        return resp.json()


def pick_candidates(query="code generation"):
    search = call(f"/api/v1/search?q={requests.utils.quote(query)}&limit=5")
    results = search.get("results") or []
    if len(results) < 2:
        raise RuntimeError(f"need >= 2 results to compare; got {len(results)}")
    ids = [r.get("id") for r in results]  # use server-returned ids
    entity = call(f"/api/v1/entity/{requests.utils.quote(ids[0], safe='')}")
    # null-safe: factors may be missing/None; never fabricate a default.
    factors = (entity.get("entity") or {}).get("fni", {}).get("factors")
    comparison = call(f"/api/v1/compare?ids={ids[0]},{ids[1]}")
    # The caller/agent reasons over this evidence and makes the final choice.
    return {"ids": ids, "factors": factors, "comparison": comparison}