How to Connect Dust Assistants to Internal Tools via the API
Beyond chat, Dust lets you trigger an assistant programmatically and let it call your own endpoints as tools. You create an API key, register a custom action, define its input schema, and the assistant calls your service mid-conversation. This is how teams push a Dust assistant into a support macro, a script, or another app.
It requires comfort with HTTP and JSON. If that is not your role, hand this guide to whoever owns your integrations.
What does the API actually expose?
Two layers. The REST API lets you start a conversation and stream a response from outside the Dust UI. Custom actions let the assistant call back into your systems during that conversation.
The combination turns an assistant from a chat toy into a step inside a larger process — for example, a nightly job that asks the assistant to summarize new tickets and writes the result to your database.
How do you get started with the API?
- In workspace settings, generate an API key and store it as an environment variable, never in source.
- Identify the assistant’s ID from its settings page.
- Send a POST request to the messages endpoint with the assistant ID and your query.
- Parse the streamed or JSON response and extract the text.
- Log the request ID so failures can be traced later.
Start with a single hardcoded query to confirm auth works before building anything around it.
How do custom actions work?
You define an action with a name, a description, and a JSON schema for its inputs. Dust uses the description to decide when to call it. Your endpoint receives the arguments, runs the logic, and returns JSON.
The description matters more than the code. A vague description makes the model call the action at the wrong time or skip it entirely. Write it as you would explain the tool to a new teammate.
What should you watch for?
| Concern | Practice |
|---|---|
| Key storage | Environment variables, rotated periodically |
| Timeouts | Return fast; queue long work |
| Idempotency | Actions may retry — make writes safe to repeat |
| Scope | Give the key the least access it needs |
Idempotency is the one that bites. An action that creates a record can fire twice if a call times out and retries, leaving duplicates. Accept an idempotency key and check it before writing.
How do you handle failures gracefully?
Return a clear JSON error rather than a stack trace. The assistant will relay it to the user, and a readable message lets them correct the input. For long-running work, return an acknowledgment and process it asynchronously so the conversation does not stall.
Also cap what the assistant can do autonomously. Read-only actions can run freely; write actions benefit from a confirmation step, since a misread prompt can trigger an unintended change.
Who should build this?
Teams with a developer who already runs internal services and wants an assistant inside an existing workflow rather than a separate chat tab. If you only need Q&A over docs, the built-in connectors spare you all of this. The API path earns its keep when the assistant must act, not just answer.
Quick Summary
- Dust exposes a REST API to trigger assistants and custom actions for tools they can call.
- Store API keys in environment variables and rotate them; never hardcode.
- Custom action descriptions drive when the model calls them — write them precisely.
- Make write actions idempotent, since retries after timeouts can duplicate records.
