Universal Tiny AI · API Guide

Bắt đầu tích hợp

Operator onboard tenant và cấp scoped API key. Hiện chưa có public signup, login/OIDC hoặc Tenant CRUD API.
Gọi GET /v1/me để kiểm tra tenant/actor/scopes. Gọi GET /v1/capabilities để xem adapter đang cấu hình.
Tạo Agent bằng POST /v1/agents, tạo configuration version, rồi publish với ETag hiện tại.
Gọi POST /v1/agent-runs. API trả202; poll run hoặc theo dõi metadata SSE.
Thêm Skills, memory scopes và reviewed MCP bindings khi cần. Một Skill hoặc MCP server vừa tạo không tự được cấp mọi quyền.

Trong Swagger, chọn Authorize và nhập API key vào Bearer token. Tài liệu công khai; API nghiệp vụ vẫn yêu cầu credential. Swagger không lưu credential vào local storage sau reload.

curl https://open-ai.virtualcallai.io.vn/v1/me \
  -H "Authorization: Bearer $AI_API_KEY"

curl https://open-ai.virtualcallai.io.vn/v1/agent-runs \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-request-001" \
  -d '{"agent_id":"<published-agent-id>","input":{"type":"text","content":"Xin chào"},"model":{"name":"gemini-3.8-flash"}}'

Dùng key có runs:execute, sessions:write và models:select nếu override model. Model phải nằm trong allowlist của server/profile; client không chọn GCP project hoặc gửi ADC.

14 cụm endpoint

API Reference mô tả đủ63 operations: mục đích, scopes, parameters, request schema và response/error schema. Swagger có bộ lọc tên và các nhóm thu gọn.

Health & Platform

Liveness, database readiness và configured capabilities.

Identity, Users

Danh tính hiện tại và external user registry theo tenant.

Organizations, Delegations

Membership, quyền act-on-behalf-of và revoke.

Agent Profiles

Draft, immutable configuration versions và CAS publish.

Agent Runs

Async model execution, model.name động, usage, cancel và SSE.

Sessions

Working messages, single writer và manual summary compaction.

Context Trace

Exact snapshots với source lineage và current authorization.

Skills

Instruction versions, user/Agent bindings, publish/revoke và SKILL.md.

Memory & Graphiti

Canonical CRUD/tombstones, projection jobs và lexical/hybrid retrieval.

Dynamic MCP

HTTP discovery, schema review, binding và read-only invocation ledger.

Artifacts

JSON/base64 upload, metadata, binary download, expiry và purge.

Quy ước request

Trường hợp	Hợp đồng thực tế
Authentication	`Authorization: Bearer <API_KEY>`. Tenant suy ra từ credential; ID trong body không cấp quyền.
Delegated user	`X-On-Behalf-Of`, optional `X-Organization-Id`. Cần grant/membership hợp lệ; không tùy ý impersonate.
JSON	`Content-Type: application/json`, không gzip request. Command/config fields lạ bị reject.
Idempotency	Gửi `Idempotency-Key` khi endpoint yêu cầu. Cùng key nhưng khác payload trả409. Identity/artifact mutations hiện chưa áp dụng đồng đều; xem parameters từng endpoint.
CAS update	Dùng nguyên ETag từ response trong `If-Match`; stale trả412, thiếu precondition trả428. Memory dùng `"memory:N"`. MCP policy/binding dùng revision trong body.
Async	Run trả202 và run_id. Memory write trả202 và job_id khi Graphiti bật. `completed` khác `quarantined` hoặc unknown outcome.
Pagination	Opaque cursor, có expiry và ràng buộc filters/tenant. Dùng next_cursor với cùng bộ lọc.
Streaming	SSE metadata qua `GET /v1/agent-runs/{id}/events`, hỗ trợ `Last-Event-ID`; chưa token streaming.

Lỗi và trạng thái

Lỗi dùng application/problem+json: status, code, detail, request_id. Response có X-Request-ID để đối chiếu log. Không dựa vào chuỗi thông báo để retry một tool có tác dụng phụ.

HTTP	Ý nghĩa thường gặp
401 /403	Key không hợp lệ hoặc thiếu scope/grant. MCP write hiện bị chặn.
404 /410	Resource không thuộc access domain, đã tombstone/purge hoặc dependency bị revoke.
409 /412 /428	Conflict, projection chưa current, unknown invocation hoặc CAS/precondition không đúng.
413 /422	Vượt body budget hoặc command/schema/input không hợp lệ.
429 /502 /503	Quota/capacity/upstream/not ready. Xem projection job/run error_code; không giả định remote operation chưa xảy ra.

Giới hạn và phần chưa hoàn thiện

Đây là bounded runtime, chưa phải toàn bộ platform đã hoàn tất. API Reference chỉ hiển thị endpoints có code thực tế.

Identity: chưa OIDC, public tenant lifecycle/offboarding; full subject-scoped Skill/session isolation cho shared service key còn cần mở rộng.
MCP: mới HTTP và reviewed read tools. Writes/approvals/reconciliation, OAuth, legacy SSE/stdio và periodic sync chưa hoàn tất. Operator phải allowlist origin/network trước registration.
Skills: instruction-only; chưa full package import/resources/scripts, sandbox hoặc learned proposals.
Memory: explicit scopes; chưa complete automatic hierarchy, physical erasure/GC, extraction billing, general file ingestion hoặc Graph Explorer API.
Runtime: chưa external waits, token streaming hoặc automatic compaction/rollback.
Operations: còn off-host restore drill, load benchmarks, HA, OTel/evaluation/feedback/webhooks và remote artifact storage.

Memory:32 scopes/tenant,16 records/scope,64 revisions/record. Query tối đa4 scopes và8 facts. Model runs tối đa120s; MCP operations30s. Graphiti projection240s và một mutation slot. Vertex embedding001 dùng một input/request; finite vectors được L2-normalize. Model/policy changes cần rebuild affected projections.