Read the users, conversations, messages, and runs captured by your HeroUI Agent.
The HeroUI Agents API is a read-only HTTP API for querying the data captured by an Agent. Every request is scoped to the Agent that owns the supplied API key, so one key cannot read another Agent's data.
This API is for server-to-server requests. To embed an Agent in your product, use the React SDK 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.
Pass an Agent API key as a Bearer token in the Authorization header:
curl "https://api.heroui.pro/v1/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 an Agent API key in browser code. The interactive API playground is deliberately disabled so a customer key is never sent through the browser or documentation server.
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 usage, latency, and tool activity. |
Only assign the permissions that a server integration needs. API keys created before scoped data access was introduced retain only auth_tokens:create; they do not inherit read access.
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.
The React SDK embeds the hosted Agent and exposes client-side tools and controls. Import it from @heroui/agent, or use the Next.js entry point at @heroui/agent/next.
| Entry point | Use |
|---|---|
@heroui/agent | React component, hook, tool helper, model constants, and public types. |
@heroui/agent/next | Next.js-compatible mirror of the React SDK. |
@heroui/agent/contracts | Edge-compatible schemas and shared protocol contracts. |
@heroui/agent/server | Server-only managed-key exchange helper. |
@heroui/agent/css | Required embed stylesheet. |
See the Quickstart for a complete embed integration.