Task API v26.5+

The capability Task API is an authenticated, synchronous fire-and-resolve interface. One request creates a bounded task, lets Kubling and the runtime exchange bounded actions and observations, and returns the final snapshot.

Endpoints

Use the versioned route in automation. The versionless route returns 409 when the name is ambiguous.

Both routes use Kubling’s normal HTTP authentication path. The response content type is application/json and successful and error responses include Cache-Control: no-store.

Request

{
  "goal": "Find why the checkout workloads are unhealthy",
  "externalContextId": "incident-4821",
  "externalContext": {
    "region": "eu",
    "severity": "high"
  },
  "artifactIds": [
    "runbook-checkout"
  ]
}

Caller and role fields in the body are not trusted. Kubling derives identity only from the authenticated HTTP request. It sends the runtime an authorized catalog, function and semantic context derived for that caller, without sending the caller’s credential or identity. Kubling retains the effective caller and uses it when executing every accepted query action.

Example invocation for a deployment configured with bearer authentication:

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $KUBLING_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"goal":"Find why the checkout workloads are unhealthy"}' \
  http://localhost:8282/api/v1/capabilities/investigation/vdbs/Operations/versions/1/tasks

Terminal response

{
  "format": "kubling-task-snapshot",
  "formatVersion": 1,
  "task": {
    "taskId": "task-1",
    "target": {
      "instanceId": "engine-a",
      "vdbName": "Operations",
      "vdbVersion": "1"
    }
  },
  "capability": "investigation",
  "state": "completed",
  "artifacts": [
    {
      "id": "conclusion-1",
      "kind": "conclusion",
      "content": {
        "contentType": "text/plain; charset=utf-8",
        "data": "cm9vdCBjYXVzZQ=="
      }
    }
  ],
  "usage": {
    "inputTokens": 1200,
    "outputTokens": 240,
    "modelCalls": 2,
    "kublingActions": 1,
    "observationRows": 1,
    "observationBytes": 128
  },
  "stop": {
    "reason": "goal_satisfied",
    "detail": "Goal satisfied by cited observations"
  }
}

Artifact content.data is Base64-encoded. Decode it according to its explicit contentType rather than assuming every artifact is text.

Task states are working, input_required, completed, cancelled, budget_exceeded and failed. The public synchronous endpoint normally returns a terminal state. Intermediate states are part of the versioned runtime protocol and may appear in diagnostics or future transports.

Error response

Errors use a stable versioned envelope:

{
  "format": "kubling-task-error",
  "formatVersion": 1,
  "code": "context_unavailable",
  "message": "No active Kubling context is available for capability tasks",
  "retryable": true
}

Use the envelope’s retryable field together with application semantics. Never retry a task solely because its HTTP status is 503.

Runtime integration contract

Applications using the Task API do not call these endpoints. They are required only when implementing a compatible agent runtime. Kubling uses these HTTP operations beneath the configured runtime baseURL:

This boundary exchanges kubling-task-start, kubling-task-advance and kubling-task-snapshot documents at formatVersion: 1. It is a Kubling-native contract and is not presented as A2A-compatible.

Authorized context

Every kubling-task-start document includes an authorizedContext derived for the authenticated caller. It identifies the exact VDB and catalog revisions and describes the catalog relations, functions and semantic surface available for planning. Access can be complete, restricted to an explicit selection or unavailable.

The runtime must constrain its proposed actions to this context. The field is not a credential and does not contain the caller’s identity. Kubling retains the authenticated caller and applies authorization again when executing every accepted query action.

See the security boundary for identity delegation and runtime-credential guidance.