API Documentation

RESTful API for searching, browsing, and managing CLI tools.

Authentication

Use API keys for programmatic access. Create keys in Settings.

Authorization: Bearer as_your_api_key_here

POST/api/search

Hybrid search using full-text and vector search.

Request Body:

{ "query": "json parser", "category": "data-processing", "limit": 20 }

GET/api/tools?page=1&limit=20&category=search&sort=score

Browse tools with filtering and pagination.

GET/api/tools/:slug

Get detailed information about a specific tool.

GET/api/tools/:slug/install

Get install command and track download.

POST/api/toolsAuth Required

Submit a new CLI tool for review.

Request Body:

{ "name": "mytool", "description": "...", "category": "search", "repo_url": "https://github.com/..." }

POST/api/tools/:slug/upvoteAuth Required

Toggle upvote on a tool.

POST/api/reportAuth Required

Report AI agent tool usage.

Request Body:

{ "slug": "jq", "outcome": "success", "model": "gpt-4", "duration_ms": 1500 }

GET/api/categories

List all categories with tool counts.

GET/api/keysAuth Required

List your API keys.

Code Examples

curl

curl -X POST https://agentshovels.com/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "json parser"}'

JavaScript

const res = await fetch("https://agentshovels.com/api/search", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query: "json parser" })
});
const data = await res.json();

Python

import requests
res = requests.post("https://agentshovels.com/api/search",
    json={"query": "json parser"})
data = res.json()