Publish an assistant as a website widget
Publish one assistant as an embeddable website widget and receive its widget key. The key is public by design; what protects the embed is its allowed origins.
POST
A widget deployment is one embed of one assistant on your website. Creating it returns a
widget_key (arukz_wk_…) that you paste into your page. The key is public by design: it lives in your page source, it is not a secret, and you can read it back at any time. What protects the embed is its origin allowlist, its fixed assistant and the narrow permissions it grants: a visitor can start a conversation and ask questions, and nothing else. See Website widget.
The assistant must exist in your organization, or the request fails with 404. It cannot be changed later; to point a page at a different assistant, create a new deployment and revoke the old one. Deployment names are unique within your organization; a name that is already taken returns 409.
You need the assistant.publish permission, which the owner, admin and editor roles hold. Authenticate with an arukz_sk_ API key or a signed-in console session.
string
required
A label for the embed. Leading and trailing whitespace is trimmed; the result must be 1 to 120
characters, with no control, invisible formatting (such as zero-width or bidirectional-override),
private-use or line-separator characters.
string
required
ID (UUID) of the assistant to embed. Fixed for the life of the deployment. A value that is not a
UUID returns
400.string[]
default:"[]"
The website origins allowed to host this widget, at most 20. Each entry must be exactly
scheme://host or scheme://host:port:httporhttpsonly.- Exact match. No wildcards:
*and*.example.comare refused. List each subdomain separately. - No trailing slash, path, query or credentials.
https://docs.example.com/is refused. - ASCII hosts only. Scheme and host are compared case-insensitively, and a default port (
:443forhttps,:80forhttp) is ignored.
integer
Lifetime in whole days, from 1 to 730. Omit it, or send
null, for an embed that does not expire.
An expired embed stops working without further action.Response
Returns201 Created with the deployment.
string
required
The deployment’s ID (UUID).
string
required
The embed’s label.
string
required
The public key to put in your page:
arukz_wk_ followed by the deployment ID. Send it in the
X-ARUKZ-Widget-Key header.string
required
The embedded assistant’s ID.
string
required
Always
active on creation.string[]
required
The accepted origins, de-duplicated and sorted, in the spelling you sent.
string
required
When the deployment was created, ISO 8601 in UTC.
string | null
required
ID of the user who created it, or
null when it was created with an API key.string | null
required
When the embed expires, or
null if it does not.string | null
required
Always
null on creation.string | null
required
Always
null on creation.Last modified on September 26, 2026