Create Hook

POST

api

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

import requests

url = "https://api.example.com/api/v1/hooks"

payload = {
    "hook_preset_id": "<string>",
    "event_pattern": "<string>",
    "skill_slug": "<string>",
    "cooldown_minutes": 123
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    hook_preset_id: '<string>',
    event_pattern: '<string>',
    skill_slug: '<string>',
    cooldown_minutes: 123
  })
};

fetch('https://api.example.com/api/v1/hooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/hooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'hook_preset_id' => '<string>',
    'event_pattern' => '<string>',
    'skill_slug' => '<string>',
    'cooldown_minutes' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/hooks"

	payload := strings.NewReader("{\n  \"hook_preset_id\": \"<string>\",\n  \"event_pattern\": \"<string>\",\n  \"skill_slug\": \"<string>\",\n  \"cooldown_minutes\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/hooks")
  .header("Content-Type", "application/json")
  .body("{\n  \"hook_preset_id\": \"<string>\",\n  \"event_pattern\": \"<string>\",\n  \"skill_slug\": \"<string>\",\n  \"cooldown_minutes\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/hooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"hook_preset_id\": \"<string>\",\n  \"event_pattern\": \"<string>\",\n  \"skill_slug\": \"<string>\",\n  \"cooldown_minutes\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "event_pattern": "<string>",
  "skill_slug": "<string>",
  "enabled": true,
  "cooldown_minutes": 123
}

Request

string

ID of a built-in hook preset (e.g., share.accepted.welcome, task.overdue.summary). Mutually exclusive with 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.

string

required

Slug of the skill to execute when the hook fires.

number

Minimum time between firings in minutes (1–1440). A server-side default is applied when omitted.

Response

string

The hook’s unique UUID.

string

The resolved event pattern (from preset or custom).

string

The target skill slug.

boolean

Always true on creation.

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

const hook = await theo.createHook({
  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

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

import requests

url = "https://api.example.com/api/v1/hooks"

payload = {
    "hook_preset_id": "<string>",
    "event_pattern": "<string>",
    "skill_slug": "<string>",
    "cooldown_minutes": 123
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    hook_preset_id: '<string>',
    event_pattern: '<string>',
    skill_slug: '<string>',
    cooldown_minutes: 123
  })
};

fetch('https://api.example.com/api/v1/hooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/hooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'hook_preset_id' => '<string>',
    'event_pattern' => '<string>',
    'skill_slug' => '<string>',
    'cooldown_minutes' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/hooks"

	payload := strings.NewReader("{\n  \"hook_preset_id\": \"<string>\",\n  \"event_pattern\": \"<string>\",\n  \"skill_slug\": \"<string>\",\n  \"cooldown_minutes\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/hooks")
  .header("Content-Type", "application/json")
  .body("{\n  \"hook_preset_id\": \"<string>\",\n  \"event_pattern\": \"<string>\",\n  \"skill_slug\": \"<string>\",\n  \"cooldown_minutes\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/hooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"hook_preset_id\": \"<string>\",\n  \"event_pattern\": \"<string>\",\n  \"skill_slug\": \"<string>\",\n  \"cooldown_minutes\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "event_pattern": "<string>",
  "skill_slug": "<string>",
  "enabled": true,
  "cooldown_minutes": 123
}

Overview

Completions

Media Generation

Audio

Skills API

E.V.I. Canvas

Workflows

Hooks

Settings

Embed Widgets

Guardrails

Routing Studio

Theo Browser

Benchmarks

Webhooks

Billing

Resources

Request

Response

Authentication

Example

Guard Rails

​Request

​Response

​Authentication

​Example

​Guard Rails

Request

Response

Authentication

Example

Guard Rails