ToolXiv
Sign in
All docs

API Guide

How to use the ToolXiv REST API

Authentication

Read endpoints (search, get tool, trending, citations, user profiles) work without authentication. Anonymous access is rate-limited to 100 requests/day.

For higher rate limits and write access, generate an API key from your dashboard and include it in the Authorization header:

Authorization: Bearer txv_your_key_here

Rate Limits

| Tier | Daily Limit | Burst Limit | Access | |------|-------------|-------------|--------| | Anonymous | 100/day | 10/min | Read endpoints only | | Authenticated | 1,000/day | None | All endpoints |

Anonymous requests require a User-Agent header. Requests without one receive a 403 response.

Rate limit headers are included in every response:

  • X-RateLimit-Limit — Daily limit
  • X-RateLimit-Remaining — Remaining requests
  • X-RateLimit-Reset — Unix timestamp when the limit resets

Endpoints

Search Tools

GET /api/v1/search?q=text+generation&categories=ai-ml&language=Python&sort=relevance&page=1

Parameters:

  • q — Search query (optional)
  • categories — Comma-separated category slugs
  • language — Filter by programming language
  • license — Filter by license
  • agent — Filter by AI agent (e.g. "claude-code", "cursor")
  • sort — relevance, newest, stars, or impact
  • page — Page number (default: 1)

Anonymous requests are limited to 2 simultaneous filters, 100-character queries, and pages 1–5.

Get Tool

GET /api/v1/tools/:id

Returns full tool details including metadata, stats, and tags.

Get Citations

GET /api/v1/tools/:id/citations

Returns incoming and outgoing citations for a tool.

Create Tool

POST /api/v1/tools
Content-Type: application/json
Authorization: Bearer txv_your_key_here

Submit a new tool programmatically. Requires authentication. The tool will go through the same review process.

Get User Profile

GET /api/v1/users/:username

Returns user profile, stats, and submitted tools.

Get Trending

GET /api/v1/trending?limit=10

Returns currently trending tools based on 7-day page views.

Error Responses

All errors follow this format:

{
  "error": "Description of what went wrong"
}

Common status codes:

  • 400 — Invalid request parameters
  • 401 — Invalid API key (only when a key is provided but incorrect)
  • 403 — Missing User-Agent header
  • 429 — Rate limit exceeded
  • 404 — Resource not found

MCP Integration

For AI agent integration, use the @toolxiv/mcp package instead of calling the REST API directly. See the MCP Server Guide for setup instructions.

PreviousCitation GuideNext Creator Profiles