> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nagare.smtdfc.net/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Tham chiếu REST API của Nagare gateway: phiên trò chuyện, nhà cung cấp mô hình, credential, plugin và thiết lập.

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:

```http theme={null}
Authorization: Bearer <TOKEN>
```

Tạo token bằng `nagare auth token`.

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

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

## Ví dụ

```bash theme={null}
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](https://docs.nagare.smtdfc.net/reference/websocket.md).

## 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`:

```json theme={null}
{
  "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 }` |

```json theme={null}
{
  "generalSettings": {
    "defaultModel": "gpt-4o-mini",
    "defaultModelProvider": "<PROVIDER_ID>",
    "summaryModel": "",
    "summaryModelProvider": ""
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.