Read Agent activity and manage the files and URLs in its knowledge base.
The HeroUI Agents API lets your backend query Agent activity and manage knowledge documents. Workspace API keys work across the workspace, while every request path selects exactly one Agent.
This API is for server-to-server requests. To embed an Agent in your product, use the web embed instead.
Send all production requests to:
https://api.heroui.pro/v1Paths in this reference are relative to that URL. The API uses HTTPS and returns JSON, except for the extracted-content endpoint, which returns Markdown.
Pass a workspace API key as a Bearer token in the Authorization header and include the Agent ID in the path:
curl "https://api.heroui.pro/v1/agents/$HEROUI_AGENT_ID/users?limit=20" \
--header "Authorization: Bearer $HEROUI_AGENT_API_KEY" \
--header "Accept: application/json"The key must include the permission required by the endpoint. Keep it in a secret manager and make requests from your backend only. See Authentication for the complete scope model.
Never put a workspace API key in your product's browser code. The documentation playground is for deliberate testing only and keeps a pasted key in the current browser tab.
All list endpoints use cursor pagination. Failed requests use a consistent error shape, and requests are subject to usage limits.
| Permission | Dashboard label | Allows |
|---|---|---|
users:read | View users | See the people who have used this Agent. |
conversations:read | View conversations | See conversations and messages between people and this Agent. |
runs:read | View runs | View this Agent's run history, including status, latency, and tool activity. |
knowledge:read | View knowledge | List knowledge documents and inspect their extracted markdown. |
knowledge:write | Manage knowledge | Add, update, refresh, schedule, and delete knowledge documents. |
Only assign the permissions that a server integration needs. Permissions apply to the operations a key can perform across Agents in its workspace; they never grant Agent-definition administration.
The OpenAPI 3.1 description is available at /.well-known/openapi/heroui-agents-api.json. It is also advertised in the site's API catalog.
Use agent.heroui.pro/loader.js on any modern website. React applications can instead import the
typed host bridge from @heroui/agent, or its Next.js entry point from @heroui/agent/next. All
three integrations render the same hosted iframe and expose client-side tools and controls.
| Entry point | Use |
|---|---|
agent.heroui.pro/loader.js | Framework-independent browser bridge. |
@heroui/agent | React component, hook, tool helper, model constants, and public types. |
@heroui/agent/next | Next.js-compatible mirror of the React bridge. |
@heroui/agent/server | Server-only managed-key exchange helper. |
See the Quickstart for a complete embed integration.