Automation API - Allternit Docs

Overview

The Automation API surfaces Gizzi Code’s cron/routine/loop runtime through the Allternit platform API. A goal is a platform-owned objective that can own routines (persistent scheduled jobs) and loops (session-scoped recurring jobs). Routines and loops can execute locally or in the cloud via the Gizzi cron daemon.

Base URL

https://api.allternit.com/api/v1/automation

For local development:

http://127.0.0.1:8013/api/v1/automation

Authentication

All automation routes require a valid bearer token. See Authentication.

Data models

Goal

Field	Type	Description
`id`	string	Goal UUID.
`user_id`	string	Owner.
`workspace_id`	string	Optional workspace context.
`agent_id`	string	Optional associated agent.
`title`	string	Goal title.
`description`	string	Optional description.
`status`	string	`active`, `paused`, `completed`, etc.
`priority`	string	`low`, `medium`, `high`, etc.
`target_date`	string	Optional ISO 8601 target date.
`progress`	integer	Progress percentage.
`metadata`	object	Arbitrary metadata.
`created_at`	string	ISO 8601 timestamp.
`updated_at`	string	ISO 8601 timestamp.

Routine

Field	Type	Description
`id`	string	Routine UUID.
`user_id`	string	Owner.
`goal_id`	string	Optional parent goal.
`agent_id`	string	Bot/agent that runs it. Required for `local` routines.
`gizzi_job_id`	string	Daemon job id when cloud scheduled.
`name`	string	Routine name.
`description`	string	Optional description.
`status`	string	`active`, `paused`, etc.
`schedule_type`	string	`cron`, `interval`, `manual`, or `once`.
`schedule_expression`	string	Cron expression or interval shorthand.
`timezone`	string	Optional timezone.
`execution_domain`	string	`local` or `cloud`.
`config`	object	Routine configuration including `jobType`.
`max_runs`	integer	Optional maximum run count.
`timeout_seconds`	integer	Optional per-run timeout.
`max_retries`	integer	Optional retry count.
`metadata`	object	Free-form, plus run bookkeeping the local scheduler maintains (below).
`next_run_at`	string	Local scheduler cursor; `null` when paused, manual, or needing a bot.
`last_run_at`	string	Start of the last run.

The local scheduler keeps these keys in metadata:

Key	Meaning
`lastRunStatus`	`succeeded`, `skipped` (monitor output unchanged) or `failed`.
`lastRunError`	Last failure message; removed by a good run.
`consecutiveFailures`	Failed runs in a row; removed by a good run.
`autoPaused`	`{ at, reason, lastError }` when the routine paused itself after 3 failures in a row.
`needsAgent`	`true` for a local routine with no `agent_id`. It is never run until one is assigned.

Loop

Field	Type	Description
`id`	string	Loop UUID.
`user_id`	string	Owner.
`goal_id`	string	Optional parent goal.
`agent_id`	string	Optional agent to run.
`session_id`	string	Optional associated session.
`gizzi_job_id`	string	Daemon job id when cloud scheduled.
`name`	string	Loop name.
`description`	string	Optional description.
`status`	string	`active`, `paused`, etc.
`schedule_type`	string	`cron`, `interval`, `manual`, or `once`.
`schedule_expression`	string	Cron expression or interval shorthand.
`execution_domain`	string	`local` or `cloud`.
`config`	object	Loop configuration.
`expires_at`	string	Optional ISO 8601 expiry.

Endpoints

Goals

Method	Path	Description
`GET`	`/api/v1/automation/goals`	List goals.
`POST`	`/api/v1/automation/goals`	Create a goal.
`GET`	`/api/v1/automation/goals/:id`	Get a goal.
`PUT`	`/api/v1/automation/goals/:id`	Update a goal.
`DELETE`	`/api/v1/automation/goals/:id`	Delete a goal.
`GET`	`/api/v1/automation/goals/:id/children`	List routines and loops under a goal.

Routines

Method	Path	Description
`GET`	`/api/v1/automation/routines`	List routines.
`POST`	`/api/v1/automation/routines`	Create a routine.
`GET`	`/api/v1/automation/routines/:id`	Get a routine.
`PUT`	`/api/v1/automation/routines/:id`	Update a routine.
`DELETE`	`/api/v1/automation/routines/:id`	Delete a routine.
`POST`	`/api/v1/automation/routines/:id/run`	Trigger a cloud routine immediately.
`GET`	`/api/v1/automation/routines/:id/runs`	List routine runs.
`GET`	`/api/v1/automation/routines/:id/metrics`	Get routine metrics.

Loops

Method	Path	Description
`GET`	`/api/v1/automation/loops`	List loops.
`POST`	`/api/v1/automation/loops`	Create a loop.
`GET`	`/api/v1/automation/loops/:id`	Get a loop.
`PUT`	`/api/v1/automation/loops/:id`	Update a loop.
`DELETE`	`/api/v1/automation/loops/:id`	Delete a loop.
`POST`	`/api/v1/automation/loops/:id/run`	Trigger a cloud loop immediately.

Local scheduler

Method	Path	Description
`GET`	`/api/v1/automation/local-schedules`	List local-domain routines and loops.

Create a goal

POST /api/v1/automation/goals

Request body

Field	Type	Required	Description
`title`	string	Yes	Goal title.
`workspace_id`	string	No	Workspace id.
`agent_id`	string	No	Associated agent id.
`description`	string	No	Description.
`priority`	string	No	Defaults to `medium`.
`target_date`	string	No	ISO 8601 date.
`metadata`	object	No	Arbitrary metadata.

Example request

curl -X POST https://api.allternit.com/api/v1/automation/goals \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Ship Q3 release",
    "description": "Coordinate release tasks",
    "priority": "high",
    "target_date": "2026-09-01"
  }'

Example response

{
  "id": "goal_550e8400",
  "user_id": "user_550e8400",
  "title": "Ship Q3 release",
  "description": "Coordinate release tasks",
  "status": "active",
  "priority": "high",
  "target_date": "2026-09-01",
  "progress": 0,
  "metadata": null,
  "created_at": "2026-08-13T10:00:00Z",
  "updated_at": "2026-08-13T10:00:00Z"
}

Create a routine

POST /api/v1/automation/routines

Request body

Field	Type	Required	Description
`name`	string	Yes	Routine name.
`schedule_type`	string	Yes	`cron`, `interval`, `manual`, or `once`.
`schedule_expression`	string	Yes	Cron expression or interval shorthand (`5m`, `1h`, etc.).
`workspace_id`	string	No	Workspace id.
`agent_id`	string	Local: yes	Bot/agent that runs it. Required when `execution_domain` is `local` (the default); must name an existing agent.
`goal_id`	string	No	Parent goal.
`description`	string	No	Description.
`timezone`	string	No	Timezone.
`execution_domain`	string	No	`local` or `cloud`; defaults to `local`.
`config`	object	No	Routine config; include `jobType` to control daemon job type.
`tags`	string[]	No	Tags.
`metadata`	object	No	Metadata.
`max_runs`	integer	No	Maximum runs.
`timeout_seconds`	integer	No	Timeout.
`max_retries`	integer	No	Retries.

Example request

curl -X POST https://api.allternit.com/api/v1/automation/routines \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily standup summary",
    "schedule_type": "cron",
    "schedule_expression": "0 9 * * *",
    "execution_domain": "cloud",
    "agent_id": "agent_550e8400",
    "config": { "jobType": "agent" }
  }'

Example response

{
  "id": "rtn_550e8400",
  "user_id": "user_550e8400",
  "agent_id": "agent_550e8400",
  "gizzi_job_id": "job_550e8400",
  "name": "Daily standup summary",
  "status": "active",
  "schedule_type": "cron",
  "schedule_expression": "0 9 * * *",
  "execution_domain": "cloud",
  "config": { "jobType": "agent" },
  "created_at": "2026-08-13T10:00:00Z",
  "updated_at": "2026-08-13T10:00:00Z"
}

Routines and bots

A local routine runs as a turn in its bot’s chat, so it must have a bot.

POST /routines without agent_id for a local routine returns 400 with {"error": "agent_required", "message": "..."}. An agent_id that names no agent returns 400 agent_not_found.
Local routines that have no bot (created before this rule) are never run. The scheduler sets metadata.needsAgent = true and clears next_run_at; the Bots UI lists them under Needs a bot.

Assign a routine to a bot

PUT /api/v1/automation/routines/:id
Content-Type: application/json

{ "agent_id": "<bot id>" }

Sets the routine’s bot, removes needsAgent, consecutiveFailures and autoPaused, and resets next_run_at so the scheduler arms the next run from the schedule. Other fields are unchanged. An empty agent_id means no change; a routine cannot be unassigned.

Pause, resume and automatic pause

PUT with {"status": "paused"} pauses a routine; {"status": "active"} resumes it and clears consecutiveFailures and autoPaused, so it gets 3 more tries. After 3 failed runs in a row the scheduler sets status to paused, records metadata.autoPaused, and appends a routine.paused event to the bot’s activity ledger (next to the routine.failed event for each failed run).

Trigger a routine

POST /api/v1/automation/routines/:id/run

Local routines run at once on this API and answer {"status": "running", "routineId": "...", "domain": "local"}; the result lands in the run history and the bot’s chat. A local routine with no bot returns 409 agent_required; one that is already running returns 409 already_running. Cloud routines run through the Gizzi cron daemon.

List routine runs

GET /api/v1/automation/routines/:id/runs

Returns stored runs for the routine, newest first, and for cloud routines attempts to sync the latest history from the Gizzi cron daemon. Local runs carry the thread they wrote to in metadata.sessionId.

Example response

{
  "runs": [
    {
      "id": "run_550e8400",
      "routine_id": "rtn_550e8400",
      "gizzi_run_id": "grun_550e8400",
      "status": "completed",
      "scheduled_at": "2026-08-13T09:00:00Z",
      "started_at": "2026-08-13T09:00:01Z",
      "finished_at": "2026-08-13T09:00:05Z",
      "duration_ms": 4000,
      "output": "Standup summary generated.",
      "error": null,
      "attempt": 1,
      "triggered_by": "schedule"
    }
  ],
  "sync": { "attempted": true, "synced": 1, "error": null }
}

Create a loop

POST /api/v1/automation/loops

Same request shape as a routine, plus an optional session_id and expires_at.

List local schedules

GET /api/v1/automation/local-schedules

Returns all routines and loops whose execution_domain is local.

Example response

{
  "routines": [...],
  "loops": [...]
}

Error codes

Status	Meaning
`200 OK`	Success.
`201 Created`	Resource created.
`204 No Content`	Resource deleted.
`400 Bad Request`	`agent_required` (local routine without a bot) or `agent_not_found`.
`401 Unauthorized`	Missing or invalid bearer token.
`409 Conflict`	Run now on a routine with no bot (`agent_required`) or one already running (`already_running`).
`404 Not Found`	Goal, routine, or loop not found.
`500 Internal Server Error`	Database or daemon error.

​Overview

​Base URL

​Authentication

​Data models

​Goal

​Routine

​Loop

​Endpoints

​Goals

​Routines

​Loops

​Local scheduler

​Create a goal

​Request body

​Example request

​Example response

​Create a routine

​Request body

​Example request

​Example response

​Routines and bots

​Assign a routine to a bot

​Pause, resume and automatic pause

​Trigger a routine

​List routine runs

​Example response

​Create a loop

​List local schedules

​Example response

​Error codes

​Related pages

Overview

Base URL

Authentication

Data models

Goal

Routine

Loop

Endpoints

Goals

Routines

Loops

Local scheduler

Create a goal

Request body

Example request

Example response

Create a routine

Request body

Example request

Example response

Routines and bots

Assign a routine to a bot

Pause, resume and automatic pause

Trigger a routine

List routine runs

Example response

Create a loop

List local schedules

Example response

Error codes

Related pages