# VibeLeaderboard API

> The community-ranked catalog of vibe-coded apps, tools, and agent skills.
> Ask it a use case in plain English ("skills for redesigning a UI") and get
> back the best-matching tools, ranked, with reasoning on why each is good
> and how to use it — instead of trawling GitHub yourself.

## Authentication

Get your API key from your profile page at https://www.vibeleaderboard.ai (sign in, go to your profile, click "Generate API Key").

Include it in every request:
  Authorization: Bearer YOUR_API_KEY

## Base URL

https://www.vibeleaderboard.ai/api/v1

## Machine-Readable Interfaces

- OpenAPI 3.1 spec: https://www.vibeleaderboard.ai/openapi.json
  (also served at /api/openapi.json)
- MCP server (JSON-RPC 2.0 over streamable HTTP):
  POST https://www.vibeleaderboard.ai/api/mcp
  Tools: list_apps, search_apps, get_app, trending, categories
  - search_apps uses the SAME semantic search + hybrid ranking as
    GET /api/v1/apps?search= and returns a `relevance` score per result.
  - GET /api/mcp returns 405 with a JSON usage hint (no SSE stream).
  - Discovery manifest: https://www.vibeleaderboard.ai/.well-known/mcp.json

## Rate Limits

- Public read endpoints (GET /api/v1/apps, /apps/{id}, /top): 120 requests
  per minute per IP. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining,
  and X-RateLimit-Reset (unix seconds) headers.
- Authenticated write endpoints (e.g. PATCH /apps/{id}): 60 requests per
  minute per API key.
- 10 app submissions per day per user.
- Public read endpoints are CORS-open (Access-Control-Allow-Origin: *), so
  browser-based agents can call them directly.

## Endpoints

### List / Search Apps (public, no auth required)

GET /api/v1/apps
GET /api/v1/apps?search=skills+for+redesigning+a+UI
GET /api/v1/apps?search=design+taste&category=Developer+Tools&subcategory=Design+Tools
GET /api/v1/apps?category=Productivity&limit=20&offset=0

Query parameters:
  search      - Natural-language use case. Semantically matched against the
                catalog (embeddings) and ranked by relevance — describe what
                you're trying to do, not just keywords.
  category    - Filter by category (see categories below)
  subcategory - Filter by subcategory (e.g. "Design Tools" under Developer Tools)
  limit       - Results per page, 1-100 (default 50)
  offset      - Pagination offset (default 0)

Each app in the response includes:
  why         - Curated reasoning: why this tool is good / why it matters
  how_to_use  - Summary of how to install and use it
  how_to_install - The literal command to install/run the tool (e.g.
                "npx dmux@latest", "pip install sherlock-project", or an MCP
                JSON config snippet), extracted verbatim from the tool's
                README. null when there is none (hosted SaaS/web apps).
  votes       - Community vote count
  relevance   - Raw semantic match to your query, 0-1 (search results only)
  score       - The blended ranking score that orders search results
                (search results only) — see ranking below
  github_url  - Source repository, when known (string|null)
  pricing     - free / open-source / freemium / paid (string|null)
  platform    - Platforms the tool runs on (string[]|null)
  agent_ready - How an agent can adopt the tool: booleans
                { mcp_server, skill_md, cli, sdk, api }.
                For repo-backed tools, mcp_server / skill_md / cli are
                scanned facts derived from the source repo (MCP SDK
                dependencies, manifests, SKILL.md files, bin/script
                entries) — both true and false are reliable signals,
                not defaults.
  maintained  - Freshness signal (boolean|null): true = the source repo is
                not archived and was pushed within the last 12 months;
                false = archived or no push in 12+ months (likely
                abandonware — prefer a maintained alternative);
                null = unknown (no repo, or activity not yet checked)
  last_commit_at - Last observed push to the source repo (ISO timestamp|null)

Search ranking is hybrid: semantic relevance (0.8) blended with a community
quality prior from votes/GitHub stars (0.2). That blend is the `score` field,
and search results are ordered by it, descending — NOT by raw `relevance`,
so relevance alone may look out of order. Results below 0.40 relevance are
never returned. The raw `relevance` is included so you can judge match
strength yourself.

Without search, results are ordered by community popularity (best first).

Response: { apps: [...], total: number|null, limit, offset,
            has_more: boolean, next_offset: number|null,
            ranking: "semantic"|"keyword"|"popularity" }

Pagination: `has_more` is true when more results exist beyond this page;
`next_offset` is the offset for the next page (null when done, or when the
next page would exceed the offset cap of 500 — narrow the query instead).
`total` is the exact match count on browse/keyword responses and null on
semantic search responses (no cheap exact total on that path — paginate
with has_more/next_offset).

Caching: browse and detail responses are edge-cached for up to 5 minutes.
Search responses are never cached (each one feeds demand analytics), so
search results are always fresh.

### Get Single App (public, no auth required)

GET /api/v1/apps/{id}

Response: the list-item fields above plus:
  description       - Longer description
  creator           - { display_name } of the verified creator, or null
  related_articles  - Intel articles we've written about this tool:
                      [{ id, title, url }] — url is the reading page on
                      vibeleaderboard.ai. Always present; [] when none.
  covered_tools     - Only on article-type entries: the tools the article
                      covers, [{ id, title, url }].

If {id} is the id of an Intel article (e.g. taken from related_articles),
the response is the article: { id, title, headline, url, type: "article",
covered_tools: [{ id, title, url }] }.

### Listing Badge (public, no auth required)

GET /api/v1/apps/{id}/badge

Returns shields.io endpoint-badge JSON for a listed app:
  { schemaVersion: 1, label: "VibeLeaderboard", message: "Featured · <Category>", color, cacheSeconds }

Embed it in a README via shields.io (URL-encode the badge endpoint):
  [![VibeLeaderboard](https://img.shields.io/endpoint?url=https%3A%2F%2Fwww.vibeleaderboard.ai%2Fapi%2Fv1%2Fapps%2F{id}%2Fbadge)](https://www.vibeleaderboard.ai/app/{id})

Unknown ids still return 200 (shields convention) with message "not listed"
and isError: true. A copyable snippet is shown on each app's detail page.

### Submit an App (auth required)

POST /api/v1/apps
Content-Type: application/json

Required fields:
  title        - App name (string)
  url          - App URL, e.g. "https://myapp.com" (string)
  description  - Short description, max 200 chars (string)
  category     - Must be one of the categories below (string)

Optional fields:
  is_creator   - Are you the creator? (boolean, default true)
  github_url   - Source code URL (string)
  license      - "MIT", "Apache-2.0", "GPL-3.0", or "BSD-3-Clause" (string)

Example:
  curl -X POST https://www.vibeleaderboard.ai/api/v1/apps \
    -H "Authorization: Bearer vl_sk_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{"title":"My App","url":"https://myapp.com","description":"A cool vibe-coded app","category":"Productivity"}'

Response: 201 with the created app object.

Errors:
  400 - Missing or invalid fields
  409 - Domain already submitted (returns app_id and app_title of existing entry)
  429 - Rate limit or daily submission limit reached

### Edit a Listing (auth required)

PATCH /api/v1/apps/{id}
Content-Type: application/json

Who can edit:
  - The original sharer can edit title, description, and category — until the creator claims it.
  - The verified creator can edit title, description, category, github_url, and license.
  - Category changes are limited to once every 90 days.
  - URL/domain can never be changed.

Example:
  curl -X PATCH https://www.vibeleaderboard.ai/api/v1/apps/{id} \
    -H "Authorization: Bearer vl_sk_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{"title":"Better Title","description":"Updated description"}'

### Start Verification (auth required)

POST /api/v1/apps/{id}/verify
Content-Type: application/json

Body:
  method - "meta_tag" or "dns_txt"

Response: { request_id, code, method, instructions }

The instructions tell you exactly what to add to your site or DNS. For meta_tag, add a <meta> tag to your HTML <head>. For dns_txt, add a TXT record to your domain.

### Complete Verification (auth required)

PUT /api/v1/apps/{id}/verify
Content-Type: application/json

Body:
  request_id - The ID from the POST response above

This checks that the verification code is present on the site/domain. Codes expire after 24 hours.

Response: { verified: true }

### Get My Info (auth required)

GET /api/v1/me

Returns your user profile, your apps, and API key info.

## Categories

Valid category values:
  - AI Agents (subcategories: Platforms, Skills, Plugins, Orchestration, Frameworks, Coding Agents, Research Agents, Task Agents)
  - AI Tools (Voice & Audio, Image & Vision, LLM Infrastructure)
  - Crypto (Trading Tools, Wallets & Infra)
  - Cybersecurity (OSINT, Vulnerability Scanning, Network Security, Threat Intelligence, Privacy Tools)
  - Productivity (Writing & Docs, Automation, Knowledge & Search)
  - Developer Tools (Skills & Plugins, Libraries, Frameworks, CLI Tools, Platforms, Design Tools)
  - Finance (Personal Finance, Crypto & DeFi)
  - Health & Fitness (Fitness, Wellness)
  - Education (Coding Education, Reference)
  - Entertainment (Games, Media & Exploration)
  - Social (Content Creation, Community)
  - Lifestyle (Travel & Outdoors, Home & Personal)
  - Other (Miscellaneous)

## Error Format

All errors return: { "error": "Human-readable message" }

Public API errors also carry a `hint` field pointing back at this document.
Unknown /api/v1 paths return a JSON 404 and wrong HTTP methods return a JSON
405 (with an Allow header) — you always get a machine-readable body.

Some errors include additional fields:
  - 409 (domain exists): { error, app_id, app_title }
  - 429 (rate limit): { error, retry_after_seconds }
  - 429 (category cooldown): { error, next_change_allowed }
  - 400 (invalid category): { error, valid_categories }
  - 400 (invalid subcategory): { error, valid_subcategories }

## Privacy

Search queries are logged (query text, result stats, user agent) to improve catalog coverage. No other personal data is stored.