• English

      • Octop Cron API: Schedule Automated Agent Tasks via REST

      The Cron API lets you create scheduled tasks that prompt your agents automatically — no manual interaction required. Jobs run on cron expressions, fixed intervals, or a specific one-time date and time. Each job sends a prompt to the agent on schedule, either passing it directly to the session or running it through the LLM to generate a reply.

      Base path

      /api/agents/{agent_id}/cron

      Endpoints

      MethodPathAuthDescription
      GET/cron/settingsuserGet process timezone
      GET/agents/{aid}/cron/examplesagent access{task_examples} from workspace .octop/manifest.json ({zh,en} string arrays, display-normalized to 3 or 6); null if absent (the web UI keeps default cards). Prefer GET /agents/{aid}/chat/welcome, which includes the same field
      GET/agents/{aid}/cronownerList cron jobs for an agent
      POST/agents/{aid}/cronownerCreate a cron job
      GET/agents/{aid}/cron/{cid}ownerGet job details
      PATCH/agents/{aid}/cron/{cid}ownerUpdate a job
      DELETE/agents/{aid}/cron/{cid}ownerDelete a job
      POST/agents/{aid}/cron/{cid}/run-nowownerTrigger immediately (off-schedule)

      Create a cron job

      Send a POST request with a trigger and a prompt to schedule a recurring task. Only the job owner can list or change jobs — administrators who do not own the agent receive an empty list.

      Daily briefing (9 AM)
      Every 30 minutes
      One-time at a specific date
      Daily briefing (9 AM)
      curl -X POST http://127.0.0.1:8088/api/agents/main/cron \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Morning briefing",
    "trigger": "0 9 * * *",
    "prompt": "Summarize today'\''s important events and send me a briefing.",
    "task_type": "agent"
  }'

      Request body

      namestringbody

      Optional display label. When omitted, the server derives one from prompt.

      triggerstringbodyrequired

      Defines when the job runs. Accepts a cron expression, an interval shorthand, or a one-time ISO 8601 date. See the trigger format table below.

      promptstringbodyrequired

      The text sent to the agent when the job fires. Must be non-empty and no longer than 2000 characters.

      task_typestringbody

      Controls how the prompt is handled. Use "agent" (default) to run the prompt through the LLM and push the reply into the session. Use "text" to push the prompt text directly without an LLM call.

      session_keystringbody

      Route the scheduled message to a specific existing thread. If omitted, the job uses the agent's default session.

      fresh_threadbooleanbody

      When true, Octop creates a brand-new thread for each run instead of appending to an existing one. Useful for daily summaries you want to keep isolated.

      modelstringbody

      Override the agent's default_model for this job only — for example "openai:gpt-4o-mini" to use a cheaper model for routine scheduled prompts.

      Trigger formats

      FormatExampleMeaning
      Cron expression0 9 * * *9 AM every day
      Cron expression0 */2 * * *Every 2 hours
      Intervalinterval:30Every 30 minutes
      One-timedate:2025-06-01T09:00:00Once at the specified date and time
      NOTE

      Cron jobs run in the timezone configured on your Octop server. Check the current timezone with GET /api/cron/settings before scheduling time-sensitive jobs.

      Trigger a job immediately

      Use POST /agents/{aid}/cron/{cid}/run-now to fire a scheduled job outside its normal schedule — for example when testing a new prompt before the next scheduled run.

      cURL
      cURL
      curl -X POST http://127.0.0.1:8088/api/agents/main/cron/job_abc/run-now \
  -H 'Authorization: Bearer $TOKEN'

      This returns 204 No Content and enqueues the job immediately. It does not affect the next scheduled run time.

      TIP

      Combine fresh_thread: true with a daily cron expression to get a clean, date-stamped conversation thread for every briefing or report — making it easy to review past runs in the chat history without scrolling through a single long thread.