API Reference

DXA Orchestration API

Định tuyến mô hình & chạy workflow AI khai báo

DXA Orchestration là lớp middleware đưa AI vào hệ thống Core hiện hữu. Phần API cung cấp bộ định tuyến mô hình (model router) với cơ chế dự phòng tự động trên Workers AI, và một workflow engine chạy pipeline AI khai báo (nhiều bước, có retry và idempotency). Chạy hoàn toàn trên Cloudflare — không cần API key bên ngoài.

Base URL

https://orchestration.dxa.io.vn

Xác thực

Các endpoint hiện công khai (không cần đăng nhập), phù hợp thử nghiệm. Bảo vệ chống lạm dụng ở tầng nền tảng Cloudflare; endpoint lead có thể bật Turnstile.

Bộ định tuyến mô hình

POST /api/route

Định tuyến yêu cầu suy luận tới mô hình phù hợp, tự dự phòng

Xác thực: Không (công khai)

Tham số (body)

Trường	Kiểu	Mô tả
`prompt`*	`string`	Câu hỏi/nội dung (≤600 ký tự)
`difficulty`	`'fast' \| 'balanced' \| 'frontier'`	Cấp độ mô hình (mặc định `balanced`)

Ví dụ yêu cầu

curl -X POST 'https://orchestration.dxa.io.vn/api/route' \
  -H 'Content-Type: application/json' \
  -d '{ "prompt": "Tóm tắt hợp đồng này", "difficulty": "balanced" }'

Phản hồi mẫu

{
  "ok": true,
  "label": "AI cân bằng",
  "model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
  "latencyMs": 1234,
  "answer": "…",
  "hops": [
    { "model": "@cf/meta/llama-3.1-8b-instruct", "status": "error" },
    { "model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast", "status": "ok" }
  ]
}

Mã lỗi

`400 empty_prompt`	Thiếu prompt
`502 all_failed`	Mọi mô hình đều lỗi
`503 ai_unavailable`	Chưa cấu hình Workers AI

Workflow engine

POST /api/wf

Chạy một workflow AI khai báo (nhiều bước, có idempotency)

Xác thực: Không (công khai)

Tham số (body)

Trường	Kiểu	Mô tả
`workflow`*	`string`	Tên workflow đã đăng ký, vd `support-triage`
`input`*	`object`	Dữ liệu đầu vào (vd `{ "message": "…" }`)
`idemKey`	`string`	Khóa idempotency (≤120 ký tự)

Ví dụ yêu cầu

curl -X POST 'https://orchestration.dxa.io.vn/api/wf' \
  -H 'Content-Type: application/json' \
  -d '{ "workflow": "support-triage", "input": { "message": "Tôi chưa nhận được hóa đơn" } }'

Phản hồi mẫu

{
  "ok": true,
  "runId": "…",
  "workflow": "support-triage",
  "status": "done",
  "steps": [
    { "id": "classify", "type": "ai", "status": "ok", "output": "Thanh toán" },
    { "id": "draft", "type": "ai", "status": "ok", "output": "Cảm ơn bạn…" },
    { "id": "record", "type": "connector", "status": "ok" }
  ],
  "result": { "category": "Thanh toán", "reply": "Cảm ơn bạn…" }
}

Mã lỗi

`400 unknown_workflow`	Workflow chưa đăng ký
`400 empty_input`	Thiếu trường đầu vào bắt buộc

GET /api/wf

Lấy trạng thái & các bước của một lần chạy workflow

Xác thực: Không (công khai)

Tham số

Tên	Kiểu	Mô tả
`id`*	`string`	runId trả về khi chạy workflow

Phản hồi mẫu

{
  "ok": true,
  "run": { "run_id": "…", "workflow": "support-triage", "status": "done" },
  "steps": [ { "step_id": "classify", "status": "ok", "latency_ms": 234 } ]
}

Mã lỗi

404 not_found Không tìm thấy lần chạy

Thu thập lead

POST /api/lead

Ghi nhận lead B2B từ form (tuỳ chọn đăng ký newsletter)

Xác thực: Không (công khai, có Turnstile tuỳ chọn)

Tham số (body)

Trường	Kiểu	Mô tả
`name`*	`string`	Họ tên
`email`*	`string`	Email công việc
`company`	`string`	Công ty
`tool`	`string`	Bối cảnh công cụ (mặc định `orchestration`)

Phản hồi mẫu

{ "ok": true }

Mã lỗi

`400 invalid`	Thiếu/không hợp lệ tên hoặc email
`400 personal_email`	Email cá nhân/dùng-một-lần bị chặn