codai docs
API referenceGateway

Scheduler

Scheduled agent tasks, terminal commands, webhooks and chains that run on any of your PCs, phones, watch or cloud VMs — cron or plain words, approvals, retries, failover and live run status.

The codai Scheduler runs work on a timetable across every device you own. The cloud owns each schedule and decides when a run is due; your hosts (the desktop app, codaid on servers and VMs, the phone) claim runs, execute them and report back. One list, one history and the same approvals on the hub, desktop, phone and watch.

What can run

  • agent — a codai agent task (prompt, optional skill, permissions read / edit / pr).
  • shell — a terminal command on a host (command, cwd, env_names, shell). Secret values never leave the host: the schedule only names the variables.
  • http — an HTTPS webhook (method, url, headers, body, expect_status).
  • chain — run other schedules in order (steps, stop_on_failure).
  • phone_action — notify, start an agent, open an app, toggle Wi-Fi or Do Not Disturb on one phone.

When

trigger is a cron expression with a time zone (5 or 6 fields, vixie-cron day semantics), a one-off at, an interval, a trigger event, or after another schedule (on success, failure or always). POST /v1/schedules/preview turns plain words in English or Romanian ("every weekday at 9", "în fiecare zi la 3") into cron and returns the next five runs plus a daylight-saving warning when a run falls in a clock-change window. Missed runs (host asleep, outage) follow misfire: skip, once (default) or all_within the misfire_window_min.

Where

target picks a single host, any host with all the given tags, any online host, the codai cloud, or a cloud_vm of a project. A cloud_vm run (shell or http) goes to the daemon of one of your codai cloud environments in that project; when none is online, the scheduler starts the most recently used stopped environment (one hour of wallet balance required) and the environment's idle timeout stops it again after the run. failover lists tag sets to try when the target is offline. A host claims a run with a 60-second lease (POST /v1/scheduler/claim, FOR UPDATE SKIP LOCKED, so two hosts never take the same run), keeps it alive with heartbeats and reports a result. An expired lease becomes a new attempt that another host can pick up. With native: true and a single-host target the desktop app also mirrors the schedule into the operating system's scheduler (Task Scheduler, launchd or systemd timers) so it fires even when codai is not running.

Safety

  • Shell commands need the host's approval. A shell schedule stores the sha256 of shell, cwd, command, env names. Each host shows you the exact command once and approves that hash (POST /v1/schedules/{id}/approve-command); any edit changes the hash and clears every approval.
  • Approvals per run. policy.approval = always or outside_hours (with quiet_hours) puts runs in awaiting_approval; you get a notification on every device, including the watch, and approve or skip from any of them.
  • Limits. policy.max_runs_per_hour, budgets per run and per day (micro-USD), overlap (skip, queue, kill), timeout_s and retries with retry_backoff_s.
  • Alerts. Failures (alert_on_fail) and runs nobody started within late_after_s send a notification with a deep link to the run.

Pause, skip days and noise control

  • Vacation mode. POST /v1/schedules/pause (optionally until) stops creating runs for all your schedules; POST /v1/schedules/resume ends it, and backfill: true gives each schedule that missed slots exactly one catch-up run.
  • Skip days. policy.skip_days skips Romanian public holidays (holidays: 'RO', including Orthodox Easter and Pentecost), chosen weekdays or exact dates, in the trigger's time zone. Skipped slots are never created.
  • Budgets and auto-pause. When today's runs reach policy.budget_micro_usd_per_day new runs are skipped with one alert per day. After policy.pause_after_failures consecutive failures (default 3) the schedule disables itself and tells you.
  • Notify. notify = on_failure (default), on_change (only when the normalised output differs from the last success: timestamps and ids are ignored), always or never.
  • Templates. GET /v1/schedules/templates lists ready-made schedules such as the weekly transcripts digest (summary, decisions, action items, emailed to you every Friday at 17:00).

Heartbeat monitors

For jobs codai does not run (a crontab on a VM, a CI job, a Cloud Scheduler job), create a monitor with POST /v1/heartbeats { name, period_s, grace_s }. The response contains ping_url once. The job calls it:

  • GET|POST /ping/<token> on success, /ping/<token>/start when it starts, /ping/<token>/fail on failure, or /ping/<token>/<exit code>.

No success within period_s + grace_s (or a start without a success within the grace) marks the monitor down and alerts every device once; the next success marks it up and tells you it recovered.

# crontab: back up, then report the exit code
0 3 * * * /srv/backup.sh; curl -fsS -m 10 https://ai.codai.ro/ping/<token>/$?
POST
/v1/schedules/pause

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json
  1. body
until?string
Formatdate-time
resume_policy?string
Value in"skip""backfill"

Response Body

OK.

application/json
  1. response
[key: string]?any
Example Request
curl -X POST 'https://ai.codai.ro/v1/schedules/pause' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{}
POST
/v1/schedules/resume

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json
  1. body
backfill?boolean

Response Body

OK.

application/json
  1. response
[key: string]?any
Example Request
curl -X POST 'https://ai.codai.ro/v1/schedules/resume' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{}
GET
/v1/schedules/templates

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

OK.

application/json
  1. response
[key: string]?any
Example Request
curl -X GET 'https://ai.codai.ro/v1/schedules/templates'
Example Response
{}
POST
/v1/schedules/templates

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json
  1. body
template*string
params?

Response Body

OK.

application/json
  1. response
[key: string]?any
Example Request
curl -X POST 'https://ai.codai.ro/v1/schedules/templates' \  -H 'Content-Type: application/json' \  -d '{  "template": "string"}'
Example Response
{}
GET
/v1/heartbeats

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

OK.

application/json
  1. response
heartbeats*array<>
Example Request
curl -X GET 'https://ai.codai.ro/v1/heartbeats'
Example Response
{  "heartbeats": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "period_s": 0,      "grace_s": 0,      "tz": "string",      "status": "new",      "last_ping_at": "2019-08-24T14:15:22Z",      "last_start_at": "2019-08-24T14:15:22Z",      "last_exit_code": 0,      "ping_url": "string",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ]}
POST
/v1/heartbeats

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json
  1. body
name*string
Lengthlength <= 120
period_s*integer
Range60 <= value <= 2592000
grace_s?integer
Range60 <= value <= 604800
tz?string

Response Body

Created.

application/json
  1. response

A heartbeat monitor.

id*string
Formatuuid
name*string
period_s*integer
grace_s*integer
tz?string
status*string
Value in"new""up""late""down""paused"
last_ping_at?string
Formatdate-time
last_start_at?string
Formatdate-time
last_exit_code?integer
ping_url?string

Only in the create response.

created_at?string
Formatdate-time
updated_at?string
Formatdate-time
Example Request
curl -X POST 'https://ai.codai.ro/v1/heartbeats' \  -H 'Content-Type: application/json' \  -d '{  "name": "string",  "period_s": 60}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "period_s": 0,  "grace_s": 0,  "tz": "string",  "status": "new",  "last_ping_at": "2019-08-24T14:15:22Z",  "last_start_at": "2019-08-24T14:15:22Z",  "last_exit_code": 0,  "ping_url": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}
PATCH
/v1/heartbeats/{id}

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Path Parameters

id*string

Monitor id.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json
  1. body
name?string
Lengthlength <= 120
period_s?integer
Range60 <= value <= 2592000
grace_s?integer
Range60 <= value <= 604800
paused?boolean

Response Body

OK.

application/json
  1. response

A heartbeat monitor.

id*string
Formatuuid
name*string
period_s*integer
grace_s*integer
tz?string
status*string
Value in"new""up""late""down""paused"
last_ping_at?string
Formatdate-time
last_start_at?string
Formatdate-time
last_exit_code?integer
ping_url?string

Only in the create response.

created_at?string
Formatdate-time
updated_at?string
Formatdate-time
Example Request
curl -X PATCH 'https://ai.codai.ro/v1/heartbeats/497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "period_s": 0,  "grace_s": 0,  "tz": "string",  "status": "new",  "last_ping_at": "2019-08-24T14:15:22Z",  "last_start_at": "2019-08-24T14:15:22Z",  "last_exit_code": 0,  "ping_url": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}
DELETE
/v1/heartbeats/{id}

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Path Parameters

id*string

Monitor id.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

Deleted.

Example Request
curl -X DELETE 'https://ai.codai.ro/v1/heartbeats/497f6eca-6276-4993-bfeb-53cbbbba6f08'
Example Response
Empty

Live status

GET /v1/schedules/stream sends a schedule event whenever a schedule changes or a run moves state on any device, so every screen updates within a second.

import { Codai } from 'codai-sdk';

const codai = new Codai({ apiKey: process.env.CODAI_API_KEY! });
const preview = await codai.schedules.preview({ text: 'every weekday at 9', tz: 'Europe/Bucharest' });
const backup = await codai.schedules.create({
  name: 'Nightly backup',
  kind: 'shell',
  spec: { command: 'restic backup ~/work' },
  trigger: { type: 'cron', expr: '0 3 * * *', tz: 'Europe/Bucharest' },
  target: { type: 'tags', tags: ['pc'] },
  retries: 2,
});
for await (const e of codai.schedules.stream()) console.log(e.op, e.state);
from codai import Codai

codai = Codai(api_key="codai_...", device="7f0e3c1a-...")
job = codai.schedules.executor.claim()  # host side; None when there is nothing to run
if job:
    codai.schedules.executor.result(job["run"]["id"], {"attempt": job["run"]["attempt"], "ok": True, "exit_code": 0})
GET
/v1/schedules

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

OK.

application/json
  1. response
schedules*array<>
Example Request
curl -X GET 'https://ai.codai.ro/v1/schedules'
Example Response
{  "schedules": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "description": "string",      "enabled": true,      "kind": "agent",      "spec": {},      "trigger": {},      "target": {},      "failover": [        [          "string"        ]      ],      "native": true,      "policy": {},      "misfire": "skip",      "misfire_window_min": 0,      "overlap": "skip",      "timeout_s": 0,      "retries": 0,      "retry_backoff_s": 0,      "late_after_s": 0,      "alert_on_fail": true,      "template": "string",      "command_hash": "string",      "next_run_at": "2019-08-24T14:15:22Z",      "last_run_at": "2019-08-24T14:15:22Z",      "upcoming": [        "2019-08-24T14:15:22Z"      ],      "approvals": [        {          "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",          "command_hash": "string",          "approved_at": "2019-08-24T14:15:22Z"        }      ],      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ]}
POST
/v1/schedules

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json
  1. body

Schedule fields. kind selects the shape of spec: agent {prompt, skill?, permissions?}, shell {command, cwd?, env_names?, shell?}, http {method?, url, headers?, body?, expect_status?}, chain {steps, stop_on_failure?}, phone_action {action, params?}.

name*string
Lengthlength <= 120
description?string
enabled?boolean
kind*string
Value in"agent""shell""http""chain""phone_action"
spec*
trigger*

cron {type, expr, tz}, at {type, at}, interval {type, every_s}, event {type, trigger_id} or after {type, schedule_id, on}.

target?

host {type, device_id}, tags {type, tags}, any, cloud or cloud_vm {type, project_id}.

failover?array<array<string>>
native?boolean
policy?

Approval (never, always, outside quiet hours), quiet hours, budgets per run and per day (micro-USD) and the hourly run limit.

misfire?string
Value in"skip""once""all_within"
misfire_window_min?integer
overlap?string
Value in"skip""queue""kill"
timeout_s?integer
retries?integer
retry_backoff_s?integer
late_after_s?integer
alert_on_fail?boolean
template?string

Response Body

Created.

application/json
  1. response

A scheduled task.

id*string
Formatuuid
name*string
Lengthlength <= 120
description?string
enabled*boolean
kind*string
Value in"agent""shell""http""chain""phone_action"
spec?
trigger*

cron {type, expr, tz}, at {type, at}, interval {type, every_s}, event {type, trigger_id} or after {type, schedule_id, on}.

target*

host {type, device_id}, tags {type, tags}, any, cloud or cloud_vm {type, project_id}.

failover?array<array<string>>
native?boolean
policy?

Approval (never, always, outside quiet hours), quiet hours, budgets per run and per day (micro-USD) and the hourly run limit.

misfire?string
Value in"skip""once""all_within"
misfire_window_min?integer
overlap?string
Value in"skip""queue""kill"
timeout_s?integer
retries?integer
retry_backoff_s?integer
late_after_s?integer
alert_on_fail?boolean
template?string
command_hash?string
next_run_at?string
Formatdate-time
last_run_at?string
Formatdate-time
upcoming*array<>
approvals?array<>
created_at?string
Formatdate-time
updated_at?string
Formatdate-time
Example Request
curl -X POST 'https://ai.codai.ro/v1/schedules' \  -H 'Content-Type: application/json' \  -d '{  "name": "string",  "kind": "agent",  "spec": {},  "trigger": {}}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "description": "string",  "enabled": true,  "kind": "agent",  "spec": {},  "trigger": {},  "target": {},  "failover": [    [      "string"    ]  ],  "native": true,  "policy": {},  "misfire": "skip",  "misfire_window_min": 0,  "overlap": "skip",  "timeout_s": 0,  "retries": 0,  "retry_backoff_s": 0,  "late_after_s": 0,  "alert_on_fail": true,  "template": "string",  "command_hash": "string",  "next_run_at": "2019-08-24T14:15:22Z",  "last_run_at": "2019-08-24T14:15:22Z",  "upcoming": [    "2019-08-24T14:15:22Z"  ],  "approvals": [    {      "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",      "command_hash": "string",      "approved_at": "2019-08-24T14:15:22Z"    }  ],  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}
POST
/v1/schedules/preview

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json
  1. body
text?string
Lengthlength <= 200
trigger?
tz?string
Default"Europe/Bucharest"

Response Body

OK.

application/json
  1. response
ok*boolean
reason?string
Value in"not_understood""invalid"
trigger?
next_runs?array<>
dst_warning?boolean
Example Request
curl -X POST 'https://ai.codai.ro/v1/schedules/preview' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "ok": true,  "reason": "not_understood",  "trigger": {},  "next_runs": [    "2019-08-24T14:15:22Z"  ],  "dst_warning": true}
GET
/v1/schedules/stream

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

OK.

response?stringtext/event-stream
Example Request
curl -X GET 'https://ai.codai.ro/v1/schedules/stream'
Example Response
"string"
GET
/v1/schedules/{id}

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Path Parameters

id*string

Schedule id.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

OK.

application/json
  1. response

A scheduled task.

id*string
Formatuuid
name*string
Lengthlength <= 120
description?string
enabled*boolean
kind*string
Value in"agent""shell""http""chain""phone_action"
spec?
trigger*

cron {type, expr, tz}, at {type, at}, interval {type, every_s}, event {type, trigger_id} or after {type, schedule_id, on}.

target*

host {type, device_id}, tags {type, tags}, any, cloud or cloud_vm {type, project_id}.

failover?array<array<string>>
native?boolean
policy?

Approval (never, always, outside quiet hours), quiet hours, budgets per run and per day (micro-USD) and the hourly run limit.

misfire?string
Value in"skip""once""all_within"
misfire_window_min?integer
overlap?string
Value in"skip""queue""kill"
timeout_s?integer
retries?integer
retry_backoff_s?integer
late_after_s?integer
alert_on_fail?boolean
template?string
command_hash?string
next_run_at?string
Formatdate-time
last_run_at?string
Formatdate-time
upcoming*array<>
approvals?array<>
created_at?string
Formatdate-time
updated_at?string
Formatdate-time
Example Request
curl -X GET 'https://ai.codai.ro/v1/schedules/497f6eca-6276-4993-bfeb-53cbbbba6f08'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "description": "string",  "enabled": true,  "kind": "agent",  "spec": {},  "trigger": {},  "target": {},  "failover": [    [      "string"    ]  ],  "native": true,  "policy": {},  "misfire": "skip",  "misfire_window_min": 0,  "overlap": "skip",  "timeout_s": 0,  "retries": 0,  "retry_backoff_s": 0,  "late_after_s": 0,  "alert_on_fail": true,  "template": "string",  "command_hash": "string",  "next_run_at": "2019-08-24T14:15:22Z",  "last_run_at": "2019-08-24T14:15:22Z",  "upcoming": [    "2019-08-24T14:15:22Z"  ],  "approvals": [    {      "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",      "command_hash": "string",      "approved_at": "2019-08-24T14:15:22Z"    }  ],  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}
PATCH
/v1/schedules/{id}

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Path Parameters

id*string

Schedule id.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json
  1. body
[key: string]?any

Response Body

OK.

application/json
  1. response

A scheduled task.

id*string
Formatuuid
name*string
Lengthlength <= 120
description?string
enabled*boolean
kind*string
Value in"agent""shell""http""chain""phone_action"
spec?
trigger*

cron {type, expr, tz}, at {type, at}, interval {type, every_s}, event {type, trigger_id} or after {type, schedule_id, on}.

target*

host {type, device_id}, tags {type, tags}, any, cloud or cloud_vm {type, project_id}.

failover?array<array<string>>
native?boolean
policy?

Approval (never, always, outside quiet hours), quiet hours, budgets per run and per day (micro-USD) and the hourly run limit.

misfire?string
Value in"skip""once""all_within"
misfire_window_min?integer
overlap?string
Value in"skip""queue""kill"
timeout_s?integer
retries?integer
retry_backoff_s?integer
late_after_s?integer
alert_on_fail?boolean
template?string
command_hash?string
next_run_at?string
Formatdate-time
last_run_at?string
Formatdate-time
upcoming*array<>
approvals?array<>
created_at?string
Formatdate-time
updated_at?string
Formatdate-time
Example Request
curl -X PATCH 'https://ai.codai.ro/v1/schedules/497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "description": "string",  "enabled": true,  "kind": "agent",  "spec": {},  "trigger": {},  "target": {},  "failover": [    [      "string"    ]  ],  "native": true,  "policy": {},  "misfire": "skip",  "misfire_window_min": 0,  "overlap": "skip",  "timeout_s": 0,  "retries": 0,  "retry_backoff_s": 0,  "late_after_s": 0,  "alert_on_fail": true,  "template": "string",  "command_hash": "string",  "next_run_at": "2019-08-24T14:15:22Z",  "last_run_at": "2019-08-24T14:15:22Z",  "upcoming": [    "2019-08-24T14:15:22Z"  ],  "approvals": [    {      "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",      "command_hash": "string",      "approved_at": "2019-08-24T14:15:22Z"    }  ],  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}
DELETE
/v1/schedules/{id}

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Path Parameters

id*string

Schedule id.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

Done, no content.

Example Request
curl -X DELETE 'https://ai.codai.ro/v1/schedules/497f6eca-6276-4993-bfeb-53cbbbba6f08'
Example Response
Empty
POST
/v1/schedules/{id}/run

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Path Parameters

id*string

Schedule id.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

Accepted.

application/json
  1. response
queued*boolean
Example Request
curl -X POST 'https://ai.codai.ro/v1/schedules/497f6eca-6276-4993-bfeb-53cbbbba6f08/run'
Example Response
{  "queued": true}
GET
/v1/schedules/{id}/runs

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Path Parameters

id*string

Schedule id.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

OK.

application/json
  1. response
runs*array<>
Example Request
curl -X GET 'https://ai.codai.ro/v1/schedules/497f6eca-6276-4993-bfeb-53cbbbba6f08/runs'
Example Response
{  "runs": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "schedule_id": "8929bb67-0da1-406c-99d2-5447376a4f58",      "scheduled_for": "2019-08-24T14:15:22Z",      "state": "pending",      "attempt": 0,      "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",      "started_at": "2019-08-24T14:15:22Z",      "finished_at": "2019-08-24T14:15:22Z",      "exit_code": 0,      "cost_micro_usd": 0,      "log_tail": "string",      "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",      "error": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ]}
POST
/v1/schedules/{id}/approve-command

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Path Parameters

id*string

Schedule id.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128
x-codai-device*string

Stable device UUID. Registers the device on first use (name/platform from x-codai-device-name / x-codai-device-platform) and selects the shared-sessions protocol.

Formatuuid

Request Body

application/json
  1. body
command_hash*string
Match^[0-9a-f]{64}$

Response Body

OK.

application/json
  1. response
approved*boolean
device_id*string
Formatuuid
Example Request
curl -X POST 'https://ai.codai.ro/v1/schedules/497f6eca-6276-4993-bfeb-53cbbbba6f08/approve-command' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{  "command_hash": "string"}'
Example Response
{  "approved": true,  "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940"}
GET
/v1/schedule-runs

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Query Parameters

limit?integer
Range1 <= value <= 200
Default50

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

OK.

application/json
  1. response
runs*array<>
Example Request
curl -X GET 'https://ai.codai.ro/v1/schedule-runs'
Example Response
{  "runs": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "schedule_id": "8929bb67-0da1-406c-99d2-5447376a4f58",      "scheduled_for": "2019-08-24T14:15:22Z",      "state": "pending",      "attempt": 0,      "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",      "started_at": "2019-08-24T14:15:22Z",      "finished_at": "2019-08-24T14:15:22Z",      "exit_code": 0,      "cost_micro_usd": 0,      "log_tail": "string",      "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",      "error": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ]}
POST
/v1/schedule-runs/{id}/decision

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Path Parameters

id*string

Run id.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json
  1. body
approve*boolean

Response Body

OK.

application/json
  1. response

One execution of a schedule.

id*string
Formatuuid
schedule_id*string
Formatuuid
scheduled_for*string
Formatdate-time
state*string
Value in"pending""awaiting_approval""claimed""running""succeeded""failed""timed_out""skipped""cancelled"
attempt*integer
device_id?string
Formatuuid
started_at?string
Formatdate-time
finished_at?string
Formatdate-time
exit_code?integer
cost_micro_usd?integer
log_tail?string
session_id?string
Formatuuid
error?string
created_at?string
Formatdate-time
Example Request
curl -X POST 'https://ai.codai.ro/v1/schedule-runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/decision' \  -H 'Content-Type: application/json' \  -d '{  "approve": true}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "schedule_id": "8929bb67-0da1-406c-99d2-5447376a4f58",  "scheduled_for": "2019-08-24T14:15:22Z",  "state": "pending",  "attempt": 0,  "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",  "started_at": "2019-08-24T14:15:22Z",  "finished_at": "2019-08-24T14:15:22Z",  "exit_code": 0,  "cost_micro_usd": 0,  "log_tail": "string",  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",  "error": "string",  "created_at": "2019-08-24T14:15:22Z"}
POST
/v1/schedule-runs/{id}/heartbeat

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Path Parameters

id*string

Run id.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128
x-codai-device*string

Stable device UUID. Registers the device on first use (name/platform from x-codai-device-name / x-codai-device-platform) and selects the shared-sessions protocol.

Formatuuid

Request Body

application/json
  1. body
attempt*integer
Range1 <= value
log?string
Lengthlength <= 16384

Response Body

Done, no content.

Example Request
curl -X POST 'https://ai.codai.ro/v1/schedule-runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/heartbeat' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{  "attempt": 1}'
Example Response
Empty
POST
/v1/schedule-runs/{id}/result

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Path Parameters

id*string

Run id.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128
x-codai-device*string

Stable device UUID. Registers the device on first use (name/platform from x-codai-device-name / x-codai-device-platform) and selects the shared-sessions protocol.

Formatuuid

Request Body

application/json
  1. body
attempt*integer
Range1 <= value
ok*boolean
exit_code?integer
error?string
Lengthlength <= 4000
log_tail?string
Lengthlength <= 65536
cost_micro_usd?integer
Range0 <= value
session_id?string
Formatuuid
timed_out?boolean

Response Body

OK.

application/json
  1. response

One execution of a schedule.

id*string
Formatuuid
schedule_id*string
Formatuuid
scheduled_for*string
Formatdate-time
state*string
Value in"pending""awaiting_approval""claimed""running""succeeded""failed""timed_out""skipped""cancelled"
attempt*integer
device_id?string
Formatuuid
started_at?string
Formatdate-time
finished_at?string
Formatdate-time
exit_code?integer
cost_micro_usd?integer
log_tail?string
session_id?string
Formatuuid
error?string
created_at?string
Formatdate-time
Example Request
curl -X POST 'https://ai.codai.ro/v1/schedule-runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/result' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{  "attempt": 1,  "ok": true}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "schedule_id": "8929bb67-0da1-406c-99d2-5447376a4f58",  "scheduled_for": "2019-08-24T14:15:22Z",  "state": "pending",  "attempt": 0,  "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",  "started_at": "2019-08-24T14:15:22Z",  "finished_at": "2019-08-24T14:15:22Z",  "exit_code": 0,  "cost_micro_usd": 0,  "log_tail": "string",  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",  "error": "string",  "created_at": "2019-08-24T14:15:22Z"}
GET
/v1/scheduler/hosts

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

OK.

application/json
  1. response
hosts*array<>
Example Request
curl -X GET 'https://ai.codai.ro/v1/scheduler/hosts'
Example Response
{  "hosts": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "platform": "string",      "os": "string",      "arch": "string",      "host_kind": "string",      "tags": [        "string"      ],      "capabilities": [        "string"      ],      "online": true,      "last_seen_at": "2019-08-24T14:15:22Z",      "app_version": "string"    }  ]}
PATCH
/v1/scheduler/hosts/{id}

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Path Parameters

id*string

Device id of the host.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json
  1. body
name?string
Lengthlength <= 120
tags?array<>
Itemsitems <= 16
host_kind?string
Value in"pc""phone""watch""vm""cloud"
os?string
Value in"windows""macos""linux""android""wearos""ios"
arch?string
Lengthlength <= 20

Response Body

OK.

application/json
  1. response
[key: string]?any
Example Request
curl -X PATCH 'https://ai.codai.ro/v1/scheduler/hosts/497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{}
POST
/v1/scheduler/claim

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128
x-codai-device*string

Stable device UUID. Registers the device on first use (name/platform from x-codai-device-name / x-codai-device-platform) and selects the shared-sessions protocol.

Formatuuid

Response Body

OK.

application/json
  1. response
run*

One execution of a schedule.

schedule*

A scheduled task.

host_approved*boolean
Example Request
curl -X POST 'https://ai.codai.ro/v1/scheduler/claim' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'
Example Response
{  "run": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "schedule_id": "8929bb67-0da1-406c-99d2-5447376a4f58",    "scheduled_for": "2019-08-24T14:15:22Z",    "state": "pending",    "attempt": 0,    "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",    "started_at": "2019-08-24T14:15:22Z",    "finished_at": "2019-08-24T14:15:22Z",    "exit_code": 0,    "cost_micro_usd": 0,    "log_tail": "string",    "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",    "error": "string",    "created_at": "2019-08-24T14:15:22Z"  },  "schedule": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "description": "string",    "enabled": true,    "kind": "agent",    "spec": {},    "trigger": {},    "target": {},    "failover": [      [        "string"      ]    ],    "native": true,    "policy": {},    "misfire": "skip",    "misfire_window_min": 0,    "overlap": "skip",    "timeout_s": 0,    "retries": 0,    "retry_backoff_s": 0,    "late_after_s": 0,    "alert_on_fail": true,    "template": "string",    "command_hash": "string",    "next_run_at": "2019-08-24T14:15:22Z",    "last_run_at": "2019-08-24T14:15:22Z",    "upcoming": [      "2019-08-24T14:15:22Z"    ],    "approvals": [      {        "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",        "command_hash": "string",        "approved_at": "2019-08-24T14:15:22Z"      }    ],    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  },  "host_approved": true}

Pending prompts

Ready-to-paste prompts that agents (or you) leave for a future chat — handoffs, dated follow-ups — with reminders and one-click launch on a device.

Transcripts

Record meetings and calls on any device, get a diarized Romanian/English transcript with word timings, then a summary, key points, actions and ready-to-run agent prompts.

On this page

What can runWhenWhereSafetyPause, skip days and noise controlHeartbeat monitorsLive status