API Reference

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.

Last updated

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.

MethodPathDescription
GET/api/v1/assistant/statusGet the status
GET/api/v1/assistant/settingsGet the settings
PUT/api/v1/assistant/settingsSave the settings
POST/api/v1/assistant/settings/testTest a provider
GET/api/v1/assistant/local-modelGet the local model's state
POST/api/v1/assistant/local-model/installInstall a local model
POST/api/v1/assistant/local-model/removeRemove a local model
POST/api/v1/assistant/local-model/uninstallRemove Ollama
GET/api/v1/assistant/conversationsList conversations
POST/api/v1/assistant/conversationsStart a conversation
GET/api/v1/assistant/conversations/:idGet a conversation
POST/api/v1/assistant/conversations/:id/messagesAsk a follow-up
POST/api/v1/assistant/conversations/:id/retryRetry a failed answer
DELETE/api/v1/assistant/conversations/:idDelete a conversation
POST/api/v1/assistant/actions/:id/approveApprove a proposed change
POST/api/v1/assistant/actions/:id/cancelCancel a proposed change

Providers

providerDescription
anthropicClaude through the Anthropic API. Needs an API key. Default model claude-opus-5-5.
openaiOpenAI, or any service with an OpenAI-compatible chat API (Ollama, vLLM…). The model must support tool calling. No default model; the key is optional.
localA 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

GET/api/v1/assistant/status
Auth
Session cookie (+ CSRF token) or API token
Permission
assistant.use
Token scope
full

Whether 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

GET/api/v1/assistant/settings
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

Returns 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

PUT/api/v1/assistant/settings
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

Saves 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

FieldTypeRequiredDescription
enabledbooleanNoTurn the assistant on or off.
providerstringNoanthropic, openai or local.
modelstringNoUp to 100 letters, digits and . _ : / @ -. For local, a model from the catalog.
baseUrlstring or nullNoThe 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.
apiKeystring or nullNoSets 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

StatusCodeWhen
422VALIDATION_ERRORTurning 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

POST/api/v1/assistant/settings/test
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

Sends 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

StatusCodeWhen
409ASSISTANT_NOT_CONFIGUREDNo provider, model or required key.
502PROVIDER_AUTH_FAILED, PROVIDER_MODEL_NOT_FOUND, PROVIDER_RATE_LIMITED, PROVIDER_UNREACHABLE, PROVIDER_TIMEOUT, PROVIDER_ERRORThe 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

GET/api/v1/assistant/local-model
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

The 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

POST/api/v1/assistant/local-model/install
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

Queues 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

FieldTypeRequiredDescription
modelstringYesA 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

StatusCodeWhen
409LOCAL_SERVER_MISSINGThe panel's own server is not connected.
409LOCAL_MODEL_UNAVAILABLEIts agent is offline or older than 0.41.0, or the panel does not run on Linux.
422VALIDATION_ERRORThe model is not in the catalog.

Remove a local model

POST/api/v1/assistant/local-model/remove
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

Queues a LOCAL_AI_REMOVE job that deletes one downloaded model.

Request body

FieldTypeRequiredDescription
modelstringYesA 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

POST/api/v1/assistant/local-model/uninstall
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

Queues 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

FieldTypeDescription
id, titlestringThe conversation; the title comes from the first question.
statusstringidle, thinking (an answer is on its way) or failed.
activitystring or nullWhat the assistant is doing, such as Reading your question.
errorobject or null{ code, message } of a failed answer: PROVIDER_AUTH_FAILED, PROVIDER_MODEL_NOT_FOUND, PROVIDER_RATE_LIMITED, PROVIDER_UNREACHABLE, PROVIDER_REFUSED, ASSISTANT_TIMEOUT…
itemsarraySingle conversation only: the transcript.
createdAt, updatedAtstringTimestamps.

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 fieldDescription
id, kind, labelSuch as application.restart, Restart app.
permission, dangerousThe permission it needs, and whether it is a risky change.
params, targetWhat it acts on: target is { type, id, label }.
reasonWhy the assistant proposes it.
statusproposed, running, succeeded, failed, cancelled or expired.
jobId, error, decidedAtThe 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

GET/api/v1/assistant/conversations
Auth
Session cookie (+ CSRF token) or API token
Permission
assistant.use
Token scope
full

Returns 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

POST/api/v1/assistant/conversations
Auth
Session cookie (+ CSRF token) or API token
Permission
assistant.use
Token scope
full

Asks 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

FieldTypeRequiredDescription
questionstringYesUp 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

StatusCodeWhen
403FORBIDDENA hosting customer, or missing assistant.use.
409ASSISTANT_NOT_CONFIGUREDThe assistant is off or not set up.
429ASSISTANT_LIMIT60 questions in the last hour.
503QUEUE_UNAVAILABLEThe panel could not hand the question to its worker (check Redis).

Get a conversation

GET/api/v1/assistant/conversations/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
assistant.use
Token scope
full

Returns 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

StatusCodeWhen
404NOT_FOUNDNo such conversation, or someone else's.

Ask a follow-up

POST/api/v1/assistant/conversations/:id/messages
Auth
Session cookie (+ CSRF token) or API token
Permission
assistant.use
Token scope
full

Asks 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

POST/api/v1/assistant/conversations/:id/retry
Auth
Session cookie (+ CSRF token) or API token
Permission
assistant.use
Token scope
full

Asks 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

DELETE/api/v1/assistant/conversations/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
assistant.use
Token scope
full

Deletes 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

POST/api/v1/assistant/actions/:id/approve
Auth
Session cookie (+ CSRF token) or API token
Permission
assistant.use
Token scope
full

Runs 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

StatusCodeWhen
404NOT_FOUNDNo such proposal, or not in your conversation.
409ACTION_EXPIREDThe proposal is more than 60 minutes old.
409ACTION_NOT_PENDINGIt was already approved, cancelled or expired.

Cancel a proposed change

POST/api/v1/assistant/actions/:id/cancel
Auth
Session cookie (+ CSRF token) or API token
Permission
assistant.use
Token scope
full

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