Tasks

Overview

Tasks define reusable asynchronous Agent work with optional schedules. Use them for on-demand execution or recurring automation whose runs remain independently observable.

Endpoints

POST /v1/tasks

Creates a Task. Omit schedule for on-demand execution. Set submit: true to enqueue an initial run; this creation endpoint is not idempotent. A tenant can have at most 100 Tasks.

Requires bearer authentication and JSON. There are no path or query parameters. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

Location	Field	Required	Description
Header	`Authorization`	yes	Tenant API key or dashboard Supabase JWT.

Body field	Type	Required	Default
`agentId`	string	yes	—
`agentVersion`	integer \| null	no	`null`
`name`	string	yes	—
`prompt`	string	yes	—
`schedule`	object \| null	no	`null`
`enabled`	boolean	no	`true`
`submit`	boolean	no	`false`
`userId`	string	no	`""`
`metadata`	object	no	`{}`

Names are 1–80 characters; prompts are 1–6,000 characters. Schedules use the Task schedule shapes.

Response

Returns 201 Created with the complete Task object and the queued run ID, or null when submit is false.

Response schema: createTaskResponseSchema.

{
  "task": {
    "id": "tk_1234567890ABCDEF",
    "tenantId": "ten_1234567890ABCDEF",
    "agentId": "ag_1234567890ABCDEF",
    "agentVersion": null,
    "name": "Daily summary",
    "prompt": "Summarize open support cases.",
    "schedule": {
      "kind": "cron",
      "config": { "expression": "0 9 * * 1-5", "timezone": "Europe/London" }
    },
    "enabled": true,
    "activeRunId": null,
    "activeRunCancelRequestedAt": null,
    "latestRunId": null,
    "recentRuns": [],
    "userId": "",
    "metadata": {},
    "deletedAt": null,
    "createdAt": "2026-07-10T10:00:00Z",
    "updatedAt": "2026-07-10T10:00:00Z"
  },
  "runId": null
}

Errors

400 invalid_request for invalid fields/schedule or the Task cap. 404 AGENT_VERSION_NOT_FOUND, 409 AGENT_DISABLED, and 409 ADMIN_AGENT_MANAGED can reject the selected Agent Version or an immediate submission. See REST errors.

cURL

curl --request POST "$BLAZING_AGENTS_BASE_URL/v1/tasks" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"agentId":"ag_1234567890ABCDEF","name":"Daily summary","prompt":"Summarize open support cases.","schedule":{"kind":"cron","config":{"expression":"0 9 * * 1-5","timezone":"Europe/London"}}}'

SDK: create. See Tasks and schedules and Schedule recurring work.

GET /v1/tasks

Returns non-deleted Tasks ordered by most recently updated. Each item adds latestRun to avoid a separate status lookup.

Request

Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

Location	Field	Required	Description
Header	`Authorization`	yes	Tenant API key or dashboard Supabase JWT.

Query parameter	Type	Default	Description
`agentId`	string	—	Restrict to one Agent
`userId`	string	—	Attribution filter; `""` means tenant-level
`cursor`	string	—	Opaque cursor
`limit`	integer	50	1–200

Response

Returns 200 OK with { data, nextCursor }. Each data item is a complete Task plus latestRun: { id, status, finishedAt } | null.

Response schema: tasksListResponseSchema.

{
  "data": [
    {
      "id": "tk_1234567890ABCDEF",
      "tenantId": "ten_1234567890ABCDEF",
      "agentId": "ag_1234567890ABCDEF",
      "agentVersion": null,
      "name": "Daily summary",
      "prompt": "Summarize open support cases.",
      "schedule": null,
      "enabled": true,
      "activeRunId": null,
      "activeRunCancelRequestedAt": null,
      "latestRunId": "tr_1234567890ABCDEF",
      "recentRuns": [
        {
          "runId": "tr_1234567890ABCDEF",
          "status": "succeeded",
          "finishedAt": "2026-07-10T10:03:00Z"
        }
      ],
      "userId": "",
      "metadata": {},
      "deletedAt": null,
      "createdAt": "2026-07-10T10:00:00Z",
      "updatedAt": "2026-07-10T10:03:00Z",
      "latestRun": {
        "id": "tr_1234567890ABCDEF",
        "status": "succeeded",
        "finishedAt": "2026-07-10T10:03:00Z"
      }
    }
  ],
  "nextCursor": null
}

Errors

400 invalid_request for invalid filters, limit, or cursor. See REST errors.

cURL

curl --get "$BLAZING_AGENTS_BASE_URL/v1/tasks" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --data-urlencode "agentId=ag_1234567890ABCDEF" \
  --data-urlencode "limit=50"

SDK: list. See Tasks and schedules and Schedule recurring work.

GET /v1/tasks/:taskId

Returns one non-deleted Task definition. Reading it does not enqueue a run or alter its schedule lifecycle.

Request

Requires bearer authentication and a tk_… taskId path parameter. There are no query or body parameters. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

Location	Field	Required	Description
Header	`Authorization`	yes	Tenant API key or dashboard Supabase JWT.
Path	`taskId`	yes	Task ID (`tk_…`).

Response

Returns 200 OK with the complete Task object.

Response schema: taskResponseSchema.

{
  "id": "tk_1234567890ABCDEF",
  "tenantId": "ten_1234567890ABCDEF",
  "agentId": "ag_1234567890ABCDEF",
  "agentVersion": null,
  "name": "Daily summary",
  "prompt": "Summarize open support cases.",
  "schedule": null,
  "enabled": true,
  "activeRunId": null,
  "activeRunCancelRequestedAt": null,
  "latestRunId": null,
  "recentRuns": [],
  "userId": "",
  "metadata": {},
  "deletedAt": null,
  "createdAt": "2026-07-10T10:00:00Z",
  "updatedAt": "2026-07-10T10:00:00Z"
}

Errors

400 invalid_request for a malformed ID. 404 not_found when the Task is missing, foreign, or deleted. See REST errors.

cURL

curl "$BLAZING_AGENTS_BASE_URL/v1/tasks/tk_1234567890ABCDEF" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"

SDK: get. See Tasks and schedules and Schedule recurring work.

PATCH /v1/tasks/:taskId

Updates a Task. agentId and userId are immutable. Schedule and enabled-state changes are durably synchronized to DBOS; schedule: null makes the Task on-demand.

Request

Requires bearer authentication, JSON, and a tk_… taskId. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

Location	Field	Required	Description
Header	`Authorization`	yes	Tenant API key or dashboard Supabase JWT.
Path	`taskId`	yes	Task ID (`tk_…`).

Body field	Type	Required	Description
`name`	string	no	New name
`agentVersion`	integer \| null	no	Pin a Version or follow current
`prompt`	string	no	New fixed instruction
`schedule`	object \| null	no	Replacement schedule or `null`
`enabled`	boolean	no	Scheduling switch
`metadata`	object	no	Replacement metadata

At least one field is required.

Response

Returns 200 OK with the complete updated Task object.

Response schema: taskSchema.

Errors

400 invalid_request for invalid/empty fields or schedule. 404 not_found applies to a missing Task; 404 AGENT_VERSION_NOT_FOUND rejects a missing pin, and 409 ADMIN_AGENT_MANAGED protects the Admin Agent. See REST errors.

cURL

curl --request PATCH \
  "$BLAZING_AGENTS_BASE_URL/v1/tasks/tk_1234567890ABCDEF" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"enabled":false,"metadata":{"pausedBy":"ops"}}'

SDK: update. See Tasks and schedules and Schedule recurring work.

DELETE /v1/tasks/:taskId

Soft-deletes the Task. Its ID subsequently returns 404; existing Task runs and their Sessions remain. A Task with an active run cannot be deleted.

Request

Requires bearer authentication and a tk_… taskId. There are no query or body parameters. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

Location	Field	Required	Description
Header	`Authorization`	yes	Tenant API key or dashboard Supabase JWT.
Path	`taskId`	yes	Task ID (`tk_…`).

curl --request DELETE \
  "$BLAZING_AGENTS_BASE_URL/v1/tasks/tk_1234567890ABCDEF" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"

SDK: delete. See Tasks and schedules and Schedule recurring work.

On this page