API: tasks

Note

Generated from the OpenAPI contract — do not edit by hand. Interactive explorer with full schemas: https://entherium.duckdns.org:8443/reference; frozen spec for this build: openapi.json.

GET /api/v1/tasks

List Tasks Endpoint

Open as a page →

The read-only task board — paginated, filterable by assignee / status / area. Team-only (owner + team members); an agent or non-team token gets 403.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
assignee_id	query	no	integer | null
status	query	no	string | null
area	query	no	string | null	platform|pipelines|instances|other
limit	query	no	integer
offset	query	no	integer

Responses:

Code	Meaning	Body
200	Successful Response	TaskListResponse
401	Missing or invalid authentication credentials	ErrorResponse
422	Validation Error	HTTPValidationError

POST /api/v1/tasks

Create

Open as a page →

Create a task (agent needs manage_task; owner/humans no-op the gate).

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
Idempotency-Key	header	no	string	Optional.

Request body: application/json — schema TaskCreate

Field	Type	Required	Description
area	string | null	no
assignee_id	integer | null	no
description	string | null	no
spec_ref	string | null	no
title	string	yes

Example:

{
  "area": "platform",
  "assignee_id": 2,
  "description": "Ten key schemas, one example each",
  "spec_ref": "SPEC-NNN",
  "title": "Add request examples to the public contract"
}

Responses:

Code	Meaning	Body
201	Successful Response	TaskRead
401	Missing or invalid authentication credentials	ErrorResponse
422	Validation Error	HTTPValidationError
429	Task intake rate exceeded; retry after the Retry-After seconds	ErrorResponse

Example response (201):

{
  "area": "platform",
  "assignee_id": 2,
  "assignee_name": "Owner",
  "createtime": "2026-09-03T08:00:00Z",
  "description": "Ten key schemas, one example each",
  "guid": 118,
  "owner": 5,
  "spec_ref": "SPEC-NNN",
  "status": "open",
  "title": "Add request examples to the public contract",
  "updatetime": "2026-09-03T08:00:00Z"
}

GET /api/v1/tasks/{guid}

Get Task Endpoint

Open as a page →

One task + its merged change-log (agent actions and notes, time-ordered). Team-only; 404 if absent.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
guid	path	yes	integer

Responses:

Code	Meaning	Body
200	Successful Response	TaskDetailRead
401	Missing or invalid authentication credentials	ErrorResponse
422	Validation Error	HTTPValidationError

Example response (200):

{
  "area": "platform",
  "assignee_id": 2,
  "assignee_name": "Owner",
  "createtime": "2026-09-03T08:00:00Z",
  "description": "Ten key schemas, one example each",
  "guid": 118,
  "owner": 5,
  "spec_ref": "SPEC-NNN",
  "status": "open",
  "title": "Add request examples to the public contract",
  "updatetime": "2026-09-03T08:00:00Z"
}

PATCH /api/v1/tasks/{guid}

Patch

Open as a page →

Change status (open↔closed) / reassign / edit; logs each field change.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
guid	path	yes	integer
Idempotency-Key	header	no	string	Optional.

Request body: application/json — schema TaskPatch

Field	Type	Required	Description
area	string | null	no
assignee_id	integer | null	no
description	string | null	no
spec_ref	string | null	no
status	"open" | "closed" | null	no
title	string | null	no

Example:

{
  "description": "Done: examples added to 17 request schemas",
  "status": "closed"
}

Responses:

Code	Meaning	Body
200	Successful Response	TaskRead
401	Missing or invalid authentication credentials	ErrorResponse
409	Illegal status transition (e.g. closing an already-closed task)	ErrorResponse
422	Validation Error	HTTPValidationError

Example response (200):

{
  "area": "platform",
  "assignee_id": 2,
  "assignee_name": "Owner",
  "createtime": "2026-09-03T08:00:00Z",
  "description": "Ten key schemas, one example each",
  "guid": 118,
  "owner": 5,
  "spec_ref": "SPEC-NNN",
  "status": "open",
  "title": "Add request examples to the public contract",
  "updatetime": "2026-09-03T08:00:00Z"
}

POST /api/v1/tasks/{guid}/notes

Add Task Note

Open as a page →

Append a free-text note to the task’s log (stored as a comment).

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
guid	path	yes	integer
Idempotency-Key	header	no	string	Optional.

Request body: application/json — schema TaskNoteIn

Field	Type	Required	Description
body_markdown	string	yes

Example:

{
  "body_markdown": "Verified live: `/api/` answers with the machine map."
}

Responses:

Code	Meaning	Body
201	Successful Response	object
401	Missing or invalid authentication credentials	ErrorResponse
422	Validation Error	HTTPValidationError
429	Task intake rate exceeded; retry after the Retry-After seconds	ErrorResponse