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
  }
}

POST /api/v1/select

Agent model selection — find the best model for a task with hardware and license constraints.

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",
  "recommendations": [
    {
      "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": 50,
        "authority": 0,
        "popularity": 70.5,
        "recency": 98.1,
        "quality": 65
      },
      "rationale": "#1 for text-generation: strong recency, fits 24GB VRAM"
    }
  ]
}

GET /api/v1/compare

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

Parameters

ParamTypeDescription
idsstringComma-separated entity IDs (2-10). 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.

free2aitools_search

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

free2aitools_rank

Rank AI tools by FNI score for a given task context. Ideal for AI agents selecting the best tool.

free2aitools_explain

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

free2aitools_select_model

Select the best model for a task with hardware/license constraints. Returns ranked recommendations with rationale.

free2aitools_compare

Compare 2-10 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

Hundreds of thousands of AI entities · FNI-ranked · Updated daily

GitHub FNI Methodology