Catalog - Hermai

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 when you want Hermai to execute a registered endpoint for you.

Basic usage

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:

{
  "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:

# 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:

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 for the full plan table.

Browsing the registry

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

# 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:

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.

​Basic usage

​Intent

​Intent taxonomy

​Rate limits

​Browsing the registry

​What about hosted execution?