AI assistant
API reference for the AI assistant - provider settings, the free model on the panel's server, conversations, and approving the changes it proposes.
The assistant answers questions about your servers by reading their status and logs through the panel, with the permissions of the person who asked, and proposes changes that run only when that person approves them. Questions are answered by the panel's worker, so the worker must be running.
Settings need settings.manage; everything else needs assistant.use (owners, admins, developers and viewers; never hosting customers). Conversations belong to the person who started them: anyone else gets 404. For the concepts, see AI assistant, Providers and Free model on this server.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/assistant/status | Get the status |
| GET | /api/v1/assistant/settings | Get the settings |
| PUT | /api/v1/assistant/settings | Save the settings |
| POST | /api/v1/assistant/settings/test | Test a provider |
| GET | /api/v1/assistant/local-model | Get the local model's state |
| POST | /api/v1/assistant/local-model/install | Install a local model |
| POST | /api/v1/assistant/local-model/remove | Remove a local model |
| POST | /api/v1/assistant/local-model/uninstall | Remove Ollama |
| GET | /api/v1/assistant/conversations | List conversations |
| POST | /api/v1/assistant/conversations | Start a conversation |
| GET | /api/v1/assistant/conversations/:id | Get a conversation |
| POST | /api/v1/assistant/conversations/:id/messages | Ask a follow-up |
| POST | /api/v1/assistant/conversations/:id/retry | Retry a failed answer |
| DELETE | /api/v1/assistant/conversations/:id | Delete a conversation |
| POST | /api/v1/assistant/actions/:id/approve | Approve a proposed change |
| POST | /api/v1/assistant/actions/:id/cancel | Cancel a proposed change |
Providers
provider | Description |
|---|---|
anthropic | Claude through the Anthropic API. Needs an API key. Default model claude-opus-5-5. |
openai | OpenAI, or any service with an OpenAI-compatible chat API (Ollama, vLLM…). The model must support tool calling. No default model; the key is optional. |
local | A small open model the panel installs on its own server with Ollama (agent 0.41.0 or newer). No API key; nothing leaves the server. Takes only a model from the panel's catalog. |
Get the status
/api/v1/assistant/statusWhether questions can be asked now. enabled is true only when the assistant is on and fully configured. canConfigure says whether you may change its settings.
Example request
curl https://panel.example.com/api/v1/assistant/status \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const status = await panel.request('GET', '/assistant/status');Response 200 OK
{
"success": true,
"data": {
"enabled": true,
"provider": "anthropic",
"providerLabel": "Claude (Anthropic)",
"model": "claude-opus-5-5",
"canConfigure": true,
"hourlyLimit": 60
},
"message": "OK",
"requestId": "…"
}Get the settings
/api/v1/assistant/settingsReturns the chosen provider's settings and, in providers, each provider's own model, address and whether it has a key. Keys are never returned, only their last four characters (apiKeyHint). missing says what is still needed before the assistant can be turned on, or null.
Example request
curl https://panel.example.com/api/v1/assistant/settings \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const settings = await panel.request('GET', '/assistant/settings');Response 200 OK
{
"success": true,
"data": {
"enabled": true,
"provider": "anthropic",
"model": "claude-opus-5-5",
"baseUrl": null,
"hasApiKey": true,
"apiKeyHint": "…x9Qa",
"missing": null,
"providers": {
"anthropic": { "model": "claude-opus-5-5", "baseUrl": null, "hasApiKey": true, "apiKeyHint": "…x9Qa" },
"openai": { "model": null, "baseUrl": null, "hasApiKey": false, "apiKeyHint": null },
"local": { "model": null, "baseUrl": null, "hasApiKey": false, "apiKeyHint": null }
},
"updatedAt": "2026-11-10T08:00:00.000Z"
},
"message": "OK",
"requestId": "…"
}Save the settings
/api/v1/assistant/settingsSaves the settings of provider (or of the chosen provider when it is left out) and makes it the chosen one. Each provider keeps its own model, address and key, so switching back needs nothing again. All fields are optional.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | No | Turn the assistant on or off. |
provider | string | No | anthropic, openai or local. |
model | string | No | Up to 100 letters, digits and . _ : / @ -. For local, a model from the catalog. |
baseUrl | string or null | No | The provider's address, http or https, without credentials, query or fragment, such as https://api.openai.com/v1. Empty or null clears it. Ignored for local. |
apiKey | string or null | No | Sets that provider's key; null removes it; leaving it out keeps it. Ignored for local. |
Example request
curl https://panel.example.com/api/v1/assistant/settings \
-X PUT \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "enabled": true, "provider": "anthropic", "model": "claude-sonnet-5-5", "apiKey": "'"$ANTHROPIC_API_KEY"'" }'await panel.request('PUT', '/assistant/settings', {
body: { enabled: true, provider: 'anthropic', model: 'claude-sonnet-5-5', apiKey: process.env.ANTHROPIC_API_KEY },
});Response 200 OK: the same data as Get the settings, message Assistant settings saved.
Errors
| Status | Code | When |
|---|---|---|
| 422 | VALIDATION_ERROR | Turning it on without a provider, a model, or a key for Claude; a local model not in the catalog; or an invalid field. |
Test a provider
/api/v1/assistant/settings/testSends one short request to a provider with the settings given, filling in what is left out from that provider's saved settings (its saved key is used when none is given). Nothing is saved.
Request body: provider, model, baseUrl and apiKey, as in Save the settings, all optional.
Example request
curl https://panel.example.com/api/v1/assistant/settings/test \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "provider": "openai", "baseUrl": "http://10.0.0.5:11434/v1", "model": "qwen3.5:9b" }'const result = await panel.request('POST', '/assistant/settings/test', {
body: { provider: 'openai', baseUrl: 'http://10.0.0.5:11434/v1', model: 'qwen3.5:9b' },
});Response 200 OK, message The AI provider answered
{ "success": true, "data": { "ok": true, "provider": "openai", "model": "qwen3.5:9b", "latencyMs": 812 }, "message": "The AI provider answered", "requestId": "…" }Errors
| Status | Code | When |
|---|---|---|
| 409 | ASSISTANT_NOT_CONFIGURED | No provider, model or required key. |
| 502 | PROVIDER_AUTH_FAILED, PROVIDER_MODEL_NOT_FOUND, PROVIDER_RATE_LIMITED, PROVIDER_UNREACHABLE, PROVIDER_TIMEOUT, PROVIDER_ERROR | The provider refused the key, does not know the model, rate-limited, could not be reached, did not answer in time, or returned an error. |
Get the local model's state
/api/v1/assistant/local-modelThe free model on the panel's own server: whether it can be installed there (problem says why not, otherwise null), Ollama's state, the installed models, the server's memory and free disk, the last install or removal job, and catalog, the models the panel offers with their download size and the memory they need.
Example request
curl https://panel.example.com/api/v1/assistant/local-model \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const local = await panel.request('GET', '/assistant/local-model');Response 200 OK
{
"success": true,
"data": {
"server": { "id": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c", "name": "This server", "status": "online" },
"problem": null,
"installed": true,
"running": true,
"version": "0.40.16",
"models": [{ "id": "qwen3.5:4b", "sizeBytes": 3400000000 }],
"memory": { "totalBytes": 8589934592, "availableBytes": 5100000000 },
"diskFreeBytes": 64000000000,
"lastJob": { "id": "…", "type": "LOCAL_AI_INSTALL", "status": "succeeded" },
"catalog": [
{ "id": "qwen3.5:2b-q4_K_M", "label": "Qwen3.5 2B", "description": "The smallest and fastest. Simple answers; for servers with 4 GB of memory.", "downloadBytes": 1945781358, "memoryBytes": 2684354560, "license": "Apache 2.0", "thinks": false, "recommendable": true }
]
},
"message": "OK",
"requestId": "…"
}The catalog's model ids are qwen3.5:2b-q4_K_M, granite4.1:3b, qwen3.5:4b and qwen3.5:9b.
Install a local model
/api/v1/assistant/local-model/installQueues a LOCAL_AI_INSTALL job on the panel's own server: the agent installs Ollama when it is missing, runs it as its own service on 127.0.0.1:21434, and downloads the model. Then choose the local provider and the model in Save the settings.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
model | string | Yes | A model id from the catalog. |
Example request
curl https://panel.example.com/api/v1/assistant/local-model/install \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "model": "qwen3.5:4b" }'const job = await panel.request('POST', '/assistant/local-model/install', { body: { model: 'qwen3.5:4b' } });
await panel.jobs.wait(job.id, { timeoutMs: 30 * 60_000 });Response 202 Accepted: the job, message Installing the model on this server.
Errors
| Status | Code | When |
|---|---|---|
| 409 | LOCAL_SERVER_MISSING | The panel's own server is not connected. |
| 409 | LOCAL_MODEL_UNAVAILABLE | Its agent is offline or older than 0.41.0, or the panel does not run on Linux. |
| 422 | VALIDATION_ERROR | The model is not in the catalog. |
Remove a local model
/api/v1/assistant/local-model/removeQueues a LOCAL_AI_REMOVE job that deletes one downloaded model.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
model | string | Yes | A model id from the catalog. |
Example request
curl https://panel.example.com/api/v1/assistant/local-model/remove \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "model": "qwen3.5:2b-q4_K_M" }'await panel.request('POST', '/assistant/local-model/remove', { body: { model: 'qwen3.5:2b-q4_K_M' } });Response 202 Accepted: the job, message Removing the model.
Errors: those of Install a local model, and 409 LOCAL_MODEL_IN_USE for the model the assistant answers with.
Remove Ollama
/api/v1/assistant/local-model/uninstallQueues a LOCAL_AI_UNINSTALL job that removes every model and Ollama itself. No body.
Example request
curl https://panel.example.com/api/v1/assistant/local-model/uninstall \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"await panel.request('POST', '/assistant/local-model/uninstall');Response 202 Accepted: the job, message Removing the models and Ollama.
Errors: 409 LOCAL_MODEL_IN_USE while the assistant answers with the local provider, 409 LOCAL_SERVER_MISSING or LOCAL_MODEL_UNAVAILABLE.
The conversation object
| Field | Type | Description |
|---|---|---|
id, title | string | The conversation; the title comes from the first question. |
status | string | idle, thinking (an answer is on its way) or failed. |
activity | string or null | What the assistant is doing, such as Reading your question. |
error | object or null | { code, message } of a failed answer: PROVIDER_AUTH_FAILED, PROVIDER_MODEL_NOT_FOUND, PROVIDER_RATE_LIMITED, PROVIDER_UNREACHABLE, PROVIDER_REFUSED, ASSISTANT_TIMEOUT… |
items | array | Single conversation only: the transcript. |
createdAt, updatedAt | string | Timestamps. |
In the transcript, a user item has text; an assistant item has text, steps (the checks it made: { label, failed, pending }) and actions, the changes it proposed:
| Action field | Description |
|---|---|
id, kind, label | Such as application.restart, Restart app. |
permission, dangerous | The permission it needs, and whether it is a risky change. |
params, target | What it acts on: target is { type, id, label }. |
reason | Why the assistant proposes it. |
status | proposed, running, succeeded, failed, cancelled or expired. |
jobId, error, decidedAt | The job it started, and its outcome. |
The proposals the assistant can make are restarting, starting, stopping, deploying, rolling back an app and applying its saved settings; restarting or starting a service; turning a website on, retrying its setup or renewing its certificate; and installing software on a server.
List conversations
/api/v1/assistant/conversationsReturns your 100 most recently updated conversations, without their transcripts.
Example request
curl https://panel.example.com/api/v1/assistant/conversations \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.request('GET', '/assistant/conversations');Response 200 OK: { items } of conversations.
Start a conversation
/api/v1/assistant/conversationsAsks a first question. It returns at once with the conversation in status thinking: poll Get a conversation until it is idle or failed. Each person may ask 60 questions an hour.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
question | string | Yes | Up to 4000 characters. |
Example request
curl https://panel.example.com/api/v1/assistant/conversations \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "question": "Why is the shop-api app restarting?" }'let convo = await panel.request('POST', '/assistant/conversations', {
body: { question: 'Why is the shop-api app restarting?' },
});
while (convo.status === 'thinking') {
await new Promise((r) => setTimeout(r, 2000));
convo = await panel.request('GET', `/assistant/conversations/${convo.id}`);
}
console.log(convo.items.at(-1).text);Response 202 Accepted: the conversation with its transcript, message The assistant is looking into it.
Errors
| Status | Code | When |
|---|---|---|
| 403 | FORBIDDEN | A hosting customer, or missing assistant.use. |
| 409 | ASSISTANT_NOT_CONFIGURED | The assistant is off or not set up. |
| 429 | ASSISTANT_LIMIT | 60 questions in the last hour. |
| 503 | QUEUE_UNAVAILABLE | The panel could not hand the question to its worker (check Redis). |
Get a conversation
/api/v1/assistant/conversations/:idReturns the conversation with its transcript and proposed changes.
Example request
curl https://panel.example.com/api/v1/assistant/conversations/0d1e2f3a-4b5c-4d6e-8f7a-8b9c0d1e2f3a \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const convo = await panel.request('GET', `/assistant/conversations/${conversationId}`);Response 200 OK
{
"success": true,
"data": {
"id": "0d1e2f3a-4b5c-4d6e-8f7a-8b9c0d1e2f3a",
"title": "Why is the shop-api app restarting?",
"status": "idle",
"activity": null,
"error": null,
"items": [
{ "id": 41, "role": "user", "text": "Why is the shop-api app restarting?", "createdAt": "2026-11-10T12:00:00.000Z" },
{
"id": 42,
"role": "assistant",
"text": "The app exits because it cannot reach its database…",
"steps": [{ "label": "Read the app's error log", "failed": false, "pending": false }],
"actions": [
{
"id": "7f8a9b0c-…",
"kind": "application.restart",
"label": "Restart app",
"permission": "applications.deploy",
"dangerous": false,
"target": { "type": "application", "id": "3e4f5a6b-…", "label": "shop-api on web-1" },
"reason": "Restart once the database is back.",
"status": "proposed",
"jobId": null,
"error": null
}
],
"createdAt": "2026-11-10T12:00:09.000Z"
}
],
"createdAt": "2026-11-10T12:00:00.000Z",
"updatedAt": "2026-11-10T12:00:20.000Z"
},
"message": "OK",
"requestId": "…"
}Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such conversation, or someone else's. |
Ask a follow-up
/api/v1/assistant/conversations/:id/messagesAsks another question in the same conversation. One question at a time per conversation.
Request body: question, as in Start a conversation.
Example request
curl https://panel.example.com/api/v1/assistant/conversations/0d1e2f3a-4b5c-4d6e-8f7a-8b9c0d1e2f3a/messages \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "question": "Is the database running now?" }'await panel.request('POST', `/assistant/conversations/${conversationId}/messages`, {
body: { question: 'Is the database running now?' },
});Response 202 Accepted: the conversation, message The assistant is looking into it.
Errors: those of Start a conversation, 404 NOT_FOUND, and 409 ASSISTANT_BUSY while it is still answering.
Retry a failed answer
/api/v1/assistant/conversations/:id/retryAsks again after a failed answer, from where it stopped.
Example request
curl https://panel.example.com/api/v1/assistant/conversations/0d1e2f3a-4b5c-4d6e-8f7a-8b9c0d1e2f3a/retry \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"await panel.request('POST', `/assistant/conversations/${conversationId}/retry`);Response 202 Accepted: the conversation, message Trying again.
Errors: 409 NOTHING_TO_RETRY when the last answer did not fail, 409 ASSISTANT_BUSY, and those of Start a conversation.
Delete a conversation
/api/v1/assistant/conversations/:idDeletes the conversation with its messages and proposed changes.
Example request
curl https://panel.example.com/api/v1/assistant/conversations/0d1e2f3a-4b5c-4d6e-8f7a-8b9c0d1e2f3a \
-X DELETE \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"await panel.request('DELETE', `/assistant/conversations/${conversationId}`);Response 200 OK: data is null, message Conversation deleted.
Approve a proposed change
/api/v1/assistant/actions/:id/approveRuns a proposed change as you, through the same service call as the matching button in the panel, so your own permission for it is checked. Proposals expire after 60 minutes. The response is the action: when it could not start, its status is failed with the error (for example, a permission you lack) and the message is The change could not start; otherwise running with its jobId, and it moves to succeeded or failed when the job ends.
Example request
curl https://panel.example.com/api/v1/assistant/actions/7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b0c/approve \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const action = await panel.request('POST', `/assistant/actions/${actionId}/approve`);
if (action.jobId) await panel.jobs.wait(action.jobId);Response 200 OK: the action, message Change started or The change could not start.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such proposal, or not in your conversation. |
| 409 | ACTION_EXPIRED | The proposal is more than 60 minutes old. |
| 409 | ACTION_NOT_PENDING | It was already approved, cancelled or expired. |
Cancel a proposed change
/api/v1/assistant/actions/:id/cancelDismisses a proposal.
Example request
curl https://panel.example.com/api/v1/assistant/actions/7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b0c/cancel \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"await panel.request('POST', `/assistant/actions/${actionId}/cancel`);Response 200 OK: the action with status cancelled, message Change cancelled.
Errors: 404 NOT_FOUND, and 409 ACTION_NOT_PENDING when it was already decided.
Webhooks
API reference for outgoing webhooks - creating JSON, Slack and Discord webhooks, rotating signing secrets, sending tests and reading or redelivering deliveries.
Hosting
API reference for hosting plans, customer accounts, quotas, suspending and removing accounts, the financial report, billing API keys and a customer's own account.