> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hermai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Catalog

> The lookup API that agents call at runtime to get endpoints for any domain.

The catalog is the agent-facing lookup endpoint. Give it a domain, get back every callable endpoint and action that the community has discovered for that site.

Use the catalog when you want endpoint recipes. Use [hosted fetch](/concepts/hosted-fetch) when you want Hermai to execute a registered endpoint for you.

## Basic usage

```bash theme={null}
curl -H "Authorization: Bearer hm_sk_..." \
     -H "X-Hermai-Intent: comparing prices on allbirds.com for a shopping agent" \
     "https://api.hermai.ai/v1/catalog/allbirds.com"
```

Response:

```json theme={null}
{
  "domain": "allbirds.com",
  "session_id": "abc123...",
  "endpoints": [
    {
      "name": "shopify_products",
      "method": "GET",
      "url": "https://www.allbirds.com/products.json",
      "description": "Shopify store product catalog",
      "params": []
    },
    {
      "name": "add_to_cart",
      "method": "POST",
      "url": "https://www.allbirds.com/cart/add.js",
      "headers": { "Content-Type": "application/json" },
      "kind": "api_call",
      "description": "Add a product variant to the cart",
      "params": [
        { "name": "id", "source": "body", "required": true },
        { "name": "quantity", "source": "body", "required": true }
      ]
    }
  ]
}
```

Each endpoint includes what your agent needs to construct a valid HTTP request: URL template, method, headers, and parameters.

## Intent

Every catalog request must include an **intent**: a natural-language description of why your caller needs this schema. Pass it as a query parameter or header:

```bash theme={null}
# Query parameter
GET /v1/catalog/allbirds.com?intent=looking+up+product+prices+for+a+comparison+agent

# Header (better for long intents)
X-Hermai-Intent: looking up product prices for a comparison agent
```

**Requirements**: at least 20 characters, at least 5 distinct words. Requests without a valid intent get a `400` error (`INTENT_REQUIRED`, `INTENT_TOO_SHORT`, or `INTENT_TOO_FEW_WORDS`).

**Why we require it**: intent data drives which schemas we prioritize for verification, helps match agents to the right endpoints, and acts as a lightweight anti-spam gate.

## Intent taxonomy

Every schema in the registry declares an `intent_category` from a fixed taxonomy. The full tree is available at:

```bash theme={null}
curl "https://api.hermai.ai/v1/categories"
```

Top-level categories include: `commerce`, `travel`, `jobs`, `social`, `media`, `reference`, and more. Each has sub-categories (e.g. `commerce` → `product-detail`, `product-search`, `reviews`).

## Rate limits

| Tier                   | Per hour | Per day |
| ---------------------- | -------- | ------- |
| Anonymous (no API key) | 5        | None    |
| Registered (free)      | 1,000    | 1,000   |
| Starter                | 3,000    | 15,000  |
| Pro                    | 5,000    | 60,000  |

Anonymous requests are rate-limited by IP. Registered requests are rate-limited by user account or workspace. Free accounts also have a 20 requests/minute burst cap (60 on Starter, 100 on Pro). Exceeding a limit returns `429 Too Many Requests`. See [credits and usage](/concepts/credits-and-usage) for the full plan table.

## Browsing the registry

Beyond the catalog lookup, you can browse the full registry:

```bash theme={null}
# List all schemas (paginated)
GET /v1/schemas

# Filter by category
GET /v1/schemas?category=commerce

# Search by site name
GET /v1/schemas?q=shopify

# Sort by trending or recently verified
GET /v1/schemas?sort=trending

# Only verified schemas
GET /v1/schemas?verified=true

# Get a specific site's latest schema card
GET /v1/schemas/allbirds.com

# Version history
GET /v1/schemas/allbirds.com/versions
```

These browse endpoints do **not** require an intent. They are designed for exploration, not runtime calls.

## What about hosted execution?

Hosted execution is available through `POST /v1/fetch`. Instead of calling the upstream site yourself, pass the registered `site`, `endpoint`, and `params` to Hermai:

```bash theme={null}
curl -sS -X POST "https://api.hermai.ai/v1/fetch" \
  -H "Authorization: Bearer ${HERMAI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "site": "semanticscholar.org",
    "endpoint": "get_paper",
    "params": {
      "paper_id": "ARXIV:1706.03762",
      "fields": "paperId,externalIds,title,authors,venue,year"
    }
  }'
```

The catalog gives you the recipe. Hosted fetch runs the registered endpoint and returns the result.