Tasks API

Tasks are the primary unit of work in Kernel Service. Submit an objective, and the orchestrator processes it through an AI agent.

Create Task

POST /api/v1/tasks

Request Body

Field	Type	Required	Description
objective	string	Yes	What the agent should accomplish
agent_id	UUID	No	Agent to execute on behalf of
pack_id	UUID	No	Agent pack to use
subject_refs	array	No	Entities the task relates to
constraints	object	No	Constraints on execution
priority	integer	No	1-10, default 5

Example

curl -X POST https://api.kernelservice.com/api/v1/tasks \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "objective": "Qualify lead #456 and draft a follow-up email",
    "agent_id": "agent-uuid",
    "subject_refs": [
      {"type": "lead", "id": "456", "product": "ROL"}
    ]
  }'

Response

{
  "task_id": "uuid",
  "run_id": "uuid",
  "status": "completed",
  "output": {"response": "..."},
  "metrics": {
    "total_input_tokens": 2507,
    "total_output_tokens": 693,
    "total_cost_cents": 0.05,
    "model_used": "gemini-2.0-flash",
    "elapsed_ms": 6709,
    "step_count": 5
  },
  "steps": [...]
}

Get Task

GET /api/v1/tasks/{task_id}

Returns the full task result including audit trail.

List Tasks

GET /api/v1/tasks?status=completed&limit=20

Parameter	Type	Description
status	string	Filter by status
limit	integer	Results per page (max 100)
offset	integer	Pagination offset

Cancel Task

POST /api/v1/tasks/{task_id}/cancel