OPS Proxy API Specification
OPS Proxy API Specification
v3.0 | 2026-03-02 (OPS-SPEC-SLIM ✅ HOÀN THÀNH — 19 ops, 7 collections) Đọc:
search_knowledge("OPS proxy API spec")
Overview
OPS Proxy cung cấp CRUD access tới Directus collections cho AI agents (GPT, Codex) qua nginx reverse proxy. Agents có STDIO MCP (Claude Code, Gemini) dùng Directus MCP trực tiếp, KHÔNG qua OPS Proxy.
Base URL
https://ops.incomexsaigoncorp.vn
OpenAPI Specs
| Spec | URL | Dùng cho | Operations |
|---|---|---|---|
| Full (23 collections) | https://ops.incomexsaigoncorp.vn/openapi.json |
Codex CLI | 105 ops |
| Council (7 collections) | https://ops.incomexsaigoncorp.vn/openapi-council.json |
GPT Hội đồng AI | 19 ops |
⚠️ GPT Actions giới hạn 30 ops/spec. GPT PHẢI dùng spec Council, KHÔNG dùng spec Full.
Trạng thái OPS-SPEC-SLIM (2026-03-02): ✅ HOÀN THÀNH
- ✅ File
openapi-council.json: DEPLOYED (PR #409 + #410 + #411 + #412) - ✅ Serve trên nginx: LIVE
- ✅ 7 collections, 19 ops (11 paths) — ALL verified 200
- ✅ PATCH tasks + POST ai_tasks: verified (PR #411 + #412)
- ⏳ GPT import: CHƯA — User manual, sẵn sàng import
Authentication
Tất cả requests cần header X-API-Key. Key cấu hình trong GPT Actions auth hoặc env var.
Rate Limiting
- Zone:
ops_limit(10 req/s per IP) - Burst: 20 requests with
nodelay
Collections — Phân nhóm theo GPT
GPT Hội đồng AI (spec Council — 7 collections, 19 ops)
| Collection | GET list | GET by id | POST | PATCH | DELETE | Mục đích |
|---|---|---|---|---|---|---|
| tasks | ✅ | ✅ | — | ✅ | — | Đọc + cập nhật nhiệm vụ |
| task_comments | ✅ | ✅ | ✅ | ✅ | ✅ | Comment, phản biện, thảo luận |
| ai_tasks | ✅ | ✅ | ✅ | ✅ | — | Điều hành + tạo agent tasks |
| posts | ✅ | ✅ | ✅ | ✅ | — | Soạn kế hoạch, bài viết |
| pages | ✅ | — | — | — | — | Đọc cấu trúc trang |
| navigation | ✅ | — | — | — | — | Đọc menu |
| globals | ✅ | — | — | — | — | Đọc cấu hình chung |
✅ 19 ops deployed. 37% headroom dưới giới hạn 30.
Bảng Nhiệm vụ → Endpoint (điểm danh đầy đủ)
| # | Nhiệm vụ GPT Council | Endpoint | Verified |
|---|---|---|---|
| — | COMMENT & PHẢN BIỆN | ||
| 1 | Đọc comments của task | GET /items/task_comments?filter[task_id] | ✅ |
| 2 | Đọc 1 comment | GET /items/task_comments/{id} | ✅ |
| 3 | Tạo comment (phản biện) | POST /items/task_comments | ✅ |
| 4 | Sửa comment | PATCH /items/task_comments/{id} | ✅ |
| 5 | Xóa comment | DELETE /items/task_comments/{id} | ✅ |
| — | QUẢN LÝ NHIỆM VỤ | ||
| 6 | Xem danh sách tasks | GET /items/tasks | ✅ |
| 7 | Đọc chi tiết task | GET /items/tasks/{id} | ✅ |
| 8 | Cập nhật nội dung task | PATCH /items/tasks/{id} | ✅ |
| — | ĐIỀU HÀNH AGENTS | ||
| 9 | Xem AI tasks | GET /items/ai_tasks | ✅ |
| 10 | Đọc AI task | GET /items/ai_tasks/{id} | ✅ |
| 11 | Cập nhật AI task | PATCH /items/ai_tasks/{id} | ✅ |
| 12 | Tạo AI task (giao việc) | POST /items/ai_tasks | ✅ |
| — | SOẠN THẢO | ||
| 13 | Xem bài viết/kế hoạch | GET /items/posts | ✅ |
| 14 | Đọc bài viết | GET /items/posts/{id} | ✅ |
| 15 | Tạo bài viết | POST /items/posts | ✅ |
| 16 | Sửa bài viết | PATCH /items/posts/{id} | ✅ |
| — | ĐỌC CONTEXT | ||
| 17 | Đọc cấu trúc trang | GET /items/pages | ✅ |
| 18 | Đọc menu | GET /items/navigation | ✅ |
| 19 | Đọc cấu hình site | GET /items/globals | ✅ |
GPT Khách hàng (spec riêng — CHƯA TẠO, tầm nhìn)
| Collection | Mục đích |
|---|---|
| contacts | Quản lý khách hàng |
| help_articles | Bài hướng dẫn |
| help_collections | Nhóm bài |
| inbox | Tin nhắn |
| forms_submissions | Form khách gửi |
Codex CLI (spec Full — 23 collections)
Codex dùng spec Full vì chạy qua curl, không bị giới hạn 30 ops. 23 collections = tasks, task_comments, ai_tasks, posts, pages, contacts, globals, navigation, help_articles, help_collections, redirects, forms, forms_submissions, categories, tags, seo, block_button_group, block_cardgroup, block_columns, block_cta, block_faqs, block_hero, block_richtext.
Field Names Quan Trọng
| Collection | ⚠️ Lưu ý |
|---|---|
| tasks | Dùng name, KHÔNG phải title |
| ai_tasks | Dùng name, KHÔNG phải title |
| task_comments | Required fields: task_id, content, tab_scope, agent_type. Field action phải là "" không phải null |
| posts | Dùng title (khác tasks!) |
Error Responses
| Code | Meaning |
|---|---|
| 403 | Missing/invalid API key, hoặc field không tồn tại/không có permission |
| 404 | Collection không trong whitelist hoặc item không tìm thấy |
| 429 | Rate limit exceeded |
Security
- Nginx validate API key trước khi forward tới Directus
- Directus AI Agent token inject server-side
- CORS enabled cho GPT Actions
- Non-whitelisted paths → 404
Lịch sử
| Ngày | Sự kiện |
|---|---|
| 2026-02-28 | CONN-FINAL: mở rộng 3 → 23 collections |
| 2026-03-01 | PR #407: spec Full expanded |
| 2026-03-02 | OPS-SPEC-SLIM PR #409: spec Council tạo (4 cols, 14 ops) |
| 2026-03-02 | PR #410: bổ sung pages/navigation/globals (7 cols, 17 ops) |
| 2026-03-02 | PR #411+#412: v3 — PATCH tasks + POST ai_tasks (7 cols, 19 ops) ✅ HOÀN THÀNH |
v3.0 | 2026-03-02