Developer Docs

REST API · Model Selection · MCP Server · FNI Badge

All endpoints are free, no authentication required

REST API

GET /api/v1/search

Search and rank AI models, tools, datasets, and papers by FNI score.

Parameters

Param Type Default Description
q string - Search query (required)
limit number 5 Max results (1-5, free tier)
type string all Filter by entity type. Canonical values: model, tool, dataset, paper. Common source-prefixed aliases also accepted: hf-model, gh-model, arxiv-paper, gh-tool, etc. (auto-mapped to canonical).

Example

curl "https://free2aitools.com/api/v1/search?q=code+generation&limit=2"

Response

{
  "version": "fni_v2.0",
  "results": [
    {
      "id": "hf-model--meta-llama--llama-3-8b",
      "name": "Llama 3 8B",
      "type": "model",
      "fni_score": 87.2
    },
    {
      "id": "hf-model--deepseek-ai--deepseek-v3",
      "name": "DeepSeek V3",
      "type": "model",
      "fni_score": 83.5
    }
  ],
  "meta": {
    "elapsed_ms": 42,
    "total": 2
  }
}

Search may return a retryable transient 503 under cold-path or fallback budget limits. Retry according to the Retry-After header.

POST /api/v1/select

Filter the catalog by declared metadata; returns FNI-ranked entries. Constraints are metadata/heuristic filters, not verified compatibility analysis — the caller is responsible for final model selection.

Request Body (JSON)

{
  "task": "text-generation",
  "constraints": {
    "max_vram_gb": 24,
    "license": "commercial"
  },
  "limit": 5
}

Constraints (all optional)

FieldTypeDescription
taskstringTask name or alias ("llm", "code", "embeddings")
max_vram_gbnumberMaximum VRAM in GB
max_params_bnumberMaximum parameters in billions
licensestring"commercial", "apache-2.0", "mit", or "any"
min_context_lengthnumberMinimum context window (tokens)
limitnumberMax results (1-20, default 5)

curl

curl -X POST https://free2aitools.com/api/v1/select \
  -H "Content-Type: application/json" \
  -d '{"task":"text-generation","constraints":{"max_vram_gb":24}}'

Response

{
  "task_interpreted": "text-generation",
  "entries": [
    {
      "rank": 1,
      "model_id": "hf-model--nvidia--gemma-4-31b-it-nvfp4",
      "name": "Gemma-4-31B-IT-NVFP4",
      "fni_score": 49.3,
      "params_billions": 20.87,
      "vram_estimate_gb": 17,
      "fni_factors": {
        "semantic": null,
        "semantic_note": "query-time baseline; scored live at search; not a per-entity value",
        "authority": 0,
        "popularity": 70.5,
        "recency": 98.1,
        "quality": 65
      },
      "fni_summary": "FNI 49.3 catalog entry; leading factor recency (98.1); 21B params."
    }
  ]
}

GET /api/v1/compare

Side-by-side model comparison with FNI factor decomposition.

Parameters

ParamTypeDescription
idsstringComma-separated entity IDs (2-25). Use model_id from the Select API or id from Search.

curl (HF-native id form, internal form, or slug — all accepted)

curl "https://free2aitools.com/api/v1/compare?ids=meta-llama/Llama-3-8B-Instruct,google/gemma-2-27b"

GET /api/v1/entity/:id

Full structured metadata for a single entity. Use this after search to fetch the complete detail you need to make a decision: FNI factors, technical specs, VRAM estimates, license, links, relations.

Accepted id forms

  • HuggingFace-native: meta-llama/Llama-3-8B-Instruct
  • Bare name (auto-prefixes common sources): Llama-3-8B-Instruct
  • Internal canonical: hf-model--meta-llama--Llama-3-8B-Instruct
  • Slug form (from search response): meta-llama--Llama-3-8B-Instruct

Case-insensitive. Lookup probes the matching shards in parallel and returns the first hit.

Query parameters

ParamDefaultDescription
include(empty)Comma list. include=body adds the rendered README (can be up to 250KB). Default response is lean.

Status codes

  • 200 — entity found
  • 404 — no entity matches any candidate form (genuine miss; don't retry)
  • 503 — all probed shards errored (transient infra; retry after a short delay)
  • 400 / 500 — bad request / unexpected server error

curl

curl "https://free2aitools.com/api/v1/entity/meta-llama/Llama-3-8B-Instruct"

Response shape (lean default)

{
  "version": "fni_v2.0",
  "entity": {
    "id": "hf-model--meta-llama--Llama-3-8B-Instruct",
    "slug": "meta-llama--Llama-3-8B-Instruct",
    "type": "model",
    "name": "Llama-3-8B-Instruct",
    "author": "meta-llama",
    "fni": {
      "score": 87.5,
      "factors": {
        "semantic": 92,
        "authority": 95,
        "popularity": 88,
        "recency": 85,
        "quality": 80
      }
    },
    "specs": {
      "params_billions": 8,
      "context_length": 8192,
      "vram": {
        "fp16_gb": 16
      },
      "ollama_compatible": true
    },
    "stats": {
      "downloads": 1234567,
      "last_modified": "..."
    },
    "links": {
      "detail_url": "...",
      "badge_url": "..."
    },
    "relations": {
      "datasets_used": [],
      "related": []
    }
  },
  "meta": {
    "elapsed_ms": 142,
    "candidates_tried": 3
  }
}

Field semantics: 0 means measured-zero, null means not-measured. Treat them differently when scoring downstream.

Rate Limits: Free tier — no authentication required. CDN cached. max 5 results for search, max 20 for select. Machine-readable docs: /llms.txt (plain markdown index per llmstxt.org), /.well-known/mcp.json (MCP manifest with tool catalog).

MCP Server

Free2AI exposes an MCP server so AI agents (Claude, Cursor, Windsurf, etc.) can discover and rank AI tools automatically.

Discovery layer only. The API and MCP server return FNI-ranked catalog data and evidence for the calling agent to reason over. They do not perform compatibility analysis (hardware/framework fields are stored heuristics), do not execute/plan/recommend workflows, do not select or decide on the caller's behalf, and do not currently provide live semantic/ANN ranking.

free2aitools_search

Search and rank AI tools, models, datasets, and papers by FNI score.

free2aitools_rank

Keyword-search AI entities using the task text as query input. Returns FNI-ranked catalog entries. Does not perform task-fit recommendation or compatibility analysis.

free2aitools_explain

Explain why a specific entity received its FNI ranking score with factor breakdown.

free2aitools_select_model

Filter the catalog by declared metadata; returns FNI-ranked entries with an optional per-entry fni_summary (factual FNI factor/spec facts). Constraints are metadata/heuristic filters, not verified compatibility analysis.

free2aitools_compare

Compare 2-25 AI models side-by-side with FNI factor decomposition.

Setup

Claude Desktop / Claude Code

Add to your MCP settings (claude_desktop_config.json or .mcp.json): 

{
  "mcpServers": {
    "free2aitools": {
      "url": "https://free2aitools.com/api/mcp",
      "transport": "streamable-http"
    }
  }
}

Cursor

Go to Settings > MCP Servers > Add Server, enter:

URL: https://free2aitools.com/api/mcp
Transport: Streamable HTTP

Windsurf

Go to Cascade > Plugins > Add MCP Server, enter:

URL: https://free2aitools.com/api/mcp
Transport: Streamable HTTP

Any MCP Client / Auto-Discovery

Endpoint: POST https://free2aitools.com/api/mcp

Protocol: JSON-RPC 2.0 (MCP Spec 2025-03-26). Supports initialize, tools/list, tools/call.

Machine-readable server manifest: https://free2aitools.com/.well-known/mcp.json

FNI Badge

Embed a live FNI score badge in your README, docs, or website. The badge updates automatically as scores change.

Endpoint

GET https://free2aitools.com/api/v1/badge/{umid}

Returns an SVG image. Color-coded: green (90+), blue (70+), yellow (50+), red (<50). Cached 1 hour at CDN edge.

Markdown (README)

![FNI Score](https://free2aitools.com/api/v1/badge/YOUR_UMID)

HTML

<img src="https://free2aitools.com/api/v1/badge/YOUR_UMID" alt="FNI Score" />
Finding your UMID: Search for your model/tool using the API, the id field in the response is your UMID.

Open Data

For bulk access and offline analysis, download FNI rankings as Apache Parquet files. Compatible with DuckDB, Pandas, Spark, and any columnar data tool.

View Open Data Downloads

FNI Score

Every entity is ranked by the Free2AITools Nexus Index (FNI) — a composite score from 0 to 99.9 based on five factors:

FNI = 0.35·S + 0.25·A + 0.15·P + 0.15·R + 0.10·Q
S
Semantic
A
Authority
P
Popularity
R
Recency
Q
Quality
Full methodology and anti-manipulation details →

Build with Free2AI

561,000+ AI entities · FNI-ranked · Updated daily

GitHub FNI Methodology