Automations

Run agents autonomously from cron jobs, webhooks, or internal services using a dedicated system endpoint.

How it works

Create (or pick) an agent in your org
Allow system execution by setting allowedCallers to include system
Trigger runs via POST /api/internal/run-automation using an API key
Use idempotencyKey to make retries safe

API key required

Automations are server-to-server. Do not call this endpoint from the browser. Create org-scoped keys in Organization.

Enable system runs for an agent

bash

# Allow both user + system callers
curl -X PUT "https://dev.usebelha.com/api/agents?id=ag_xxx" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $BELHA_API_KEY" \
  -d '{"allowedCallers":["user","system"]}'

Trigger an automation run

bash

curl -X POST "https://dev.usebelha.com/api/internal/run-automation" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $BELHA_API_KEY" \
  -H "x-trigger-type: schedule" \
  -H "x-automation-id: daily-leads" \
  -d '{
    "target": "ag_xxx",
    "input": { "message": "Run my scheduled workflow." },
    "idempotencyKey": "daily-leads-2025-01-01",
    "ttlOverride": 86400
  }'

Scheduling options

UseBelha stays platform-agnostic: use any scheduler that can run a curl command.

Cron services

cron-job.org, EasyCron, Render/Railway cron, etc.

Webhooks/events

Trigger runs from Stripe, your CRM, internal queues, or CI.

Notes

idempotencyKey returns cached results if the same run is retried.
ttlOverride extends retention for long-running automation sessions.
Rate limits: demo is low; authenticated is higher; automation runs use a higher system: tier.