REST API

Gateway cung cấp REST API tại http://localhost:9832 (mặc định). Giao diện web dùng chính API này, nên bạn có thể dùng nó để tích hợp Nagare với công cụ khác.

Xác thực

Mọi endpoint yêu cầu header:

Authorization: Bearer <TOKEN>

Tạo token bằng nagare auth token.

Định dạng phản hồi

{
  "isSuccess": true,
  "data": { },
  "error": {
    "statusCode": 400,
    "code": "ERROR_CODE",
    "message": "Mô tả lỗi"
  }
}

Ví dụ

TOKEN="<TOKEN>"

# Tạo phiên trò chuyện
curl -X POST http://localhost:9832/api/v1/user/chat/session/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Phiên mới","currentModelProvider":"<PROVIDER_ID>","currentModel":"gpt-4o-mini"}'

# Gửi tin nhắn
curl -X POST http://localhost:9832/api/v1/user/chat/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sessionID":"<SESSION_ID>","text":"Mấy giờ rồi?"}'

/chat/send chỉ trả về invokeID. Nội dung câu trả lời được truyền qua WebSocket.

Trạng thái đăng nhập

Method	Endpoint	Mô tả
`GET`	`/api/v1/user/auth/state`	Kiểm tra token. Trả về `{ isAuth }`.

Trò chuyện

Method	Endpoint	Body / tham số	Kết quả
`POST`	`/api/v1/user/chat/send`	`{ sessionID, text }`	`{ invokeID }`
`POST`	`/api/v1/user/chat/cancel`	`{ sessionID, invokeID }`
`POST`	`/api/v1/user/chat/compact`	`{ sessionID }`	`{ invokeID }`
`POST`	`/api/v1/user/chat/session/create`	`{ title, currentModelProvider, currentModel }`	`{ session }`
`GET`	`/api/v1/user/chat/session/list`	Query `limit`, `offset`	`{ sessions }`
`GET`	`/api/v1/user/chat/session/:id`		`{ session }`
`DELETE`	`/api/v1/user/chat/session/:id`
`POST`	`/api/v1/user/chat/session/:id/settings`	`{ currentModelProvider, currentModel }`	`{ session }`
`GET`	`/api/v1/user/chat/session/:id/history`	Query `limit`, `beforeID`	`{ sessionID, messages, nextCursor }`
`POST`	`/api/v1/user/chat/session/:id/archive`	`{ isArchive }`	`{ session }`
`POST`	`/api/v1/user/chat/session/:id/duplicate`		`{ session }`

Đối tượng session:

{
  "id": "…",
  "title": "Phiên mới",
  "isArchive": false,
  "currentModel": "gpt-4o-mini",
  "currentModelProvider": { "id": "…", "name": "OpenAI", "compatible": "OpenAI" }
}

Nhà cung cấp mô hình

Method	Endpoint	Body / tham số
`GET`	`/api/v1/user/model-providers/list`
`GET`	`/api/v1/user/model-providers/details`	Query `provider=<id>`
`POST`	`/api/v1/user/model-providers/add`	`{ name, compatible, apiKey, models, baseUrl, credentialId }`
`POST`	`/api/v1/user/model-providers/delete`	`{ id }`
`POST`	`/api/v1/user/model-providers/models`	`{ id }`, trả về danh sách mô hình khả dụng từ nhà cung cấp.

compatible nhận "OpenAI" hoặc "Google". Dùng apiKey hoặc credentialId.

Credential

Method	Endpoint	Body / tham số
`GET`	`/api/v1/user/credentials/list`
`GET`	`/api/v1/user/credentials/details`	Query `credential=<id>`
`POST`	`/api/v1/user/credentials/add`	`{ name, apiKey }`
`POST`	`/api/v1/user/credentials/update`	`{ id, name, apiKey }`
`POST`	`/api/v1/user/credentials/delete`	`{ id }`

Phản hồi chỉ chứa id và name, không bao giờ trả lại API key.

Plugin

Method	Endpoint	Body
`GET`	`/api/v1/user/plugins/list`
`POST`	`/api/v1/user/plugins/upload`	`multipart/form-data`, trường `file`. Trả về `{ attachmentId }`.
`POST`	`/api/v1/user/plugins/install-attachment`	`{ attachmentId, signatureAttachmentId? }`
`POST`	`/api/v1/user/plugins/install-local`	`{ path }`
`POST`	`/api/v1/user/plugins/update`	`{ attachmentId, signatureAttachmentId? }`
`POST`	`/api/v1/user/plugins/uninstall`	`{ id }`
`POST`	`/api/v1/user/plugins/activate`	`{ id }`
`POST`	`/api/v1/user/plugins/deactivate`	`{ id }`
`POST`	`/api/v1/user/plugins/status`	`{ id }`, trả về `{ pid, packageName, name, version, cpuPercent, memoryUsage }`.

Đối tượng plugin gồm id, packageName, name, author, features, version, signatureStatus, lastStatus, isActive. Các thao tác cài đặt có thể trả về trường warning khi gói chưa ký hoặc chưa xác minh.

Thiết lập

Method	Endpoint	Body
`GET`	`/api/v1/user/settings/general/get`
`POST`	`/api/v1/user/settings/general/set`	`{ generalSettings }`

{
  "generalSettings": {
    "defaultModel": "gpt-4o-mini",
    "defaultModelProvider": "<PROVIDER_ID>",
    "summaryModel": "",
    "summaryModelProvider": ""
  }
}

Bắt đầu

Hướng dẫn sử dụng

Phát triển plugin

Tham chiếu

Xác thực

Định dạng phản hồi

Ví dụ

Trạng thái đăng nhập

Trò chuyện

Nhà cung cấp mô hình

Credential

Plugin

Thiết lập

​Xác thực

​Định dạng phản hồi

​Ví dụ

​Trạng thái đăng nhập

​Trò chuyện

​Nhà cung cấp mô hình

​Credential

​Plugin

​Thiết lập

Xác thực

Định dạng phản hồi

Ví dụ

Trạng thái đăng nhập

Trò chuyện

Nhà cung cấp mô hình

Credential

Plugin

Thiết lập