Skip to content

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 groupCallerCredential
Auth bindingyour backendscoped API key (auth:bind)
MCP file accessyour MCP serverscoped API key
Knowledge base syncyour backendscoped API key

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.

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.

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.

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.

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.

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/fetch
x-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.

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:

PartDescription
fileThe file to store.
filenameOptional. 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.

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.

:id is the knowledge base. Header: x-api-key: diosc_ak_… (knowledge:write). Body is multipart/form-data:

PartDescription
actionadd, replace, or remove.
filenameThe document’s name (max 512 chars). The sync key.
fileThe 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.