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

> REST API reference for the Nagare gateway: chat sessions, model providers, credentials, plugins, and settings.

The gateway provides a REST API at `http://localhost:9832` (default). The web UI uses this same API, so you can use it to integrate Nagare with other tools.

## Authentication

Every endpoint requires the header:

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

Generate a token with `nagare auth token`.

## Response format

```json theme={null}
{
  "isSuccess": true,
  "data": { },
  "error": {
    "statusCode": 400,
    "code": "ERROR_CODE",
    "message": "Error description"
  }
}
```

## Example

```bash theme={null}
TOKEN="<TOKEN>"

# Create a chat session
curl -X POST http://localhost:9832/api/v1/user/chat/session/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"New session","currentModelProvider":"<PROVIDER_ID>","currentModel":"gpt-4o-mini"}'

# Send a message
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":"What time is it?"}'
```

`/chat/send` only returns `invokeID`. The response content is streamed through [WebSocket](https://docs.nagare.smtdfc.net/en/reference/websocket.md).

## Login state

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/api/v1/user/auth/state` | Check the token. Returns `{ isAuth }`. |

## Chat

| Method | Endpoint | Body / params | Result |
| - | - | - | - |
| `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 }` |

The `session` object:

```json theme={null}
{
  "id": "…",
  "title": "New session",
  "isArchive": false,
  "currentModel": "gpt-4o-mini",
  "currentModelProvider": { "id": "…", "name": "OpenAI", "compatible": "OpenAI" }
}
```

## Model providers

| Method | Endpoint | Body / params |
| - | - | - |
| `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 }`, returns the list of available models from the provider. |

`compatible` accepts `"OpenAI"` or `"Google"`. Use either `apiKey` or `credentialId`.

## Credentials

| Method | Endpoint | Body / params |
| - | - | - |
| `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 }` |

Responses only contain `id` and `name`; the API key is never returned.

## Plugins

| Method | Endpoint | Body |
| - | - | - |
| `GET` | `/api/v1/user/plugins/list` | |
| `POST` | `/api/v1/user/plugins/upload` | `multipart/form-data`, field `file`. Returns `{ 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 }`, returns `{ pid, packageName, name, version, cpuPercent, memoryUsage }`. |

The plugin object includes `id`, `packageName`, `name`, `author`, `features`, `version`, `signatureStatus`, `lastStatus`, `isActive`. Installation operations may return a `warning` field when the package is unsigned or unverified.

## Settings

| 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.