INSULA LABS

HTML docs · raw markdown

Tasks

A task is an immediate (one-shot) agent run created through this API. Create queues a job and returns right away; poll status, then fetch scrubbed history when it finishes.

Scope: only jobs with a public tsk_… id minted by POST /v1/tasks. Schedule-triggered runs and product-UI jobs are not listed or addressable here. Tasks do not support webhooks. Job event streams and permission/credential gate submission are not part of this API.

Typical flow: create → poll get → history when terminal → optional delete or clear.

Identifiers

Field Role
id Stable handle (tsk_…). Use this in get/history/cancel/retry/delete and CLI -id / -ids.
agentId Site agent (ag_… from agents list).
knowledgebaseId Knowledgebase (kb_…) the agent runs against.

Example task object:

{
  "id": "tsk_7k2m9x4q",
  "agentId": "ag_7k2m9x4q",
  "agentName": "Kobold AI",
  "knowledgebaseId": "kb_qc0rp0gz",
  "prompt": "Summarize new files",
  "state": "queued",
  "createdAt": "2026-07-16T19:24:19.812169Z"
}

States: queued, running, completed, failed, cancelled. You may also see needs_permission, required_credentials, or waiting_on_child when a run is blocked. There are no public endpoints to unblock gates; cancel the task or wait for a future gate API.

usage (when present) has inputTokens, outputTokens, and toolCalls. Optional timestamps: startedAt, finishedAt. Optional error on failure.

List

Lists tasks created via this API for your key (newest first). Query: offset, limit (default 50). Orphan aliases (runner job already gone) are omitted from the page and cleaned up server-side.

kobold-cli tasks list
kobold-cli tasks list -offset 0 -limit 20

GET /v1/tasks?offset=0&limit=50
Authorization: Bearer <api_key>

Response:

{
  "tasks": [ /* Task objects */ ],
  "offset": 0,
  "limit": 50,
  "total": 3
}

Create

Queues an immediate run. Same inputs as schedule create minus interval and hooks. Enforces active/total task and day/month token limits. Mints tsk_….

kobold-cli tasks create -agent ag_7k2m9x4q -kb kb_qc0rp0gz -prompt "Summarize new files"
kobold-cli tasks create -agent ag_7k2m9x4q -kb kb_qc0rp0gz -prompt ./prompt.md

POST /v1/tasks
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "agentId": "ag_7k2m9x4q",
  "knowledgebaseId": "kb_qc0rp0gz",
  "prompt": "Summarize new files"
}

Success returns a Task, typically with state: "queued". Unknown agent or knowledgebase for your key → 404. Limit exceeded → 429.

Get (poll)

kobold-cli tasks get -id tsk_7k2m9x4q

GET /v1/tasks/tsk_7k2m9x4q
Authorization: Bearer <api_key>

Unknown or other-tenant id → 404.

History

Chat-like result after (or during) a run. Every transcript message with role == "system" is dropped. response is the last non-empty assistant text after that scrub. Raw event streams are not exposed.

kobold-cli tasks history -id tsk_7k2m9x4q

GET /v1/tasks/tsk_7k2m9x4q/history
Authorization: Bearer <api_key>

Example shape:

{
  "response": "Here is a short summary…",
  "transcript": [
    { "role": "user", "text": "Summarize new files" },
    { "role": "assistant", "text": "Here is a short summary…" }
  ],
  "state": "completed",
  "usage": {
    "inputTokens": 1200,
    "outputTokens": 340,
    "toolCalls": 2
  }
}

Cancel

Soft-cancels a non-terminal task. The row is kept with state: "cancelled". Already-terminal tasks are rejected.

kobold-cli tasks cancel -id tsk_7k2m9x4q

POST /v1/tasks/tsk_7k2m9x4q/cancel
Authorization: Bearer <api_key>

Retry

Requeues a failed task. Other states are rejected.

kobold-cli tasks retry -id tsk_7k2m9x4q

POST /v1/tasks/tsk_7k2m9x4q/retry
Authorization: Bearer <api_key>

Delete

Hard-deletes the runner job and its public alias.

kobold-cli tasks delete -id tsk_7k2m9x4q

DELETE /v1/tasks/tsk_7k2m9x4q
Authorization: Bearer <api_key>

CLI prints {"ok": true} on success.

Clear (bulk delete)

Hard-deletes several API-created tasks. Unknown ids are skipped.

kobold-cli tasks clear -ids tsk_7k2m9x4q,tsk_abc12345

POST /v1/tasks/clear
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "ids": ["tsk_7k2m9x4q", "tsk_abc12345"]
}

Response: { "cleared": N } (rows actually removed upstream).

Related