API Documentation - AiPicks | Developer Guide & API Reference

Overview

The AiPicks API gives you programmatic access to AI tool verdicts, scores, search, comparison data, and leaderboard rankings. It is a RESTful HTTP API that returns JSON.

REST · JSON

Standard HTTP verbs. All responses are JSON with a consistent envelope.

p99 < 80ms

Fast, globally distributed. Rate limits are generous on every tier.

No sponsored data

Scores and verdicts cannot be purchased. The data is editorially independent.

Base URL

https://api.aipicks.org/v1

Available resources

Resource	Path	Description
Tools	`/v1/tools`	List, get, search, and compare AI tools
Leaderboard	`/v1/leaderboard`	Weekly ranked list by combined AI + community score
Categories	`/v1/categories`	Available tool categories with stats

Quickstart

Make your first request in under 2 minutes. No SDK needed.

Get a free API key

Create an account and generate a key from your dashboard. Free keys include 1,000 requests/month.

Make your first request

Pass your key as a Bearer token in the Authorization header.

Parse the response

All responses follow a standard envelope with data and meta fields.

Your first request

cURL

curl class="t-string">"https://api.aipicks.org/v1/tools?category=code&limit=5" \
  -H class="t-string">"Authorization: Bearer YOUR_API_KEY"

JavaScript

const res = await fetch(
  class="t-string">"https://api.aipicks.org/v1/tools?category=code&limit=5",
  { headers: { Authorization: class="t-string">"Bearer YOUR_API_KEY" } }
);
const { data, meta } = await res.json();
console.log(data); class=class="t-string">"t-comment">// array of tool objects

JSON

{
  class="t-string">"data": [
    { class="t-string">"id": class="t-string">"cursor-pro", class="t-string">"name": class="t-string">"Cursor Pro", class="t-string">"ai_score": 97 }
  ],
  class="t-string">"meta": { class="t-string">"total": 148, class="t-string">"limit": 5, class="t-string">"cursor": class="t-string">"eyJpZCI6..." }
}

Authentication

All API requests must include a valid API key in the Authorization header using the Bearer scheme.

Request header

HTTP

Authorization: Bearer YOUR_API_KEY

Keep keys secret

Never expose API keys in client-side code, public repos, or browser console output. Use environment variables and server-side proxies for production integrations.

Key scopes

Scope	Access	Plan
`read:tools`	Read tool data, scores, tags	Free
`read:verdicts`	Full verdict text and dimensions	Builder+
`read:community`	Community votes and ratings	Builder+
`webhooks`	Subscribe to verdict update webhooks	Scale

Revoking keys

Keys can be revoked instantly from the Maker Dashboard under Settings → API Keys. Revoked keys return 401 Unauthorized immediately.

Playground

Try requests directly without writing any code. All responses here are mocked — no real requests are made, and no API key is required.

API Playground

Interactive

No real requests are made — responses are mocked

Endpoint

API Key

Request URL

https://api.aipicks.org/v1/tools?category=code&limit=5

Parameters

category=code

limit=5

Response

Hit "Run request" to see the response

Pagination

List endpoints use cursor-based pagination. The response includes a meta.cursor string that you pass as the cursor query parameter to get the next page.

Fetching the next page

JavaScript

class=class="t-string">"t-comment">// First page
const first = await fetch(class="t-string">"/v1/tools?limit=20", { headers });
const { data, meta } = await first.json();

class=class="t-string">"t-comment">// Next page — pass the cursor from the first response
const next = await fetch(
  `/v1/tools?limit=20&cursor=${meta.cursor}`,
  { headers }
);

Pagination parameters

Parameter	Type	Required	Description
`limit`	integer	Optional	Results per page. Min 1, max 100, default 20.
`cursor`	string	Optional	Opaque cursor from the previous page's meta.cursor field.

Cursor expiry

Cursors expire after 10 minutes. For long-running exports, use the bulk export endpoint available on Scale plans.

Rate limits

Limits are enforced per API key per minute. Exceeding a limit returns 429 Too Many Requests with a Retry-After header indicating seconds until the window resets.

Tier	Requests / min	Requests / month	Concurrent
Free	`10`	`1,000`	`2`
Builder	`60`	`50,000`	`10`
Scale	`300`	`Unlimited`	`50`

Rate limit headers

Response headers on every request

HTTP

X-RateLimit-Limit:     60
X-RateLimit-Remaining: 47
X-RateLimit-Reset:     1713700800
Retry-After:           32   class=class="t-string">"t-comment"># only present on 429

Errors

All errors follow a consistent JSON envelope. HTTP status codes are standard. The error.code field is a machine-readable string you can use in application logic.

Error response envelope

JSON

{
  class="t-string">"error": {
    class="t-string">"code": class="t-string">"RATE_LIMIT_EXCEEDED",
    class="t-string">"message": class="t-string">"Rate limit of 60 req/min exceeded.",
    class="t-string">"docs": class="t-string">"https://docs.aipicks.org/errors/rate-limit"
  },
  class="t-string">"status": 429
}

Error codes reference

HTTP	Code	Meaning
`400`	`INVALID_PARAM`	A required parameter is missing or has an invalid value
`401`	`INVALID_API_KEY`	The API key is missing, malformed, or revoked
`403`	`INSUFFICIENT_SCOPE`	Your key doesn't have the required scope for this endpoint
`404`	`TOOL_NOT_FOUND`	The requested tool ID does not exist in the directory
`422`	`COMPARE_LIMIT`	You requested more than 4 tools in a compare call
`429`	`RATE_LIMIT_EXCEEDED`	Request rate exceeded. Check Retry-After header
`500`	`INTERNAL_ERROR`	Unexpected server error. These are monitored automatically

Versioning

The API version is included in the base URL path (/v1/). We follow semantic versioning principles — breaking changes are always in a new major version. The current version is v1.

Deprecation policy

We give at least 6 months notice before deprecating a version, communicated via email, the changelog, and a deprecation header on every request once the clock starts.

List tools

GET/tools

Returns a paginated list of all tools, with optional filters. Results are sorted by AI score descending by default.

Query parameters

Parameter	Type	Required	Description
`category`	string	Optional	Filter by category slug. See /categories for valid values.
`pricing`	string	Optional	free \| freemium \| paid
`min_score`	integer	Optional	Minimum AI Score (0–100). E.g. min_score=90 returns only top tools.
`sort`	string	Optional	score \| votes \| created_at · Default: score
`limit`	integer	Optional	Results per page. Max 100, default 20.
`cursor`	string	Optional	Pagination cursor from previous response.

cURL

curl class="t-string">"https://api.aipicks.org/v1/tools?category=image&min_score=90&limit=10" \
  -H class="t-string">"Authorization: Bearer YOUR_API_KEY"

JSON

{
  class="t-string">"data": [
    {
      class="t-string">"id": class="t-string">"midjourney-v7",
      class="t-string">"name": class="t-string">"Midjourney v7",
      class="t-string">"maker": class="t-string">"Midjourney",
      class="t-string">"ai_score": 96,
      class="t-string">"category": class="t-string">"image",
      class="t-string">"pricing": class="t-string">"paid",
      class="t-string">"tagline": class="t-string">"Create stunning images with the world's best AI",
      class="t-string">"votes": 5910,
      class="t-string">"created_at": class="t-string">"2025-09-12T00:00:00Z"
    }
  ],
  class="t-string">"meta": { class="t-string">"total": 38, class="t-string">"limit": 10, class="t-string">"cursor": class="t-string">"eyJpZCI6ImRhbGxlLTMifQ==" }
}

Get a tool

GET/tools/:id

Returns full details for a single tool by its slug ID. Use the include parameter to request optional related data.

Path parameters

Parameter	Type	Required	Description
`:id`	string	Required	The tool slug (e.g. cursor-pro, midjourney-v7). Get slugs from the list endpoint.

Query parameters

Parameter	Type	Required	Description
`include`	string	Optional	Comma-separated includes: verdict, dimensions, community_stats, tags

cURL

curl class="t-string">"https://api.aipicks.org/v1/tools/cursor-pro?include=verdict,dimensions" \
  -H class="t-string">"Authorization: Bearer YOUR_API_KEY"

Verdict text and dimension scores require a Builder plan or higher. Free tier returns only basic tool metadata.

JSON

{
  class="t-string">"id": class="t-string">"cursor-pro",
  class="t-string">"name": class="t-string">"Cursor Pro",
  class="t-string">"maker": class="t-string">"Anysphere",
  class="t-string">"ai_score": 97,
  class="t-string">"category": class="t-string">"code",
  class="t-string">"pricing": class="t-string">"paid",
  class="t-string">"start_price": class="t-string">"$20/mo",
  class="t-string">"tagline": class="t-string">"The AI-native IDE that writes code alongside you",
  class="t-string">"verdict": {
    class="t-string">"summary": class="t-string">"Non-negotiable for professional developers in 2026.",
    class="t-string">"tested_hours": 36,
    class="t-string">"updated_at": class="t-string">"2026-04-21T08:00:00Z"
  },
  class="t-string">"dimensions": {
    class="t-string">"capability": 98,
    class="t-string">"description": 95,
    class="t-string">"media": 92,
    class="t-string">"category_fit": 97,
    class="t-string">"verifiability": 94
  },
  class="t-string">"community": { class="t-string">"votes": 6102, class="t-string">"rating": 4.8, class="t-string">"rating_count": 1240 }
}

Search tools

GET/tools/search

Full-text search across tool names, descriptions, and tags. Results include a relevance_score from 0 to 1.

Parameter	Type	Required	Description
`q`	string	Required	Search query. Minimum 2 characters.
`category`	string	Optional	Narrow to a specific category.
`limit`	integer	Optional	Max results. Default 10, max 50.

cURL

curl class="t-string">"https://api.aipicks.org/v1/tools/search?q=voice+synthesis&limit=5" \
  -H class="t-string">"Authorization: Bearer YOUR_API_KEY"

JSON

{
  class="t-string">"query": class="t-string">"voice synthesis",
  class="t-string">"results": [
    { class="t-string">"id": class="t-string">"elevenlabs-v3", class="t-string">"name": class="t-string">"ElevenLabs v3", class="t-string">"ai_score": 93, class="t-string">"relevance_score": 0.97 },
    { class="t-string">"id": class="t-string">"play-ht",       class="t-string">"name": class="t-string">"Play.ht",        class="t-string">"ai_score": 82, class="t-string">"relevance_score": 0.88 }
  ],
  class="t-string">"total": 14
}

Compare tools

GET/tools/compare

Side-by-side comparison of 2 to 4 tools. Returns dimension breakdowns for each tool aligned on the same axes.

Parameter	Type	Required	Description
`ids`	string	Required	Comma-separated tool slugs. Min 2, max 4. e.g. cursor-pro,copilot-x

Comparing more than 4 tools in a single request returns 422 COMPARE_LIMIT.

cURL

curl class="t-string">"https://api.aipicks.org/v1/tools/compare?ids=cursor-pro,copilot-x,windsurf" \
  -H class="t-string">"Authorization: Bearer YOUR_API_KEY"

JSON

{
  class="t-string">"tools": [
    { class="t-string">"id": class="t-string">"cursor-pro", class="t-string">"ai_score": 97, class="t-string">"winner": true  },
    { class="t-string">"id": class="t-string">"copilot-x",  class="t-string">"ai_score": 90, class="t-string">"winner": false },
    { class="t-string">"id": class="t-string">"windsurf",   class="t-string">"ai_score": 88, class="t-string">"winner": false }
  ],
  class="t-string">"dimensions_comparison": {
    class="t-string">"capability":    { class="t-string">"cursor-pro": 98, class="t-string">"copilot-x": 88, class="t-string">"windsurf": 87 },
    class="t-string">"category_fit":  { class="t-string">"cursor-pro": 97, class="t-string">"copilot-x": 95, class="t-string">"windsurf": 92 },
    class="t-string">"verifiability": { class="t-string">"cursor-pro": 94, class="t-string">"copilot-x": 91, class="t-string">"windsurf": 90 }
  },
  class="t-string">"winner": class="t-string">"cursor-pro"
}

Get leaderboard

GET/leaderboard

Parameter	Type	Required	Description
`period`	string	Optional	week \| month \| all_time · Default: week
`category`	string	Optional	Filter to a single category.
`limit`	integer	Optional	Max 50, default 10.

cURL

curl class="t-string">"https://api.aipicks.org/v1/leaderboard?period=week&category=code&limit=5" \
  -H class="t-string">"Authorization: Bearer YOUR_API_KEY"

JSON

{
  class="t-string">"period": class="t-string">"week",
  class="t-string">"category": class="t-string">"code",
  class="t-string">"ranked_at": class="t-string">"2026-04-21T00:00:00Z",
  class="t-string">"tools": [
    { class="t-string">"rank": 1, class="t-string">"prev_rank": 1, class="t-string">"id": class="t-string">"cursor-pro",  class="t-string">"ai_score": 97, class="t-string">"weekly_votes": 890 },
    { class="t-string">"rank": 2, class="t-string">"prev_rank": 2, class="t-string">"id": class="t-string">"copilot-x",   class="t-string">"ai_score": 90, class="t-string">"weekly_votes": 460 }
  ]
}

List categories

GET/categories

Returns all available categories with tool counts and average scores.

cURL

curl class="t-string">"https://api.aipicks.org/v1/categories" \
  -H class="t-string">"Authorization: Bearer YOUR_API_KEY"

JSON

{
  class="t-string">"categories": [
    { class="t-string">"id": class="t-string">"code",  class="t-string">"label": class="t-string">"Code & Dev",      class="t-string">"tool_count": 148, class="t-string">"avg_score": 87, class="t-string">"top_tool": class="t-string">"cursor-pro"    },
    { class="t-string">"id": class="t-string">"image", class="t-string">"label": class="t-string">"Image Generation", class="t-string">"tool_count": 94,  class="t-string">"avg_score": 84, class="t-string">"top_tool": class="t-string">"midjourney-v7" },
    { class="t-string">"id": class="t-string">"video", class="t-string">"label": class="t-string">"Video",            class="t-string">"tool_count": 34,  class="t-string">"avg_score": 81, class="t-string">"top_tool": class="t-string">"sora-2"       }
  ]
}

Webhooks overview

Webhooks let you receive real-time notifications when a tool's verdict is updated, a new tool is added, or a tool's score changes significantly. Available on Scale plans.

Scale plan only

Webhooks require an active Scale plan. Each key can register up to 10 webhook endpoints.

Registering an endpoint

cURL

curl -X POST class="t-string">"https://api.aipicks.org/v1/webhooks" \
  -H class="t-string">"Authorization: Bearer YOUR_API_KEY" \
  -H class="t-string">"Content-Type: application/json" \
  -d class="t-string">'{ class="t-string">"url": class="t-string">"https://yourapp.com/hooks/aipicks", class="t-string">"events": [class="t-string">"verdict.updated",class="t-string">"tool.created"] }'

Verifying payloads

Every webhook delivery includes an X-AiPicks-Signature header. Verify it against the HMAC-SHA256 of the raw request body using your webhook secret.

webhook-verify.js

JavaScript

import crypto from class="t-string">"crypto";

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac(class="t-string">"sha256", secret)
    .update(rawBody)
    .digest(class="t-string">"hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

Event types

Event	When it fires
`verdict.updated`	AI verdict text or score updated for an existing tool
`tool.created`	New tool added to the directory and verdict published
`score.changed`	AI score changes by ≥5 points in a single update
`tool.deleted`	Tool removed from the directory

Example webhook payload

JSON

{
  class="t-string">"event": class="t-string">"verdict.updated",
  class="t-string">"timestamp": class="t-string">"2026-04-21T10:30:00Z",
  class="t-string">"tool": {
    class="t-string">"id": class="t-string">"elevenlabs-v3",
    class="t-string">"name": class="t-string">"ElevenLabs v3",
    class="t-string">"previous_score": 91,
    class="t-string">"current_score": 93,
    class="t-string">"change": 2
  }
}

SDKs

No official SDK exists yet. All endpoints are plain REST — any HTTP client works. Community SDKs are listed below.

Official SDK in progress

An official Node.js/TypeScript SDK is in development. Subscribe to the changelog to be notified when it ships.

JavaScript / TypeScript

Official — in progress

Shell

npm install @aipicks/sdk  class=class="t-string">"t-comment"># coming soon

Python

Community — maintained

Shell

pip install aipicks-python

Community — maintained

Shell

go get github.com/community/aipicks-go

Changelog

April 21, 2026

v1.4.0

Latest

Added include=community_stats to /tools/:id
compare endpoint now returns a winner field
Rate limit headers added to all responses

March 15, 2026

v1.3.0

Webhooks launched for Scale plan customers
score.changed event type added
Improved p99 latency from 120ms to 34ms

January 8, 2026

v1.2.0

New /leaderboard endpoint with period filtering
cursor-based pagination replacing offset/page
Added min_score filter to list endpoint