Skip to main content
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>"
}
'
Registers 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

​
name
string
required
Display name for the schedule (max 255 characters).
​
timing
object
required
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.
The expression may not fire more often than once every 5 minutes.
​
session_request
object
required
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.
​
description
string
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"}
      ]
    }
  }'
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

StatusCause
400Organization schedule limit reached (20), or the expression fires more often than once every 5 minutes.
404The agent referenced by session_request doesn’t exist or isn’t visible to you.
422Body failed validation: invalid cron expression, unknown timezone, template without messages, or template setting parent_session_id.