Create a schedule
curl --request POST \
--url https://agp.eu.hcompany.ai/api/v2/schedules \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"timing": {},
"session_request": {},
"description": "<string>"
}
'import requests
url = "https://agp.eu.hcompany.ai/api/v2/schedules"
payload = {
"name": "<string>",
"timing": {},
"session_request": {},
"description": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: '<string>', timing: {}, session_request: {}, description: '<string>'})
};
fetch('https://agp.eu.hcompany.ai/api/v2/schedules', 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://agp.eu.hcompany.ai/api/v2/schedules",
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([
'name' => '<string>',
'timing' => [
],
'session_request' => [
],
'description' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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://agp.eu.hcompany.ai/api/v2/schedules"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"timing\": {},\n \"session_request\": {},\n \"description\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://agp.eu.hcompany.ai/api/v2/schedules")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"timing\": {},\n \"session_request\": {},\n \"description\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agp.eu.hcompany.ai/api/v2/schedules")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"timing\": {},\n \"session_request\": {},\n \"description\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodySchedules
Create a schedule
Register a cron schedule that starts a session on each fire.
POST
/
api
/
v2
/
schedules
Create a schedule
curl --request POST \
--url https://agp.eu.hcompany.ai/api/v2/schedules \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"timing": {},
"session_request": {},
"description": "<string>"
}
'import requests
url = "https://agp.eu.hcompany.ai/api/v2/schedules"
payload = {
"name": "<string>",
"timing": {},
"session_request": {},
"description": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: '<string>', timing: {}, session_request: {}, description: '<string>'})
};
fetch('https://agp.eu.hcompany.ai/api/v2/schedules', 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://agp.eu.hcompany.ai/api/v2/schedules",
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([
'name' => '<string>',
'timing' => [
],
'session_request' => [
],
'description' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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://agp.eu.hcompany.ai/api/v2/schedules"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"timing\": {},\n \"session_request\": {},\n \"description\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://agp.eu.hcompany.ai/api/v2/schedules")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"timing\": {},\n \"session_request\": {},\n \"description\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agp.eu.hcompany.ai/api/v2/schedules")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"timing\": {},\n \"session_request\": {},\n \"description\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyRegisters a schedule for your organization. The
session_request template is validated and resolved at creation time (the agent must exist), then re-resolved on every fire.
Returns 201 with the created schedule object.
Request body
Display name for the schedule (max 255 characters).
When the schedule fires:
expression(string): Five-field cron expression, e.g."0 9 * * 1-5".timezone(string): IANA timezone the expression is evaluated in, e.g."Europe/Paris".type(string, optional):"cron", the default and only variant today.
Template used to create each scheduled session, in the same shape as the Create session body. Must contain at least one initial message and may not set
parent_session_id. Defaults to max_time_s: 3600 when the template does not set it.Optional description (max 255 characters).
Examples
curl -X POST https://agp.eu.hcompany.ai/api/v2/schedules \
-H "Authorization: Bearer $HAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "morning-market-scan",
"description": "Weekday scan of new Paris listings",
"timing": {"expression": "0 9 * * 1-5", "timezone": "Europe/Paris"},
"session_request": {
"agent": "h/web-surfer-flash",
"messages": [
{"type": "user_message", "message": "Scan new apartment listings in Paris 11e and summarize the top five"}
]
}
}'
from hai_agents import Client
client = Client()
schedule = client.schedules.create_schedule(
name="morning-market-scan",
description="Weekday scan of new Paris listings",
timing={"expression": "0 9 * * 1-5", "timezone": "Europe/Paris"},
session_request={
"agent": "h/web-surfer-flash",
"messages": [
{"type": "user_message", "message": "Scan new apartment listings in Paris 11e and summarize the top five"}
],
},
)
print(schedule.id, schedule.next_run_times[0])
import { HaiAgentsClient } from "hai-agents";
const client = new HaiAgentsClient();
const schedule = await client.schedules.createSchedule({
name: "morning-market-scan",
description: "Weekday scan of new Paris listings",
timing: { expression: "0 9 * * 1-5", timezone: "Europe/Paris" },
sessionRequest: {
agent: "h/web-surfer-flash",
messages: [
{ type: "user_message", message: "Scan new apartment listings in Paris 11e and summarize the top five" },
],
},
});
console.log(schedule.id, schedule.nextRunTimes[0]);
Response
{
"id": "9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f",
"name": "morning-market-scan",
"description": "Weekday scan of new Paris listings",
"timing": {"type": "cron", "expression": "0 9 * * 1-5", "timezone": "Europe/Paris"},
"session_request": {
"agent": "h/web-surfer-flash",
"messages": [
{"type": "user_message", "message": "Scan new apartment listings in Paris 11e and summarize the top five"}
],
"max_time_s": 3600
},
"paused": false,
"pause_note": null,
"next_run_times": [
"2026-07-06T07:00:00Z",
"2026-07-07T07:00:00Z",
"2026-07-08T07:00:00Z",
"2026-07-09T07:00:00Z",
"2026-07-10T07:00:00Z"
],
"last_run_at": null,
"created_at": "2026-07-04T12:00:00Z",
"updated_at": "2026-07-04T12:00:00Z"
}
Errors
| Status | Cause |
|---|---|
400 | Organization schedule limit reached (20), or the expression fires more often than once every 5 minutes. |
404 | The agent referenced by session_request doesn’t exist or isn’t visible to you. |
422 | Body failed validation: invalid cron expression, unknown timezone, template without messages, or template setting parent_session_id. |
Was this page helpful?
⌘I