Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agentvolumes.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

The search endpoint lets you discover volumes in a bibliotheca’s catalog by freeform text, component type, runtime compatibility, provider, keyword, or publisher. It returns a paginated list of matching volumes. No authentication is required.

​
Endpoint

GET /api/v1/search

​
Query parameters

​
q
string
Freeform query text. Matches against volume names, descriptions, keywords, and other catalog metadata. Ranking and text relevance are bibliotheca-local.
​
type
string
Filter by component type. One of: agent, skill, command, tool, hook, mcp-server, lsp-server.
​
runtime
string
Filter by runtime compatibility metadata. Matches volumes that declare compatibility with the given runtime identifier (e.g., claude-code, cursor, opencode). Bibliothecas evaluate this filter only for runtime version schemes they understand.
​
provider
string
Filter by provider declaration. Matches volumes that declare integration with the given provider (e.g., github, slack, postgres).
​
keyword
string
Filter by keyword. Matches volumes that include the given keyword in their volume.toml keyword list.
​
publisher
string
Filter by publisher identifier or scope.
​
limit
integer
default:"20"
Maximum number of results per page. Range: 1–100.
​
offset
integer
default:"0"
Zero-based pagination offset. Use in combination with limit to page through results.

​
Example requests

GET /api/v1/search?q=github&type=tool&runtime=claude-code&limit=20

GET /api/v1/search?provider=postgres&keyword=migration&limit=10&offset=20

GET /api/v1/search?type=mcp-server&publisher=acme

​
Example response

{
  "items": [
    {
      "name": "github-toolkit",
      "latestVersion": "2.1.0",
      "description": "GitHub integration tools for agent runtimes",
      "role": "provider",
      "providers": ["github"],
      "components": [
        {
          "type": "tool",
          "name": "read-pr"
        },
        {
          "type": "tool",
          "name": "comment-pr"
        }
      ]
    },
    {
      "name": "@acme/github-provider",
      "latestVersion": "3.0.1",
      "description": "GitHub provider package for ACME runtimes",
      "role": "provider",
      "providers": ["github"],
      "components": [
        {
          "type": "tool",
          "name": "read-pr"
        },
        {
          "type": "hook",
          "name": "issue-event"
        }
      ]
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

​
Response fields

​
items
object[]
required
Matching catalog entries. Each item contains name and latestVersion, with optional discovery metadata such as description, role, providers, and components.
​
total
integer
required
Total number of matching entries for the query.
​
limit
integer
required
Page size applied to this response.
​
offset
integer
required
Zero-based offset applied to this response.

​
Pagination

Use limit and offset together to page through results: 
GET /api/v1/search?q=research&limit=10&offset=0   # page 1
GET /api/v1/search?q=research&limit=10&offset=10  # page 2
GET /api/v1/search?q=research&limit=10&offset=20  # page 3
Search result ordering and ranking are bibliotheca-local. There is no guaranteed stable global ordering across bibliothecas unless a specific bibliotheca documents one.

​
Important limitations

Do not use search results as inputs to dependency resolution. Search results are discovery aids, not resolver inputs. Always use the version index for candidate selection and the fetch endpoint for authoritative release metadata before installation or trust evaluation.
  • Search results are not resolver inputs. Never substitute a search response for a version index or exact release metadata during resolution.
  • Ordering and ranking are bibliotheca-local. The same query may return results in different orders on different bibliothecas.
  • Runtime and protocol compatibility filters are discovery aids only. Bibliothecas evaluate these filters only for version schemes they understand and must not claim portable compatibility rejection for unknown schemes.
  • Search responses may be cached under ordinary HTTP semantics, but cached results do not guarantee freshness.