---
title: "Create a task in a session's todo list"
method: POST
path: "/v1/task/create"
tags: ["Task"]
---

# Create a task in a session's todo list

`POST /v1/task/create`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/task/create`
- Auth: HTTP bearer

Mints a `pending` task in the agent's per-session todo store (B3b of the
Agent Loop Kernel Relocation). Session scoping: `task_create` takes the
driving agent session from its invocation, so the model never supplies it;
a route caller may pass `session_id` explicitly, else the shared `default`
bucket is used, and only the conversation's owner may use its list. The
route mirrors `task_create`: that tool's Deny, Ask and firewall judge the
call (403 `tool_refused`, or `consent_required` to a caller that declares
the REST approval channel), and the call is recorded as a `task_create` call.

## Request body

- object
  - `title` string, required: Short title of the task
  - `description` string: Optional longer description
  - `session_id` string: The session whose todo list to add to (defaults to "default")

## Response `200`

Task created

- object
  - `ok` true
  - `task` AgentTask
    - `id` string, required
    - `title` string, required
    - `description` string
    - `status` 'pending' | 'in_progress' | 'completed' | 'cancelled', required
    - `createdAt` string, required
    - `updatedAt` string, required

## Other responses

- `400`: Missing/blank title
- `429`: Per-session task limit reached

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)