openapi: 3.0.3
info:
title: VIETAL — Agent API
version: "1.1"
description: |
API cho AI Agent làm việc từ xa trên hệ thống quản trị dự án VIETAL.
Xác thực: Bearer token (vtk_...) do quản trị viên cấp tại /project/agents.
Giới hạn: 120 request/phút/token; tệp ≤ 25 MB.
contact:
name: VIETAL project management
url: https://dv.badt.vn/project
servers:
description: Production (Internet)
security:
tags:
paths:
/ping:
get:
tags: [bootstrap]
summary: Kiểm tra token
responses:
"200": { description: OK }
"401": { $ref: "#/components/responses/Unauthorized" }
/workspace:
get:
tags: [bootstrap]
summary: Gói khởi động cho agent
parameters:
responses:
"200":
description: Việc được giao, yêu cầu, job, nguồn lực, quy trình
content:
application/json:
schema:
type: object
properties:
ok: { type: boolean }
workspace: { $ref: "#/components/schemas/Workspace" }
/projects:
get:
tags: [bootstrap]
summary: Danh sách dự án
responses: { "200": { description: OK } }
/projects/{code}/summary:
get:
tags: [bootstrap]
summary: KPI + mốc của dự án
parameters:
responses: { "200": { description: OK } }
/tasks:
get:
tags: [tasks]
summary: Danh sách công việc
parameters:
responses: { "200": { description: OK } }
/tasks/{id}/context:
get:
tags: [tasks]
summary: Ngữ cảnh đầy đủ của một việc
parameters:
responses:
"200": { description: task + indicators + evidence + events + logs }
"404": { description: Không tìm thấy việc }
/tasks/{id}/claim:
post:
tags: [tasks]
summary: Giữ việc (lease) — 409 nếu agent khác đang giữ
parameters:
requestBody:
content:
application/json:
schema:
type: object
properties:
ttl_minutes: { type: integer, default: 120, minimum: 15, maximum: 1440 }
note: { type: string }
responses:
"200": { description: "Trả claim_token + expires_at" }
"409": { description: already_claimed }
/tasks/{id}/release:
post:
tags: [tasks]
summary: Trả việc
parameters:
responses: { "200": { description: OK }, "409": { description: not_owner } }
/tasks/{id}/progress:
post:
tags: [tasks]
summary: Cập nhật tiến độ/trạng thái
parameters:
requestBody:
content:
application/json:
schema:
type: object
properties:
status: { type: string, enum: [backlog, todo, doing, review, done, blocked] }
progress: { type: integer, minimum: 0, maximum: 100 }
message: { type: string }
responses: { "200": { description: OK } }
/tasks/{id}/deliverable:
post:
tags: [tasks]
summary: Nộp kết quả (JSON markdown hoặc multipart file)
parameters:
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [title]
properties:
title: { type: string }
content: { type: string, description: Markdown }
summary: { type: string }
kind: { type: string, enum: [report, minutes, artifact, document, image, other] }
multipart/form-data:
schema:
type: object
properties:
title: { type: string }
kind: { type: string }
summary: { type: string }
file: { type: string, format: binary }
responses:
"200": { description: "evidence_id + task.status=review" }
"422": { description: missing_content / upload_failed }
/tasks/{id}:
get:
summary: Chi tiết một công việc (thuộc tính, việc con, tài chính, minh chứng)
parameters:
responses: { '200': { description: OK } }
post:
summary: Cập nhật thuộc tính công việc
parameters:
requestBody:
content:
application/json:
schema:
type: object
properties:
status: { type: string, enum: [backlog, todo, doing, review, done, blocked] }
progress: { type: integer, minimum: 0, maximum: 100 }
due_date: { type: string, format: date }
start_date: { type: string, format: date }
location: { type: string }
deliverables: { type: string }
note: { type: string, description: "ghi chú nối thêm vào mô tả" }
est_cost: { type: number }
responses: { '200': { description: OK } }
/tasks/{id}/cost:
post:
summary: Ghi khoản chi/thu/cam kết gắn với công việc
parameters:
requestBody:
content:
application/json:
schema:
type: object
required: [amount]
properties:
amount: { type: number }
currency: { type: string, enum: [EUR, VND, USD] }
kind: { type: string, enum: [income, expense, commitment] }
date: { type: string, format: date }
description: { type: string }
category: { type: string }
ref_no: { type: string }
responses: { '200': { description: OK } }
/events:
post:
summary: Thêm sự kiện (cuộc họp, tập huấn, báo cáo)
requestBody:
content:
application/json:
schema:
type: object
required: [title]
properties:
title: { type: string }
date: { type: string, format: date }
time: { type: string, description: "HH:MM" }
kind: { type: string, enum: [meeting, training, report, other] }
location: { type: string }
participants: { type: string }
notes: { type: string }
project: { type: string }
responses: { '200': { description: OK } }
/requests/{id}/answer:
post:
summary: Trả lời một yêu cầu
parameters:
requestBody:
content:
application/json:
schema:
type: object
required: [answer]
properties:
answer: { type: string }
status: { type: string, enum: [answered, closed] }
responses: { '200': { description: OK } }
/intake:
post:
summary: Phân tích văn bản thô (apply=false chỉ trả kế hoạch, không ghi)
requestBody:
content:
application/json:
schema:
type: object
required: [text]
properties:
text: { type: string }
project: { type: string }
apply: { type: boolean, default: false }
force: { type: boolean, description: "bỏ qua kiểm tra dán trùng" }
responses:
'200': { description: "intake{id,status,model,preview{changes,warnings},applied,skipped,duplicate}" }
'202': { description: "Đã xếp hàng (apply=false, chế độ cũ)" }
get:
summary: Danh sách bản tiếp nhận gần đây
responses: { '200': { description: OK } }
/intake/{id}:
get:
summary: Chi tiết một bản tiếp nhận (analysis, preview, snapshot, warnings)
parameters:
responses: { '200': { description: OK } }
/intake/{id}/apply:
post:
summary: Duyệt ghi kế hoạch đã phân tích
parameters:
responses: { '200': { description: OK } }
/intake/{id}/revert:
post:
summary: Hoàn tác một lần ghi tiếp nhận
parameters:
responses: { '200': { description: OK } }
/requests:
get:
tags: [requests]
summary: Yêu cầu dành cho agent
parameters:
responses: { "200": { description: OK } }
post:
tags: [requests]
summary: Agent hỏi / báo vướng mắc / đề xuất
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [title]
properties:
title: { type: string }
body: { type: string }
kind: { type: string, enum: [question, blocker, request, review] }
priority: { type: string, enum: [low, normal, high] }
project: { type: string }
task_id: { type: integer }
responses: { "200": { description: request_id } }
/requests/{id}/accept:
post:
tags: [requests]
summary: Nhận một yêu cầu chung
parameters:
responses: { "200": { description: accepted }, "409": { description: assigned_other } }
/resources:
get:
tags: [resources]
summary: Danh mục nguồn lực (LLM/OCR/ASR/TTS) + token dịch vụ nếu scope=write
responses: { "200": { description: OK } }
/resources/{code}/check:
post:
tags: [resources]
summary: Kiểm tra sức khoẻ một nguồn lực
parameters:
responses: { "200": { description: "health: {ok, code, ms}" } }
/docs:
get:
tags: [docs]
summary: Danh mục tài liệu kỹ thuật (slug + URL công khai)
responses: { "200": { description: OK } }
/docs/{slug}:
get:
tags: [docs]
summary: Nội dung một tài liệu kỹ thuật (markdown)
parameters:
responses: { "200": { description: OK }, "404": { description: doc_not_found } }
/documents:
get:
tags: [documents]
summary: Tìm tài liệu dự án (minh chứng) theo từ khoá
parameters:
responses: { "200": { description: OK } }
/documents/{id}:
get:
tags: [documents]
summary: Nội dung text đã bóc của tài liệu (PDF/DOCX/ảnh)
parameters:
responses:
"200": { description: "{method, cached, chars, text}" }
"404": { description: evidence_not_found }
/documents/{id}/extract:
post:
tags: [documents]
summary: Bóc lại nội dung tài liệu
parameters:
responses: { "200": { description: "{method, chars, text}" } }
/evidence/{id}/file:
get:
tags: [evidence]
summary: Tải tệp nguồn
parameters:
responses:
"200": { description: Tệp nhị phân }
"404": { description: evidence_not_found }
/evidence:
post:
tags: [evidence]
summary: Tải minh chứng (multipart hoặc base64)
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
project: { type: string }
kind: { type: string }
title: { type: string }
file: { type: string, format: binary }
application/json:
schema:
type: object
properties:
project: { type: string }
kind: { type: string }
title: { type: string }
filename: { type: string }
content_base64: { type: string }
responses: { "200": { description: evidence_id } }
/indicators:
get:
tags: [indicators]
summary: Danh sách chỉ số + giá trị hiện tại
parameters:
responses: { "200": { description: OK } }
/indicators/{code}:
post:
tags: [indicators]
summary: Ghi giá trị chỉ số
parameters:
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [value]
properties:
value: { type: number }
note: { type: string }
responses: { "200": { description: OK } }
/logs:
post:
tags: [logs]
summary: Ghi nhật ký xử lý
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [project, message]
properties:
project: { type: string }
action: { type: string }
message: { type: string }
task_id: { type: integer }
payload: { type: object }
responses: { "200": { description: OK } }
/reports:
post:
tags: [logs]
summary: Nộp báo cáo (lưu thành minh chứng .md)
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [project, content]
properties:
project: { type: string }
title: { type: string }
content: { type: string }
kind: { type: string }
task_id: { type: integer }
responses: { "200": { description: evidence_id } }
/jobs:
get:
tags: [tasks]
summary: Việc trong hàng đợi
parameters:
responses: { "200": { description: OK } }
post:
tags: [tasks]
summary: Agent đề xuất việc mới
requestBody:
content:
application/json:
schema:
type: object
required: [title]
properties:
title: { type: string }
instruction: { type: string }
project: { type: string }
responses: { "200": { description: job_id } }
/jobs/{id}:
post:
tags: [tasks]
summary: Báo trạng thái/kết quả job
parameters:
requestBody:
content:
application/json:
schema:
type: object
properties:
status: { type: string, enum: [queued, running, done, failed, cancelled] }
result: { type: string }
tokens_in: { type: integer }
tokens_out: { type: integer }
responses: { "200": { description: OK } }
/heartbeat:
post:
tags: [bootstrap]
summary: Duy trì trạng thái agent (mỗi 5 phút)
requestBody:
content:
application/json:
schema:
type: object
properties:
status: { type: string, enum: [active, paused, offline] }
note: { type: string }
responses: { "200": { description: OK } }
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: vtk_<48 hex>
responses:
Unauthorized:
description: missing_token / invalid_token / expired / revoked
schemas:
Workspace:
type: object
properties:
agent_id: { type: integer }
project: { type: object }
stats: { type: object }
tasks: { type: array, items: { type: object } }
requests: { type: array, items: { type: object } }
jobs: { type: array, items: { type: object } }
resources: { type: array, items: { type: object } }
protocol: { type: object }