API hay dùng

Tra cứu các endpoint hay dùng cho task, plan, Space và Wiki — kèm quyền tối thiểu, shape lỗi chung và ví dụ curl copy-paste được.

Thay <host>, <spaceId>, <taskId> bằng giá trị thật. Ma trận quyền của từng endpoint: Phân quyền Board.

Quy ước chung: xác thực & shape lỗi

Request/response đều JSON. Lỗi luôn có dạng { "error": "<message>" } kèm status code (§ Lỗi hay gặp).
Triển khai đặt API_KEY thì mọi route /api/* (trừ GET /api/health) yêu cầu header Authorization: Bearer <token> — thiếu/sai token trả 401 { "error": "unauthorized" }.
Danh tính human (approve, Human Gate) do lớp biên ngoài cấp (Cloudflare Access / reverse proxy tin cậy), không tự nhận qua header — role theo Space đọc từ database.

thông tin

Môi trường dev (NODE_ENV khác production, gọi qua loopback) có thể bật danh tính giả bằng AGENTBOARD_DEV_IDENTITY=1 rồi gửi kèm x-mock-user-email / x-mock-user-role (viewer|member|admin). Production từ chối khởi động nếu bật cờ này.

# Danh tính của tôi — kiểm tra server đang nhìn mình là ai
curl -s http://<host>/api/me | jq .
# → { "actor": { "id": "human:ban@cty.vn", "type": "human",
#                "name": "ban", "email": "ban@cty.vn", "role": "member" } }
# Chưa đăng nhập (fail closed): { "actor": { "id": "system", "type": "system", ... } }

# Health check công khai, không cần auth — dùng cho script giám sát
curl -s http://<host>/api/health
# → { "status": "ok", "timestamp": 1735689600000 }

Task & agent (member+; approve/rework cần admin + human)

Việc	Endpoint
Liệt kê / tạo task	`GET·POST /api/tasks?projectId=<spaceId>`
Tạo task hàng loạt	`POST /api/tasks/batch` (kiểm quyền mọi Space tham chiếu)
Chạy / dừng agent	`POST /api/tasks/:id/run` · `POST /api/tasks/:id/stop`
Nhắn cho agent đang chạy	`POST /api/tasks/:id/message` (tab Follow-up)
Ghi checks (lint/test/typecheck)	`POST /api/tasks/:id/checks`
Xem verdict / activities / events	`GET /api/tasks/:id/reviews` · `.../activities` · `.../events?since=<ms>&limit=<n>`
Approve / Request Changes	`POST /api/tasks/:id/approve` · `POST /api/tasks/:id/rework` (body tùy chọn `{"note":"..."}`; approve đặt task `done` + `reviewState: approved`)
Dọn worktree bẩn	`POST /api/tasks/:id/cleanup-worktree`
Archive (thay Delete)	`PATCH /api/tasks/:id/archive`
Quan hệ phụ thuộc (cùng Space)	`POST /api/tasks/<blocker>/links {"targetTaskId":"<task>","linkType":"blocks"}` (`linkType`: `blocks`, `is_blocked_by`, `relates_to`; tạo mới trả 201)
Agent khả dụng trên PATH	`GET /api/agents`

Plan, Group, Template

Việc	Endpoint
Tạo / sửa plan	`POST·PATCH /api/plans*`
Apply Plan (1 transaction)	`POST /api/plans/:id/apply`
Tạo / chạy / dừng Group	`POST /api/groups*` · `POST /api/groups/:id/run` · `POST /api/groups/:id/stop`
Template dùng lại	`GET·POST /api/templates`

Space & Wiki

Việc	Endpoint
Tạo Space (người tạo thành `owner`)	`POST /api/projects`
Sửa / xoá Space	`PATCH·DELETE /api/projects/:id` (owner; không xoá được Space `default`)
Quản thành viên	`GET·POST /api/spaces/:id/members` (`{"email":"...","role":"member"}`; `role`: `viewer`, `member`, `admin`, `owner`; mới trả 201, trùng trả 200) · `DELETE /api/spaces/:id/members/:email` (owner; 409 nếu xoá owner cuối)
Ghi / duyệt Wiki draft	`POST /api/wiki/drafts` (member) · `POST /api/wiki/drafts/:id/approve?projectId=<spaceId>` / `.../reject` (admin + human; `projectId` bắt buộc — thiếu trả 400; reject nhận thêm `{"note":"..."}`)
Danh tính của tôi	`GET /api/me` (xem § Quy ước chung)

Cờ tính năng & realtime theo Space

Việc	Endpoint
Xem cờ server đang bật (palette, mention-subtask, auto-retro, ws-topics, …)	`GET /api/features` (trả boolean thuần, không lộ giá trị cấu hình)
Vào / rời phòng realtime của Space qua WebSocket `/ws`	Gửi `{ "type": "subscribe", "spaceId": "<spaceId>" }` → nhận `{ "type": "subscribed", ... }`; rời bằng `{ "type": "unsubscribe", ... }`

# Sysadmin kiểm cờ trong container (server là nguồn chân lý, client chỉ đọc)
docker exec agentjira_server sh -c 'env | grep AGENTBOARD_'
# Triển khai có API_KEY thì thêm header: -H "Authorization: Bearer $API_KEY"
curl -s http://<host>/api/features | jq .

Ví dụ: gắn quan hệ chặn + approve kèm ghi chú

# 1. Đánh dấu task B bị task A chặn (cùng Space; sai linkType trả 400)
curl -s -X POST http://<host>/api/tasks/<taskA>/links \
  -H 'Content-Type: application/json' \
  -d '{"targetTaskId":"<taskB>","linkType":"blocks"}' | jq .
# → { "id": "...", "sourceTaskId": "<taskA>",
#     "targetTaskId": "<taskB>", "linkType": "blocks", ... } (201 nếu mới tạo)

# 2. Approve kèm ghi chú (chỉ human; agent/system nhận 403 Human Gate)
curl -s -X POST http://<host>/api/tasks/<taskId>/approve \
  -H 'Content-Type: application/json' \
  -d '{"note":"Đã review diff, OK để merge"}' | jq '{success, reviewState: .task.reviewState}'
# → { "success": true, "reviewState": "approved" }

Chỉ có API, chưa có giao diện

Hai nhóm dưới đây tồn tại đầy đủ ở tầng API nhưng chưa có màn hình nào trong Board — muốn dùng thì gọi API. Ghi ở đây để bạn khỏi đi tìm nút không tồn tại.

Nhóm	Endpoint	Dùng để làm gì
Agent Profile	`GET·POST /api/agent-profiles` `GET·PATCH·DELETE /api/agent-profiles/:id`	Bộ cấu hình tái dùng cho một kiểu agent: `displayName`, `role`, `skills[]`, `systemPrompt` riêng, cờ `isDefault`. Thay vì dán cùng một đoạn hướng dẫn vào mọi task
Template task	`GET·POST /api/templates` `GET·PATCH·DELETE /api/templates/:id`	Lưu sẵn mô tả + acceptance criteria + loại agent cho việc lặp lại

# Tạo một agent profile
curl -X POST http://<host>/api/agent-profiles \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "backend-reviewer",
    "displayName": "Backend Reviewer",
    "role": "reviewer",
    "skills": ["typescript", "postgres"],
    "systemPrompt": "Soát kỹ transaction và xử lý lỗi. Không đề xuất đổi kiến trúc."
  }'

# Xem danh sách (tra id để gán)
curl -s http://<host>/api/agent-profiles | jq '.[] | {id, name, isDefault}'

Tên trùng trả 409. isDefault là bất biến sau khi tạo (400 isDefault is immutable). Cách dùng template cho việc lặp: Tổ chức công việc dài hạn.

Lỗi hay gặp

Bảng đầy đủ mọi mã lỗi kèm thông điệp gốc, sắp theo mã HTTP: Mã lỗi API.

Bốn mã bạn gặp nhiều nhất khi gọi các endpoint ở trang này:

Status	Nghĩa	Xử lý nhanh
`400`	Thiếu hoặc sai tham số	Đọc `error` — nó nói đúng trường nào sai
`403`	Không đủ quyền, hoặc actor không phải human	Phân quyền Board; Human Gate không có bypass
`404`	Sai id, hoặc tài nguyên đã archive	Task archive vẫn tồn tại — bật `Show Archived`
`409`	Thao tác đúng nhưng sai thời điểm	Kiểm trạng thái hiện tại rồi thử lại

Đi tiếp: Mã lỗi API · Phân quyền Board · Tạo task và chạy agent

Quy ước chung: xác thực & shape lỗi​

Task & agent (member+; approve/rework cần admin + human)​

Plan, Group, Template​

Space & Wiki​

Cờ tính năng & realtime theo Space​

Ví dụ: gắn quan hệ chặn + approve kèm ghi chú​

Chỉ có API, chưa có giao diện​

Lỗi hay gặp​