Automation API V1

Automation API cho phép AI, CLI và CI quản trị Nexus qua HTTP mà không cần thao tác trên giao diện Web.

Tạo API key

1. Đăng nhập bằng tài khoản Admin công ty hoặc Super Admin.
2. Mở /security/api-keys.
3. Chọn tên key, ngày hết hạn và các quyền cần dùng.
4. Sao chép secret ngay khi Nexus hiển thị.

Secret chỉ hiển thị một lần

Nexus chỉ lưu bản băm của API key. Không ghi secret vào source code, tài liệu, log hoặc Git.

Địa chỉ API

Môi trường	Base URL
Production	https://nexus.genium.one
Local	http://127.0.0.1:8021

Các ví dụ dưới đây dùng biến môi trường để tránh đưa secret vào lịch sử lệnh:

export NEXUS_URL="https://nexus.genium.one"
export NEXUS_API_KEY="nxk_live_..."
export EMPLOYEE_ID="00000000-0000-4000-8000-000000000011"

Xác thực

Gửi API key bằng Bearer authentication:

curl --fail-with-body \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  "$NEXUS_URL/api/v1/me"

GET /api/v1/me trả công ty, nhân viên, vai trò và scope hiệu lực của key. Hãy gọi endpoint này trước khi chạy automation để xác nhận đúng tài khoản và quyền.

Key mất hiệu lực ngay khi hết hạn, bị thu hồi, tài khoản bị khóa hoặc vai trò không còn cấp scope tương ứng.

OpenAPI

Contract máy đọc được công khai tại:

curl --fail-with-body "$NEXUS_URL/api/v1/openapi.json"

OpenAPI liệt kê method, path và x-nexus-scope cần thiết cho từng endpoint.

Cách đọc ví dụ curl

Option	Khi dùng
--fail-with-body	Trả exit code lỗi nhưng vẫn giữ JSON lỗi từ Nexus.
-X / --request	Chọn method POST, PUT, PATCH hoặc DELETE. GET không cần khai báo.
-H / --header	Gửi Bearer key, JSON content type và Idempotency-Key.
-d / --data	Gửi JSON request body.
-F / --form	Upload file ZIP Workflow hoặc Skill.

Request GET không cần Idempotency-Key. Super Admin có thêm endpoint quản lý công ty, nội dung, Package và MCP nếu key được cấp đúng scope.

Thay đổi dữ liệu

Mọi request POST, PUT, PATCH và DELETE bắt buộc có Idempotency-Key duy nhất cho một thao tác nghiệp vụ.

curl --fail-with-body \
  -X PATCH \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: employee-profile-42-20260811" \
  -d '{"display_name":"Nguyễn Văn A","email":"a@example.com","phone":"","address":"","gender":""}' \
  "$NEXUS_URL/api/v1/employees/$EMPLOYEE_ID/profile"

Khi retry cùng method, path, body và Idempotency-Key, Nexus trả lại kết quả đã lưu. Nếu tái sử dụng key đó cho nội dung khác, Nexus trả 409.

Có thể tạo idempotency key ngẫu nhiên bằng công cụ hệ điều hành:

IDEMPOTENCY_KEY="$(uuidgen)"

API reference

• Nhân viên
• Vai trò
• Package
• Workflow và Skill
• MCP và Tool
• Công ty

Mỗi trang ghi rõ method, URL, scope, body và ví dụ curl. Đọc /api/v1/openapi.json khi AI cần contract máy đọc được.

Mã lỗi thường gặp

HTTP	Ý nghĩa	Cách xử lý
400	Input hoặc Idempotency-Key không hợp lệ	Kiểm tra body, header và contract OpenAPI.
401	Key thiếu, sai, hết hạn hoặc đã bị thu hồi	Tạo key mới hoặc kiểm tra biến môi trường.
403	Key không có scope hoặc tài khoản không còn capability	Cấp đúng vai trò rồi tạo key với scope cần dùng.
404	Resource không tồn tại hoặc không thuộc phạm vi công ty	Kiểm tra ID và tài khoản đang gọi.
409	Xung đột dữ liệu hoặc idempotency	Không tái sử dụng Idempotency-Key cho request khác.

Response lỗi có dạng JSON và chứa mã lỗi ổn định để automation xử lý.

Thu hồi key

Mở /security/api-keys, chọn key và xác nhận Thu hồi. Các request mới dùng key đó sẽ nhận 401 ngay lập tức.

Nên dùng một key riêng cho mỗi AI, CLI hoặc CI; chỉ cấp scope cần thiết và đặt thời hạn ngắn nhất phù hợp.

Chạy tài liệu

bun run docs:dev

Build bản tĩnh:

bun run docs:build

Chạy smoke test toàn bộ Automation API bằng curl trên PostgreSQL, R2 và MCP mock tạm:

bun run test:api-curl

Script tự tạo rồi xóa database test; không gọi production.