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

# Quickstart

> 註冊、取得 API key,並在兩分鐘內執行第一次 hosted fetch。

## 1. 註冊

到 [hermai.ai/register](https://hermai.ai/register) 建立免費帳號。Registry 可以免費瀏覽。

## 2. 建立 API key

進入 **Dashboard > API Keys** 並建立新的 key。建立後複製一次。需要驗證的請求會用到。

```
hm_sk_abc123...
```

部分 registry 瀏覽請求可以匿名使用,但 hosted fetch 需要 API key。

## 3. 執行 hosted fetch

透過 Hermai 呼叫一個已註冊端點:

```bash theme={null}
export HERMAI_API_KEY="hm_sk_abc123..."

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,referenceCount,citationCount,openAccessPdf"
    }
  }'
```

回應:

```json theme={null}
{
  "success": true,
  "data": {
    "paperId": "204e3073870fae3d05bcbc2f6a8e263d9b72e776",
    "title": "Attention is All you Need",
    "year": 2017
  },
  "meta": {
    "site": "semanticscholar.org",
    "endpoint": "get_paper",
    "method": "GET",
    "source": "gateway",
    "latency_ms": 1234,
    "credits_used": 1,
    "credits_remaining": 999,
    "cached": false
  }
}
```

## 4. 瀏覽可用 schema

在 [hermai.ai/schemas](https://hermai.ai/schemas) 瀏覽,或透過 API:

```bash theme={null}
# 列出所有 schema
curl "https://api.hermai.ai/v1/schemas"

# 取得一個公開 schema 卡片
curl "https://api.hermai.ai/v1/schemas/semanticscholar.org"
```

公開 schema 卡片會顯示網站、描述、端點名稱、method、purpose,以及面向使用者的 readiness 訊號。

## 5. 拉取 package 或自行執行

如果希望自己的 agent 或伺服器直接執行請求,可以帶 intent 拉取 catalog 或完整 package:

```bash theme={null}
curl -H "Authorization: Bearer ${HERMAI_API_KEY}" \
     -H "X-Hermai-Intent: looking up product endpoints on allbirds.com to build a price comparison agent" \
     "https://api.hermai.ai/v1/catalog/allbirds.com"

curl -H "Authorization: Bearer ${HERMAI_API_KEY}" \
     -H "X-Hermai-Intent: downloading Semantic Scholar metadata routes for citation enrichment" \
     "https://api.hermai.ai/v1/schemas/semanticscholar.org/package"
```

Catalog 和 package 路由會回傳端點 recipe。`POST /v1/fetch` 會透過 Hermai 執行已註冊端點。

## 6. 貢獻 schema

發現缺少的網站?用 CLI 記錄其端點並推送 schema:

```bash theme={null}
# 安裝 CLI
go install github.com/hermai-ai/hermai-cli/cmd/hermai@latest

# 分類網站並找出公開路徑
hermai detect https://example.com
hermai wellknown example.com

# 從詳細頁面擷取內嵌資料
hermai probe --body https://example.com/products/123 | hermai extract

# 捕獲動態頁面的 XHR 流量(搜尋、購物車等)
hermai intercept https://example.com/search?q=test

# 撰寫 schema.json(參見 /zh-Hant/concepts/schemas),然後推送
hermai registry push schema.json
```

<Tip>
  **使用 Claude Code、Codex 或 Cursor?** 執行 `npx skills add hermai-ai/hermai-skills`,你的 agent 就會代替你完成探索與推送。詳情參見 [hermai-skills repo](https://github.com/hermai-ai/hermai-skills)。
</Tip>

每貢獻一個網站可獲得 **+50 credits**。Credits 會顯示在 dashboard 中,並可在支援 hosted execution 的地方使用。

## 下一步

* [Hermai 如何運作](/zh-Hant/concepts/how-hermai-works): 執行模型
* [Hosted fetch](/zh-Hant/concepts/hosted-fetch): 透過 Hermai 執行已註冊端點
* [Schemas](/zh-Hant/concepts/schemas): 格式、認證、貢獻方式
* [Catalog](/zh-Hant/concepts/catalog): 查詢 API 細節
* [API keys](/zh-Hant/concepts/api-keys): 範圍與速率限制