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

# 創建 Hook

> 安裝一個自主 Hook，當匹配的事件發生時觸發技能執行。

## 請求

<ParamField body="hook_preset_id" type="string" optional>
  內置 Hook 預設的 ID（例如 `share.accepted.welcome`、`task.overdue.summary`）。與 `event_pattern` 互斥。
</ParamField>

<ParamField body="event_pattern" type="string" optional>
  要匹配的自定義事件模式。支持精確匹配（`share.accepted`）、通配符（`order.*.completed`）、前綴匹配（`share`）或全匹配（`*`）。與 `hook_preset_id` 互斥。
</ParamField>

<ParamField body="skill_slug" type="string" required>
  Hook 觸發時要執行的技能 slug。
</ParamField>

<ParamField body="cooldown_minutes" type="number" optional>
  兩次觸發之間的最短間隔時間（分鐘，1–1440）。省略時將應用服務端默認值。
</ParamField>

## 響應

<ResponseField name="id" type="string">
  該 Hook 的唯一 UUID。
</ResponseField>

<ResponseField name="event_pattern" type="string">
  解析後的事件模式（來自預設或自定義）。
</ResponseField>

<ResponseField name="skill_slug" type="string">
  目標技能 slug。
</ResponseField>

<ResponseField name="enabled" type="boolean">
  創建時始終為 `true`。
</ResponseField>

<ResponseField name="cooldown_minutes" type="number">
  兩次觸發之間的冷卻週期。
</ResponseField>

## 身份驗證

需要具有 `completions` 權限範圍的 API 密鑰。

## 示例

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hitheo.ai/api/v1/hooks \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "event_pattern": "order.*.completed",
      "skill_slug": "order-processor",
      "cooldown_minutes": 5
    }'
  ```

  ```typescript SDK theme={null}
  const hook = await theo.createHook({
    event_pattern: "order.*.completed",
    skill_slug: "order-processor",
    cooldown_minutes: 5,
  });
  ```
</CodeGroup>

## 護欄

* 每次自主執行前進行預檢信用額度檢查
* 自主操作單獨設有每日上限
* 對工具調用次數和總支出設有單次運行上限
* Hook 在連續失敗後會自動暫停
* 強制執行兩次觸發之間的冷卻時間


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.