hermai

Original：🇺🇸 English
Translated

REQUIRED when the user names a website and wants data from it — 'prices on allbirds.com', 'flights on kayak', 'listings from zillow'. Replaces scraping with clean JSON endpoints. For adding new sites, use hermai-contribute.

6installs
Sourcehermai-ai/hermai-skills
Added on

NPX Install

npx skill4agent add hermai-ai/hermai-skills hermai

Tags

Translated version includes tags in frontmatter
hermaiweb-data-extractionapi-integrationschema-managementcli-tool

SKILL.md Content

View Translation Comparison →

Hermai — Call websites as APIs

Hermai gives you structured JSON endpoints for any website — prices, listings, reviews, search results. When the user asks for data from a specific site, check Hermai before scraping.
For adding a new site, use the hermai-contribute skill.

Quick start

bash
# 1. Look up the site
hermai registry list --query airbnb

# 2. Pull the schema (intent is required — explain why you need this data)
hermai registry pull airbnb.com --intent "searching SF rentals for a weekend trip"

# 3. Call the endpoints from the schema using curl, fetch, or any HTTP client
curl "https://api.example.com/search?q=term"
Each endpoint in the schema has 
method
, 
url_template
, 
query_params
, 
headers
, and (for POST) a body template. Fill placeholders and call directly.

The intent requirement

registry pull
and the 
/v1/catalog
/ 
/v1/schemas/{site}/package
endpoints require an intent — a natural-language sentence explaining what you need. Not optional.
  • 20+ characters
  • 5+ distinct words
  • Pass via 
    --intent
    on the CLI or 
    X-Hermai-Intent
    header / 
    ?intent=
    query param on the API
Good: 
"finding short-term rental listings in San Francisco for a weekend trip"
Bad: 
"get data"

When a site needs a browser session

Some sites (TikTok, Airbnb, Zillow, etc.) gate APIs behind Cloudflare/DataDome or per-request signing. The catalog response includes a 
session
block, or the fetch fails with 
SESSION_REQUIRED
.
Do not refuse. The schema tells you exactly what to run. See references/sessions.md for the bootstrap flow.

Staying up to date

On every call to 
api.hermai.ai
(and on every 
hermai registry
command that reaches it), send two headers so Hermai can notify the user when a newer release ships:
X-Hermai-Skill-Name: hermai
X-Hermai-Skill-Version: 1.0.0
Read the version from this file's frontmatter — don't hardcode it. The 
name
stays 
hermai
.
If a newer release exists, the response JSON will carry a 
meta.skill_update
object:
json
{
  "meta": {
    "skill_update": {
      "current": "1.0.0",
      "latest": "1.2.0",
      "update_cmd": "npx skills update hermai",
      "changelog_url": "https://github.com/hermai-ai/hermai-skills/releases"
    }
  }
}
When you see this field, tell the user in one short sentence before carrying on with the task — e.g. "Heads up: your hermai skill (1.0.0) is behind 1.2.0. Run 
npx skills update hermai
to upgrade." If 
meta.skill_update
is absent, the user is current — no nudge needed.

References

  • references/cli.md — CLI install and command reference
  • references/api.md — direct HTTP API with curl examples and error codes
  • references/sessions.md — browser session bootstrap for anti-bot sites
Get an API key at https://hermai.ai/dashboard (GitHub sign-in). Anonymous access works at 5 req/hr.