Skip to main content
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.

​
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 everything 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 agent 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 INTENT_REQUIRED error. 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

TierPer hourPer day
Anonymous (no API key)5—
Registered (free)50500
Anonymous requests are rate-limited by IP. Registered requests are rate-limited by user account. The response includes an X-Rate-Limit-Remaining header so your agent can pace itself.

​
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’re designed for exploration, not agent runtime calls.

​
What about hosted execution?

Currently, agents call the upstream sites directly using the URLs from the catalog response. Hermai is not in the request path. Hosted execution — where Hermai proxies the request through its own infrastructure with anti-bot bypass, residential proxies, and session management — is coming in a future phase. Join the waitlist to express interest and help us model pricing.