Skip to main content
POST
/
api
/
v1
/
hooks
Create Hook
curl --request POST \
  --url https://api.example.com/api/v1/hooks \
  --header 'Content-Type: application/json' \
  --data '
{
  "hook_preset_id": "<string>",
  "event_pattern": "<string>",
  "skill_slug": "<string>",
  "cooldown_minutes": 123
}
'
{
  "id": "<string>",
  "event_pattern": "<string>",
  "skill_slug": "<string>",
  "enabled": true,
  "cooldown_minutes": 123
}

​
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

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
  }'

​
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