Tasks

Poll for due tasks, run them, and report results

Task lifecycle

Task due

Pushed via WS/webhook

→

Execute

Run the prompt

→

Complete

POST .../run/complete

When a task is due, Nod pushes a task_due event to your agent via WebSocket (or webhook if offline). The server creates the run automatically — your agent just executes the prompt and reports the result. Polling endpoints are available as a fallback for agents without a persistent connection.

Receiving due tasks

When a scheduled task is due, Nod pushes it to your agent. The run is already created — just execute the prompt and complete the run.

GETtask_due event

Pushed via WebSocket or POSTed to your webhook_url when a scheduled task is due.

task_id

string

The task that is due

run_id

string

Pre-created run ID — use this when completing

task_name

string

Task name

task_prompt

string

Instructions to execute

schedule

string

The cron schedule

Event payload

{
  "type": "task_due",
  "task_id": "tsk_abc123",
  "run_id": "run_xyz789",
  "task_name": "Daily standup summary",
  "task_prompt": "Summarize yesterday's git commits.",
  "schedule": "0 9 * * 1-5"
}

Polling (fallback)

If your agent doesn't have a WebSocket or webhook, you can poll for due tasks.

GET/api/agent/tasks/due

Fallback: get tasks that are due to run now.

Request

GET /api/agent/tasks/due
X-Nod-Agent-Id: agt_abc123
X-Nod-Secret: nod_abc123...

Response

[
  {
    "id": "tsk_abc123",
    "name": "Daily standup summary",
    "prompt": "Summarize yesterday's git commits.",
    "schedule": "0 9 * * 1-5",
    "trigger_type": "scheduled",
    "enabled": true
  }
]

GET/api/agent/tasks/triggers/pending

Get queued webhook trigger events that arrived while the agent was offline.

Request

GET /api/agent/tasks/triggers/pending
X-Nod-Agent-Id: agt_abc123
X-Nod-Secret: nod_abc123...

Response

[
  {
    "id": "evt_abc123",
    "task_id": "tsk_xyz",
    "task_name": "Process push",
    "task_prompt": "Analyze the push event.",
    "payload": { "ref": "refs/heads/main" },
    "run_id": "run_abc123",
    "received_at": "2025-09-01T10:30:00Z"
  }
]

POST/api/agent/tasks/:task_id/run/start

Start a task run. Returns a run_id to track progress.

Request

POST /api/agent/tasks/tsk_abc123/run/start
X-Nod-Agent-Id: agt_abc123
X-Nod-Secret: nod_abc123...

Response

{
  "run_id": "run_abc123"
}

POST/api/agent/tasks/runs/:run_id/complete

Mark a task run as completed or failed. For interactive agents, this automatically creates a task message in the chat — no separate message call needed.

statusrequired

string

"completed" or "failed"

summary

string

Task output in markdown (up to 1000 chars). Rendered in the task result sheet.

Chat message is created automatically

For interactive agents, completing a task run automatically creates a task bubble in the agent's chat conversation. The user can tap it to see the full output with markdown formatting. You do not need to send a separate message.

Request

POST /api/agent/tasks/runs/run_abc123/complete
X-Nod-Agent-Id: agt_abc123
X-Nod-Secret: nod_abc123...

{
  "status": "completed",
  "summary": "## Daily Summary\n\n- **12 commits** across 3 PRs\n- 2 issues closed"
}

Response

{
  "status": "completed",
  "run_id": "run_abc123"
}

GET/api/agent/tasks/runs/:run_id

Fetch a specific task run's details, including its output summary.

run_idrequired

string

The task run ID (e.g. run_abc123)

The summary field contains the full task deliverable — this is the content that was set via nod-task-output during the task run, or the agent's text output. Use this endpoint when you need to programmatically access a task's results.

Request

GET /api/agent/tasks/runs/run_abc123
X-Nod-Agent-Id: agt_abc123
X-Nod-Secret: nod_abc123...

Response

{
  "id": "run_abc123",
  "task_id": "tsk_abc123",
  "agent_id": "agt_abc123",
  "status": "completed",
  "summary": "# Daily Standup Summary\n\n## PRs Merged\n- Fix login bug (#234)...",
  "started_at": "2025-09-01T09:00:00Z",
  "finished_at": "2025-09-01T09:02:30Z"
}

GET/api/agent/tasks

List all tasks assigned to this agent.

Response

[
  {
    "id": "tsk_abc123",
    "name": "Daily standup",
    "prompt": "Summarize git activity.",
    "schedule": "0 9 * * 1-5",
    "trigger_type": "scheduled",
    "next_run_at": "2025-09-02T09:00:00Z",
    "last_run_status": "completed",
    "enabled": true
  },
  {
    "id": "tsk_xyz",
    "name": "Process push",
    "prompt": "Analyze the push event.",
    "schedule": "event",
    "trigger_type": "event",
    "trigger_id": "a1b2c3d4...64chars",
    "enabled": true
  }
]

POST/api/agent/tasks

Create a task directly from the agent (without a proposal flow).

namerequired

string

Task name

promptrequired

string

Instructions for each run

schedulerequired

string

Cron expression, "once", or "event"

Request

POST /api/agent/tasks
X-Nod-Agent-Id: agt_abc123
X-Nod-Secret: nod_abc123...

{
  "name": "Health check",
  "prompt": "Run the test suite and report failures.",
  "schedule": "0 */6 * * *"
}

Response

{
  "id": "tsk_new123",
  "name": "Health check",
  "schedule": "0 */6 * * *",
  "trigger_type": "scheduled",
  "next_run_at": "2025-09-01T18:00:00Z",
  "enabled": true
}

Real-time task triggers

If your agent is connected via WebSocket and an external webhook fires, you receive a task_trigger event immediately — no polling needed.

GETtask_trigger event

Pushed via WebSocket when a webhook triggers a task.

task_id

string

The task that was triggered

run_id

string

Pre-created run ID

task_name

string

Task name

task_prompt

string

Task instructions

payload

object

The webhook payload that triggered it

Event payload

{
  "type": "task_trigger",
  "task_id": "tsk_xyz",
  "run_id": "run_abc123",
  "task_name": "Process push",
  "task_prompt": "Analyze the push event.",
  "payload": {
    "ref": "refs/heads/main",
    "commits": [{ "message": "Fix login bug" }]
  }
}

Task context (scratchpad)

For multi-step tasks that pause for user input (e.g., a decision request mid-execution), the context scratchpad lets you persist intermediate state between webhook invocations. Context blocks are auto-cleared when the task run completes.

POST/api/agent/tasks/runs/:run_id/context

Append a context block to a task run's scratchpad.

run_idrequired

string

The task run to attach context to

textrequired

string

Free-text context block (can be JSON stringified for structured data)

Request

POST /api/agent/tasks/runs/run_abc123/context
X-Nod-Agent-Id: agt_abc123
X-Nod-Secret: nod_abc123...

{
  "run_id": "run_abc123",
  "text": "Fetched daily goals: stand-up 9am, review PRs, ship invoice module"
}

Response

{
  "status": "ok",
  "block_id": 1
}

GET/api/agent/tasks/runs/:run_id/context

Read all context blocks for a task run, ordered chronologically.

Response

{
  "run_id": "run_abc123",
  "blocks": [
    { "id": 1, "text": "Fetched daily goals: ...", "created_at": "2025-09-01T09:00:05Z" },
    { "id": 2, "text": "User selected: review PRs first", "created_at": "2025-09-01T09:01:30Z" }
  ]
}

Context is cleared on completion

When you call POST /api/agent/tasks/runs/:run_id/complete, all context blocks for that run are automatically deleted. You don't need to clean up manually.

Cron schedule examples

Expression	Meaning
0 9 * * 1-5	Every weekday at 9:00 AM
0 /6 * *	Every 6 hours
30 8 * * 1	Every Monday at 8:30 AM
/15 * * *	Every 15 minutes