> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.omicx.one/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.omicx.one/_mcp/server.

# Giới thiệu

OMICX AI Assistant là trợ lý AI dạng hội thoại (chatbot) của OMICX. Đối
tác bên thứ ba có thể tích hợp trực tiếp qua API để gửi tin nhắn và quản lý
cuộc trò chuyện thay mặt người dùng cuối của mình.

## Base URL

```
https://api.omicx.one
```

Tất cả endpoint đều yêu cầu xác thực qua header `X-Api-Key` — xem chi tiết
tại trang [Xác thực](/authentication).

## Ràng buộc theo trợ lý

Scope `assistant:execute` **không phải scope tự chọn** — nó chỉ được cấp
cho một API key khi tạo key, và bị ràng buộc với đúng **1 trợ lý**. Vì
vậy một key FULL-access thông thường (không được gán riêng) vẫn không
gọi được các endpoint này. Thiếu scope trả về `403 INSUFFICIENT_SCOPE`;
key có scope nhưng đã bị gỡ ràng buộc trả về `403 ASSISTANT_NOT_BOUND`.

## Cuộc trò chuyện (Conversation)

Mỗi cuộc trò chuyện được nhóm theo `conversationId`. Gửi tin nhắn đầu
tiên không kèm `conversationId` để bắt đầu cuộc trò chuyện mới — response
trả về `conversationId` được tạo, dùng cho các tin nhắn tiếp theo trong
cùng cuộc trò chuyện. Mỗi cuộc trò chuyện gắn với một `userId` do đối tác
tự định danh (người dùng cuối phía đối tác) — dùng để phân tách dữ liệu
giữa các người dùng khác nhau. `userId` phải là một định danh **không
mang nghĩa** (không dùng email, số điện thoại, hay tên thật).

## Chế độ phản hồi (Response mode)

Hiện tại chỉ hỗ trợ `blocking` — chờ xử lý xong, trả kết quả trong 1
response (thường vài giây, có thể tới 1 phút). `streaming` được chấp
nhận trong hợp đồng nhưng hiện tại luôn trả về `501
STREAMING_NOT_AVAILABLE`.

## Retry & tính phí

Gửi kèm header `Idempotency-Key` khi gửi tin nhắn để retry an toàn — xem
chi tiết tại API [Gửi tin nhắn cho trợ lý](/agent/chat/agent-chat). Không
gửi header này, một lần gửi lại sau lỗi mạng sẽ được tính là lượt chat
mới và bị tính phí lần nữa.