Skip to main content
POST
Create Hook

Request

hook_preset_id
string
ID of a built-in hook preset (e.g., share.accepted.welcome, task.overdue.summary). Mutually exclusive with event_pattern.
event_pattern
string
Custom event pattern to match. Supports exact match (share.accepted), glob wildcards (order.*.completed), prefix match (share), or catch-all (*). Mutually exclusive with hook_preset_id.
skill_slug
string
required
Slug of the skill to execute when the hook fires.
cooldown_minutes
number
Minimum time between firings in minutes (1–1440). A server-side default is applied when omitted.

Response

id
string
The hook’s unique UUID.
event_pattern
string
The resolved event pattern (from preset or custom).
skill_slug
string
The target skill slug.
enabled
boolean
Always true on creation.
cooldown_minutes
number
Cooldown period between firings.

Authentication

Requires an API key with completions scope.

Example

Guard Rails

  • Pre-flight credit check before each autonomous execution
  • Separate daily cap for autonomous actions
  • Per-run caps on tool invocations and total spend
  • Hooks auto-pause after repeated failures
  • Cooldown enforced between firings