API Reference — AgentRank

Try it now

Run live requests against the API. No key required for free-tier endpoints.

GET https://agentrank-ai.com/api/v1/search?q=database&limit=5

Response

Free (v1) No API key required — 100 req/min per IP

GET /api/v1/search

Search across tools, skills, and agents. Returns ranked results sorted by score.

Query Parameters

Parameter Type Default Description

q string "" Search query. Empty returns top-ranked results.

category string "all" Filter by type: tool, skill, agent, or omit for all.

sort string "score" Sort order: score, rank, stars, freshness.

limit integer 20 Results per page. Max 100.

offset integer 0 Pagination offset.

Example

curl

curl "https://agentrank-ai.com/api/v1/search?q=database&category=tool&limit=5"

Python

import httpx

resp = httpx.get(
    "https://agentrank-ai.com/api/v1/search",
    params={"q": "database", "category": "tool", "limit": 5},
)
data = resp.json()
for item in data["results"]:
    print(item["name"], item["score"])

TypeScript

const params = new URLSearchParams({ q: "database", category: "tool", limit: "5" });
const res = await fetch("https://agentrank-ai.com/api/v1/search?" + params);
const data = await res.json();
for (const item of data.results) {
  console.log(item.name, item.score);
}

Response

JSON

{
  "query": "database",
  "category": "tool",
  "sort": "score",
  "results": [
    {
      "type": "tool",
      "id": "owner--repo",
      "name": "owner/repo",
      "description": "A database MCP server",
      "score": 82.5,
      "rank": 14,
      "url": "https://agentrank-ai.com/tool/owner--repo/",
      "raw": {
        "stars": 1240,
        "contributors": 8,
        "dependents": 23,
        "lastCommitAt": "2026-03-10T00:00:00Z",
        "language": "TypeScript",
        "license": "MIT",
        "isArchived": false,
        "topics": ["mcp", "database", "sqlite"]
      }
    }
  ],
  "meta": { "total": 87, "limit": 5, "offset": 0 }
}

GET /api/v1/tool/{id}

Get full detail for a single tool, skill, or agent. Includes score, rank, and signal breakdown.

Path Parameters

Parameter Type Description

id string GitHub owner--repo (use -- in place of /). Also accepts skill slugs.

Example

curl

curl "https://agentrank-ai.com/api/v1/tool/modelcontextprotocol--servers"

Python

import httpx

tool_id = "modelcontextprotocol--servers"  # owner--repo
resp = httpx.get(f"https://agentrank-ai.com/api/v1/tool/{tool_id}")
tool = resp.json()
print(tool["name"], "score:", tool["score"])

TypeScript

const toolId = "modelcontextprotocol--servers"; // owner--repo
const res = await fetch("https://agentrank-ai.com/api/v1/tool/" + toolId);
const tool = await res.json();
console.log(tool.name, "score:", tool.score);

Response

JSON

{
  "type": "tool",
  "id": "modelcontextprotocol--servers",
  "name": "modelcontextprotocol/servers",
  "description": "Model Context Protocol servers",
  "score": 97.4,
  "rank": 1,
  "githubUrl": "https://github.com/modelcontextprotocol/servers",
  "signals": {
    "stars": 1.0,
    "freshness": 0.98,
    "issueHealth": 0.82,
    "contributors": 1.0,
    "dependents": 1.0,
    "descriptionQuality": 0.9,
    "licenseHealth": 1.0
  },
  "weights": {
    "stars": 0.15,
    "freshness": 0.25,
    "issueHealth": 0.20,
    "contributors": 0.10,
    "dependents": 0.25,
    "descriptionQuality": 0.03,
    "licenseHealth": 0.02
  },
  "raw": { ... }
}

Returns 404 if the tool is not in the index.

GET /api/v1/movers

Returns tools with the largest rank changes over a lookback window. Useful for "biggest movers" content.

Query Parameters

Parameter Type Default Description

days integer 7 Lookback window in days. Max 30.

limit integer 10 Number of results. Max 50.

type string "tool" Filter by type: tool, skill, or omit for all.

Example

curl

curl "https://agentrank-ai.com/api/v1/movers?days=7&limit=10"

Response

JSON

{
  "movers": [
    {
      "full_name": "owner/repo",
      "tool_type": "tool",
      "current_rank": 12,
      "prev_rank": 31,
      "rank_delta": 19,
      "current_score": 78.3,
      "stars": 842,
      "url": "https://agentrank-ai.com/tool/owner--repo/"
    }
  ],
  "meta": {
    "today": "2026-03-18",
    "prev_date": "2026-03-11",
    "days": 7,
    "count": 10
  }
}

GET /api/v1/new-tools

Returns tools newly added to the index within the last N days.

Query Parameters

Parameter Type Default Description

days integer 7 Lookback window in days. Max 30.

limit integer 20 Number of results. Max 100.

type string "tool" Filter by type: tool, skill, or omit for all.

Example

curl

curl "https://agentrank-ai.com/api/v1/new-tools?days=14&limit=20"

Response

JSON

{
  "tools": [
    {
      "full_name": "owner/new-tool",
      "tool_type": "tool",
      "rank": 284,
      "score": 41.2,
      "stars": 87,
      "first_seen": "2026-03-15",
      "url": "https://agentrank-ai.com/tool/owner--new-tool/"
    }
  ],
  "meta": {
    "today": "2026-03-18",
    "cutoff": "2026-03-04",
    "days": 14,
    "count": 18
  }
}

GET /api/v1/stats

Returns aggregate counts and averages for the entire index. Useful for dashboards, status pages, or displaying live stats. No parameters required. Response is cached for 1 hour.

Example

curl

curl "https://agentrank-ai.com/api/v1/stats"

Response

JSON

{
  "totalTools": 25843,
  "totalSkills": 1204,
  "toolsUpdatedWeek": 3741,
  "averageScore": 38.2,
  "totalCategories": 42,
  "totalApiRequestsServed": null,
  "totalSkillInstalls": null,
  "generatedAt": "2026-03-19T08:00:00.000Z"
}

Cached for 1 hour (Cache-Control: public, s-maxage=3600). totalApiRequestsServed and totalSkillInstalls are null, meaning those runtime counters are unavailable from the generated static snapshot. Snapshot freshness is unavailable in the current data format. generatedAt is the response generation time, not the snapshot generation time or data freshness.

Pro (v2) Requires API key — 10,000 req/day — Get a key

All v2 endpoints require an API key in the Authorization header:

HTTP

Authorization: Bearer ark_pro_your_key_here

GET /api/v2/search Pro

Same as v1 search, but with an additional history parameter and tier metadata in responses.

Additional Parameters

Parameter Type Default Description

history string 0 Set to 1 to include 30-day rank history for each result.

All v1 search parameters (q, category, sort, limit, offset) are also supported.

Example

curl

curl -H "Authorization: Bearer ark_pro_your_key" \
  "https://agentrank-ai.com/api/v2/search?q=filesystem&history=1"

GET /api/v2/tool/{id} Pro

Same as v1 tool detail, but includes rankHistory — a 30-day array of {date, rank, score} entries.

Example

curl

curl -H "Authorization: Bearer ark_pro_your_key" \
  "https://agentrank-ai.com/api/v2/tool/modelcontextprotocol--servers"

Additional Response Field

JSON

{
  // ... all v1 fields ...
  "rankHistory": [
    { "date": "2026-03-18", "rank": 1,  "score": 97.4 },
    { "date": "2026-03-17", "rank": 1,  "score": 97.2 },
    { "date": "2026-03-16", "rank": 2,  "score": 96.8 }
    // up to 30 entries
  ]
}

POST /api/v2/batch Pro

Resolve up to 50 tool IDs in a single request. Returns a map of id → tool | null. Null means the tool is not in the index.

Request Body

Field Type Description

ids string[] Array of tool IDs in owner--repo format. Max 50.

Example

curl

curl -X POST \
  -H "Authorization: Bearer ark_pro_your_key" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["modelcontextprotocol--servers", "owner--repo2"]}' \
  "https://agentrank-ai.com/api/v2/batch"

Response

JSON

{
  "results": {
    "modelcontextprotocol--servers": {
      "type": "tool",
      "id": "modelcontextprotocol--servers",
      "score": 97.4,
      "rank": 1
      // ... full tool detail
    },
    "owner--repo2": null
  }
}

Returns 403 for free-tier keys. Pro and Enterprise only.

Error responses

All errors return a JSON body with an error field:

JSON

{ "error": "Tool not found: owner--bad-repo" }

Status Meaning

400Bad request (invalid parameter)

401Missing or invalid API key

403Insufficient tier for this endpoint

404Tool not found in index

429Rate limit exceeded

500Internal server error

Get an API key

The free tier works without a key — 100 requests/min per IP. For Pro access (10,000 req/day, rank history, batch endpoint), connect with GitHub to generate your developer key.

Keys look like: ark_pro_a1b2c3d4e5f6...

Get your developer key →