← Danh mục tài liệu · raw markdown

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 }