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	embed key
MCP file access	your MCP server	scoped API key
Knowledge base sync	your backend	scoped API key

Authentication

Every call carries an x-api-key header. Two kinds of key:

• Embed key: the same key your embed snippet uses. Authenticates auth binding.
• Scoped API key (diosc_ak_…): minted in the admin portal with a single permission. Authenticates MCP file access and knowledge-base sync. Give each key the narrowest scope it needs (mcp-files:read, mcp-files:write, or knowledge:write).

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

Header: x-api-key: <embed key>

{
  "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

Header: x-api-key: <embed key>. 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

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 session in context: header x-session-id (the session id from the tool call DioscHub sent your server). The session resolves to the user; you never pass a user id.

POST /api/mcp/files/fetch

get_file, fetch a file by exact name. Headers: x-api-key: diosc_ak_… (mcp-files:read), x-session-id.

{ "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

put_file, store a file into the user’s library. Headers: x-api-key: diosc_ak_… (mcp-files:write), x-session-id. 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.

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

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

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