itasks

🔌 API Reference

API workspace-scoped cho agent CRUD project & task. Base URL: https://tasks.chuyen.dev.

Authentication

Token được tạo từ Admin → Workspaces → Edit → API Tokens. Token có prefix ws_ và hiển thị một lần duy nhất khi tạo — hãy lưu ngay. Mọi request đều cần 2 header:

Authorization: Bearer ws_xxxxxxxx
Content-Type: application/json

Sample — tạo token & gọi API

# 1. Tạo token trong Admin → Workspaces → Edit → API Tokens
#    → nhận token dạng ws_xxxxxxxx...

# 2. Lưu vào biến môi trường (không hardcode trong code)
export ITASKS_TOKEN=ws_xxxxxxxx

# 3. Dùng trong mọi request
curl -H "Authorization: Bearer $ITASKS_TOKEN" \
  https://tasks.chuyen.dev/api/workspace/1/projects

Endpoints — Projects

Project payload (create / update)

{
  "name": "Project Name",
  "description": "Optional description",
  "status": "open",
  "priority": "p1",
  "due_date": "2026-08-01"
}

Sample — POST create project

Request:

curl -X POST -H "Authorization: Bearer $ITASKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Website Redesign","priority":"p1","due_date":"2026-08-01"}' \
  https://tasks.chuyen.dev/api/workspace/1/projects

Response 201 Created:

{
  "id": 12,
  "name": "Website Redesign",
  "slug": "website-redesign",
  "description": null,
  "status": "open",
  "priority": "p1",
  "due_date": "2026-08-01",
  "created_by": 1,
  "created_at": "2026-08-12T03:50:00.000000Z",
  "updated_at": "2026-08-12T03:50:00.000000Z",
  "deleted_at": null,
  "tasks": [],
  "creator": { "id": 1, "name": "Khoi Nguyen", "email": "[email protected]" }
}

Sample — GET list projects

Request:

curl -H "Authorization: Bearer $ITASKS_TOKEN" \
  https://tasks.chuyen.dev/api/workspace/1/projects

Response 200 OK — mảng các project, mỗi project kèm tasks và creator:

[
  {
    "id": 12,
    "name": "Website Redesign",
    "slug": "website-redesign",
    "status": "open",
    "priority": "p1",
    "due_date": "2026-08-01",
    "tasks": [
      { "id": 55, "title": "Fix login bug", "status": "open" }
    ],
    "creator": { "id": 1, "name": "Khoi Nguyen" }
  }
]

Endpoints — Tasks

Task payload (create / update)

{
  "title": "Task title",
  "description": "Optional description",
  "project_id": 1,
  "status": "open",
  "priority": "p1",
  "deadline": "2026-08-01",
  "estimation_hours": 2.5
}

Sample — POST create task

Request:

curl -X POST -H "Authorization: Bearer $ITASKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Fix login bug","project_id":12,"priority":"p1","estimation_hours":2.5}' \
  https://tasks.chuyen.dev/api/workspace/1/tasks

Response 201 Created:

{
  "id": 55,
  "project_id": 12,
  "title": "Fix login bug",
  "description": null,
  "status": "open",
  "priority": "p1",
  "assignee_id": null,
  "deadline": null,
  "estimation_hours": "2.5",
  "created_by": 1,
  "completed_at": null,
  "created_at": "2026-08-12T04:00:00.000000Z",
  "updated_at": "2026-08-12T04:00:00.000000Z",
  "deleted_at": null,
  "project": { "id": 12, "name": "Website Redesign", "slug": "website-redesign" },
  "assignee": null,
  "creator": { "id": 1, "name": "Khoi Nguyen" }
}

Sample — PUT update task status → done

Request:

curl -X PUT -H "Authorization: Bearer $ITASKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"done"}' \
  https://tasks.chuyen.dev/api/workspace/1/tasks/55

Response 200 OK — status: done tự ghi completed_at:

{
  "id": 55,
  "project_id": 12,
  "title": "Fix login bug",
  "status": "done",
  "priority": "p1",
  "completed_at": "2026-08-12T05:12:30.000000Z",
  "updated_at": "2026-08-12T05:12:30.000000Z",
  "project": { "id": 12, "name": "Website Redesign" },
  "assignee": null,
  "creator": { "id": 1, "name": "Khoi Nguyen" }
}

Field validation

Status lifecycle

Khi đặt status: done, hệ thống tự ghi completed_at. Khi chuyển về open/in_progress, completed_at bị xóa.

Error cases (failure)

Mọi lỗi đều trả JSON dạng {"message": "..."}. Lỗi validation trả thêm mảng errors.

401 — Thiếu hoặc sai token

curl -H "Authorization: Bearer ws_wrongtoken" \
  https://tasks.chuyen.dev/api/workspace/1/projects

401 Unauthorized
{
  "message": "Invalid token."
}

403 — Token không thuộc workspace

403 Forbidden
{
  "message": "Token does not belong to this workspace."
}

404 — Project/task không tồn tại trong workspace

404 Not Found
{
  "message": "Project not found in this workspace."
}

422 — Validation error

Khi payload thiếu field bắt buộc hoặc sai giá trị:

curl -X POST -H "Authorization: Bearer $ITASKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://tasks.chuyen.dev/api/workspace/1/projects

422 Unprocessable Entity
{
  "message": "The name field is required.",
  "errors": {
    "name": [ "The name field is required." ]
  }
}

💻 Usage — Quick Start

Các ví dụ dùng token placeholder ws_xxxxxxxx — thay bằng token thật của workspace bạn (xem tab API để biết chi tiết response).

Setup token

export ITASKS_TOKEN=ws_xxxxxxxx

List projects

curl -H "Authorization: Bearer $ITASKS_TOKEN" \
  https://tasks.chuyen.dev/api/workspace/1/projects

Create a project

curl -X POST -H "Authorization: Bearer $ITASKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Website Redesign","priority":"p1"}' \
  https://tasks.chuyen.dev/api/workspace/1/projects

Create a task

curl -X POST -H "Authorization: Bearer $ITASKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Fix login bug","project_id":1,"priority":"p1","estimation_hours":2.5}' \
  https://tasks.chuyen.dev/api/workspace/1/tasks

Update task status → done

curl -X PUT -H "Authorization: Bearer $ITASKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"done"}' \
  https://tasks.chuyen.dev/api/workspace/1/tasks/1

Delete a task

curl -X DELETE -H "Authorization: Bearer $ITASKS_TOKEN" \
  https://tasks.chuyen.dev/api/workspace/1/tasks/1

Status lifecycle

🔒 Bảo mật

itasks áp dụng token per-workspace và kiểm tra quyền ở nhiều lớp để cách ly dữ liệu giữa các team.

Token per workspace

• Mỗi workspace có token riêng, prefix ws_.
• Token chỉ truy cập được dữ liệu trong workspace của chính nó.
• Token được lưu dạng SHA-256 hash trong database — không lưu plaintext.

Scope giới hạn

Mọi endpoint API đều đi qua middleware workspace-token, kiểm tra token thuộc đúng workspace trước khi xử lý. Project/task thuộc workspace khác sẽ bị chặn.

Error codes

⚠️ Lưu ý

• Không bao giờ ghi token thật vào code, docs, hoặc commit.
• Token trong ví dụ luôn dùng placeholder ws_xxxxxxxx.
• Nếu token bị lộ, revoke ngay từ Admin → Workspaces → API Tokens.

❓ FAQ

Các câu hỏi thường gặp khi dùng itasks.

Làm sao để tạo API token?

Vào Admin → Workspaces → Edit → API Tokens và tạo token mới. Token sẽ hiển thị một lần duy nhất — hãy lưu lại ngay.

Token có thể truy cập dữ liệu của workspace khác không?

Không. Token bị scope cứng vào workspace của nó. Truy cập workspace khác trả về 403.

Đặt task thành done thì điều gì xảy ra?

Hệ thống tự ghi completed_at với timestamp hiện tại. Nếu chuyển về open/in_progress, trường này bị xóa.

Task có bắt buộc thuộc một project không?

Có. project_id là bắt buộc khi tạo task, và project phải thuộc cùng workspace với token.

itasks có phải open source không?

Có. Source nằm trên GitLab (mirror từ GitHub codetot-ai/itasks).