SDK Reference — AgentRank

Installation

npm

npm install @agentrank/sdk

pnpm

pnpm add @agentrank/sdk

yarn

yarn add @agentrank/sdk

Requires TypeScript 4.5+ or any modern JavaScript runtime with fetch support.

Constructor

new AgentRank(options?: AgentRankOptions)

Options

Option Type Default Description

apiKey string? undefined Pro API key. Omit for free-tier (v1) access.

baseUrl string? "https://agentrank-ai.com" Override the API base URL. Useful for local dev.

Examples

import { AgentRank } from '@agentrank/sdk';

// Free tier (no key)
const ar = new AgentRank();

// Pro tier
const ar = new AgentRank({ apiKey: process.env.AGENTRANK_API_KEY });

// Custom base URL
const ar = new AgentRank({ baseUrl: 'http://localhost:4321' });

When apiKey is provided, the SDK automatically routes all requests to /api/v2/*. Without a key, it uses /api/v1/*.

`ar.search(query, options?)`

Search the index for tools, skills, and agents. Returns ranked results.

search(query: string, options?: SearchOptions): Promise<SearchResponse>

Parameters

Param Type Description

query string Search query. Pass empty string for top-ranked results.

options.category Category? "all" | "tool" | "skill" | "agent"

options.sort SortBy? "score" | "rank" | "stars" | "freshness"

options.limit number? Max results to return. Default 20, max 100.

options.offset number? Pagination offset. Default 0.

Example

const res = await ar.search('filesystem', {
  category: 'tool',
  sort: 'score',
  limit: 10,
});

for (const result of res.results) {
  console.log(result.name, result.score, result.rank);
}

// Pagination
const page2 = await ar.search('filesystem', { limit: 10, offset: 10 });

`ar.getTool(id)`

Get full detail for one tool, including score, rank, and signal breakdown. Pass the GitHub owner/repo — the SDK handles URL encoding.

getTool(id: string): Promise<ToolDetail>

Parameters

Param Type Description

id string GitHub owner/repo format. The SDK converts / to -- automatically.

Example

const tool = await ar.getTool('modelcontextprotocol/servers');

console.log(tool.score);   // 97.4
console.log(tool.rank);    // 1
console.log(tool.signals); // { stars, freshness, issueHealth, ... }

// With Pro key: includes rankHistory
if (tool.rankHistory) {
  const trend = tool.rankHistory.slice(0, 7);
  console.log('7-day rank trend:', trend.map(h => h.rank));
}

Throws NotFoundError if the tool is not in the index.

`ar.getMovers(options?)`

Get tools with the largest rank changes over a recent window.

getMovers(options?: MoversOptions): Promise<MoversResponse>

Parameters

Param Type Description

options.days number? Lookback window in days. Default 7, max 30.

options.limit number? Number of results. Default 10, max 50.

Example

const { movers, meta } = await ar.getMovers({ days: 7, limit: 10 });

movers.forEach(m => {
  const dir = m.rankDelta > 0 ? 'up' : 'down';
  console.log(`${m.fullName} moved ${dir} ${Math.abs(m.rankDelta)} spots`);
});

`ar.getNewTools(options?)`

Get tools that appeared in the index for the first time within the last N days.

getNewTools(options?: NewToolsOptions): Promise<NewToolsResponse>

Parameters

Param Type Description

options.days number? Lookback window in days. Default 7, max 30.

options.limit number? Number of results. Default 20, max 100.

Example

const { tools } = await ar.getNewTools({ days: 7 });

tools.forEach(t => {
  console.log(`${t.fullName} — first indexed ${t.firstSeen} — rank ${t.rank}`);
});

Error handling

The SDK exports typed error classes. Catch them to handle specific failure modes:

import { AgentRank, NotFoundError, RateLimitError, AuthError } from '@agentrank/sdk';

try {
  const tool = await ar.getTool('owner/does-not-exist');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Tool not in index');
  } else if (err instanceof RateLimitError) {
    // err.retryAfter is an ISO timestamp or undefined
    console.log('Rate limited. Retry after:', err.retryAfter);
  } else if (err instanceof AuthError) {
    console.log('Invalid API key');
  }
}

Class HTTP Status Description

AgentRankError Any Base class for all SDK errors. Has status and code fields.

AuthError 401 Invalid or missing API key.

NotFoundError 404 Tool not found in the index.

RateLimitError 429 Rate limit hit. Has optional retryAfter string.

Type reference

The SDK exports all types used in request and response objects. Import as needed:

import type {
  AgentRankOptions,
  SearchOptions,
  SearchResponse,
  SearchResult,
  ToolDetail,
  ToolSignals,
  RankHistoryEntry,
  MoversOptions,
  MoversResponse,
  Mover,
  NewToolsOptions,
  NewToolsResponse,
  NewTool,
  Category,
  SortBy,
  ResultType,
} from '@agentrank/sdk';