Server API
These are the HTTP endpoints your own services call. The widget’s own endpoints (the embed loader,
session and file APIs) are not part of this surface. They belong to the kit, and you drive the kit
with diosc(), not HTTP.
There are three:
| Endpoint group | Caller | Credential |
|---|---|---|
| Auth binding | your backend | scoped API key (auth:bind) |
| MCP file access | your MCP server | scoped API key |
| Knowledge base sync | your backend | scoped API key |
Authentication
Section titled “Authentication”Every call carries an x-api-key header with a scoped API key (diosc_ak_…): a secret key minted
in the admin portal with a single permission, kept on your server. Give each key the narrowest scope it
needs: auth:bind for auth binding, mcp-files:read or mcp-files:write for
MCP file access, knowledge:write for knowledge-base sync.
The public embed key from your embed snippet is not accepted on any of these endpoints. It ships to the
browser, so the hub answers 401 Invalid API key when it arrives here.
Auth binding
Section titled “Auth binding”How an authenticated user reaches DioscHub. Your backend authenticates the user its own way, then binds that identity to the live widget connection. The assistant acts as the user without DioscHub ever handling a password; the auth artifacts you pass are forwarded to your MCP servers unmodified and are never placed in the model’s context. See Identity & auth for the end-to-end flow.
POST /api/auth/bind
Section titled “POST /api/auth/bind”Header: x-api-key: <scoped API key with auth:bind>
{ "wsId": "abc123", // the connection id the widget hands your backend "identity": { // omit for an anonymous bind "userId": "user_42", "username": "ada", "role": { "name": "support-agent" } }, "authArtifacts": { "headers": { "Authorization": "Bearer …" }, // forwarded opaquely to your MCP servers "cookies": "session=…" // optional }}Returns { "ok": true }. DioscHub binds the identity and artifacts to the connection, and the widget
proceeds as the signed-in user.
POST /api/auth/invalidate
Section titled “POST /api/auth/invalidate”Header: x-api-key: <scoped API key with auth:bind>. Call this when the user signs out or their role changes; DioscHub
drops the binding and signals the affected widget connections to re-authenticate.
MCP file access
Section titled “MCP file access”How an MCP server reads and writes files in the user’s library, for example to hand the assistant a document the user uploaded, or to store one your tool generated. Files are scoped to the user behind the session; there is no listing endpoint.
Both calls require the call’s file access token in header x-file-access-token: the opaque value
DioscHub puts in _meta["dioschub/fileAccess"] of every session tool call it sends your server. It is
valid for 15 minutes, issued per tool call, and bound to the session and your server’s instance, with read and
write access. The session comes from the token and resolves to the user; you never pass a user id.
x-session-id is optional; if sent it must match the token’s session.
403 when the token is invalid, tampered or expired, the session does not match, the operation is not
granted, the session is no longer live (completed, expired, deleted or quarantined), or the server is no
longer attached to the session’s Assistant. An invalid token is never retried on the legacy path. The
token is a credential: never log it or return it in tool output.
Deprecated: the API key plus x-session-id without a token still works for one release (DioscHub
logs a warning) and is removed in the next release.
POST /api/mcp/files/fetch
Section titled “POST /api/mcp/files/fetch”get_file, fetch a file by exact name. Headers: x-api-key: diosc_ak_… (mcp-files:read),
x-file-access-token.
POST /api/mcp/files/fetchx-api-key: diosc_ak_…x-file-access-token: <from _meta["dioschub/fileAccess"]>content-type: application/json{ "name": "invoice-2026.pdf" }Returns the file contents as a download. 404 if no file by that name exists for the user.
POST /api/mcp/files/upload
Section titled “POST /api/mcp/files/upload”put_file, store a file into the user’s library. Headers: x-api-key: diosc_ak_…
(mcp-files:write), x-file-access-token. Body is multipart/form-data:
| Part | Description |
|---|---|
file | The file to store. |
filename | Optional. The name to store it under; defaults to the uploaded file’s name. |
413 with code: "FILE_TOO_LARGE" (and limitBytes) when the file is over the upload limit, or
code: "QUOTA_EXCEEDED" (with usage and quota fields) when it would exceed the user’s storage quota;
415 with code: "FILE_TYPE_REFUSED" for an executable; nothing is stored. 403 with code: "ANONYMOUS_SESSION" for an anonymous session (both MCP file
calls). See Read and write files from a tool.
Knowledge base sync
Section titled “Knowledge base sync”Keep a knowledge base in step with your source system. When a document changes on your side, push the
change and DioscHub re-indexes it. Files are keyed by filename, so replace and remove target the
same name you added.
POST /api/admin/knowledge/:id/sync
Section titled “POST /api/admin/knowledge/:id/sync”:id is the knowledge base. Header: x-api-key: diosc_ak_… (knowledge:write). Body is
multipart/form-data:
| Part | Description |
|---|---|
action | add, replace, or remove. |
filename | The document’s name (max 512 chars). The sync key. |
file | The document. Required for add and replace; omit for remove. |
A file over the system upload limit (default 100 MB) is refused with 413 and
code: "FILE_TOO_LARGE" (with limitBytes); nothing is stored. See File storage
limits. When the optional knowledge-base storage limit
is set, an add, or a replace that grows the file, that would pass it is refused with 413 and
code: "KB_STORAGE_LIMIT_EXCEEDED" (with usedBytes, limitBytes, requiredBytes); see Knowledge
bases. An executable is refused with 415
and code: "FILE_TYPE_REFUSED"; a replace refused this way leaves the existing document as it was. See
File types.
replace doesn’t delete first: the old version keeps answering searches until the new one is indexed,
then the file switches over, whatever the outcome (see Replace a file without a
gap). A replace that collides with another
replace of the same file, or finds the file changed under it, is refused with 409 and stores nothing;
retry it.
Returns the synced file and the action taken, or 204 No Content when the call is a no-op (e.g.
removing a file that isn’t there). The file carries its status fields
(status, reason, warnings, progress, canRead, canSearch); isIndexed is deprecated.