DEVELOPER DOCUMENTATION / API v1

Updating work

Update assigned tasks, append progress notes and replace factual actual-effort intervals using the frozen Can You Just v1 contract.

Change planning fields

PATCH /api/v1/tasks/42 requires tasks:update, exact task If-Match and a live claim token when a lease exists. A retry key is optional and recommended. A successful write returns 204 with no response body. Omission preserves fields; null clears supported optional fields. Known-start corrections follow task lifecycle rules; null does not erase established tracking.

Update total planned duration · curl request

curl -i -X PATCH 'https://cyj.example/api/v1/tasks/42' \
  -H "Authorization: Bearer $CYJ_API_TOKEN" \
  -H 'If-Match: "task-42-plan-7"' \
  -H 'Idempotency-Key: example-patch-001' \
  -H 'X-Task-Claim: 22222222-2222-4222-8222-222222222222' \
  -H 'Content-Type: application/json' \
  --data-raw '{"status":"InProgress","estimatedMinutes":90,"description":"Checking the release summary."}'

Fields	Meaning and bounds
title, description	Nonblank title up to 200 characters; optional description up to 20,000.
status	Ready, InProgress or Done. Blocking and completion rules still apply.
sequence	0–100,000; ordering within the plan, not a dependency.
estimatedMinutes	Total planned duration, 0–1,000,000; preferred duration input.
startedAt, earliestStart, releaseDate	Nullable London wall-time fields with lifecycle/domain constraints.
isWaiting	Explicit external-waiting flag; human blocking remains derived.
resourceMode	Independent or Collaboration; existing contributor rules apply.
dependencyIds	Up to 1,000 positive task IDs; cycles and invalid prerequisites are rejected.
actualIntervals	Up to 1,000 own factual intervals; additionally requires tasks:time.
remainingMinutes	Deprecated compatibility input; see below.

Project ownership, priority, targets/deadlines, assignments, identities and source mappings are not editable task fields. See the exact TaskPatch schema for field details. Starting blocked work or completing work with outstanding human blockers can be refused.

Append a note

POST /api/v1/tasks/42/notes requires tasks:notes, current task If-Match and a claim token under a live lease. The nonblank text is at most 20,000 characters. Notes append progress context without replacing the description. Success is 204.

Append a progress note · curl request

curl -i -X POST 'https://cyj.example/api/v1/tasks/42/notes' \
  -H "Authorization: Bearer $CYJ_API_TOKEN" \
  -H 'If-Match: "task-42-plan-7"' \
  -H 'Idempotency-Key: example-note-001' \
  -H 'X-Task-Claim: 22222222-2222-4222-8222-222222222222' \
  -H 'Content-Type: application/json' \
  --data-raw '{"text":"Draft prepared. Waiting for approval."}'

Replace factual actual effort

PUT /api/v1/tasks/42/actual-effort requires tasks:time. Supply actualIntervals as a replacement, never an increment. Describe real past work for the mapped resource. Other contributors’ factual intervals cannot be changed. Success is 204.

Replace factual effort · curl request

curl -i -X PUT 'https://cyj.example/api/v1/tasks/42/actual-effort' \
  -H "Authorization: Bearer $CYJ_API_TOKEN" \
  -H 'If-Match: "task-42-plan-7"' \
  -H 'Idempotency-Key: example-actual-001' \
  -H 'X-Task-Claim: 22222222-2222-4222-8222-222222222222' \
  -H 'Content-Type: application/json' \
  --data-raw '{"actualIntervals":[{"staffMemberId":7,"start":"2026-10-19T09:00:00","end":"2026-10-19T09:20:00"}]}'

These example intervals are fictional and must be replaced with known actual work. Their start/end values use London wall time. Planning or elapsed forecast time does not itself prove actual effort. A task’s calculated remaining duration and factual intervals are different measures.

Strict request shapes

Send one JSON object within 131072 bytes. Unknown members, duplicate members including case variants, invalid typed fields and irrelevant combinations are rejected. Do not overpost a complete task response as PATCH input. Responses include read-only context that is not writable.

Compatibility

remainingMinutes is deprecated. A remaining-only write converts elapsed planned duration plus remainingMinutes into estimatedMinutes; estimatedMinutes wins if both are supplied. The compatibility write returns Warning 299. Prefer estimatedMinutes; response remainingMinutes is calculated from the plan. Read-only numeric project priority is also deprecated in favour of priorityName.

Follow If-Match rules, claim requirements and retry receipts. Re-read after a successful mutation before the next logical write.