API docs

Add plugin search to your app. Get ranked results with descriptions, repository links, and install commands.

Get an API key

DM me on X for an API key and tell me what you are building.

Save it as PLUGINS_API_KEY in your server environment. Make requests from your backend to keep the key private.

Search

GET https://plugins.sh/api/v1/search

curl --get 'https://plugins.sh/api/v1/search' \
  --data-urlencode 'q=code review' \
  --data 'limit=5' \
  --header "Authorization: Bearer $PLUGINS_API_KEY"

Or use JavaScript on your server:

const url = new URL("https://plugins.sh/api/v1/search");
url.searchParams.set("q", "code review");
url.searchParams.set("limit", "5");

const response = await fetch(url, {
  headers: {
    Authorization: `Bearer ${process.env.PLUGINS_API_KEY}`,
  },
});

if (!response.ok) throw new Error(`Search failed: ${response.status}`);
const { data: plugins, total } = await response.json();

Parameters

Parameter	Description
`q`	Search query, up to 240 characters. Omit to browse.
`limit`	Results per request, from 1 to 100. Default: 24.
`offset`	Results to skip, from 0 to 10,000. Default: 0.
`sort`	`relevance` (default), `newest`, or `stars`.
`verified`	`true` or `false`. Omit for both.

Results

The JSON response includes data, an array of plugins, and total, the result count. Each plugin has a slug, displayName, description, repositoryUrl, and installTargets.

Display the results in your app. Increase offset by limit for the next page.

Limits and errors

Each key allows 120 requests per minute per API instance. A 400 response means invalid parameters; 401 means a missing or invalid key. For 429, wait for the seconds specified in the retry-after header.