canonical: https://jentic.com/apis/arena.fi/arena-fi

# Arena Fi SmartDialog API

Jentic publishes the only available OpenAPI specification for SmartDialog API, keeping it validated and agent-ready. SmartDialog is Arena's conversational platform API for managing dialog flows and the conversations that run through them. Five endpoints cover dialog definition (list, create, fetch, update) and conversation retrieval, so an agent can assemble new dialog flows or read the conversation history that customers have produced inside them.

## For AI agents

Define and manage dialog flows on the SmartDialog platform and read back conversation transcripts produced by those flows.

## Scope

Does not handle SMS sending, voice telephony, or message broadcasting - use for SmartDialog flow configuration and conversation retrieval only.

## Capabilities

- List dialog flow definitions stored on the SmartDialog platform
- Create a new dialog flow with steps and routing logic
- Fetch a single dialog by id with its current configuration
- Update an existing dialog's configuration
- Retrieve conversation transcripts produced by a dialog flow

## Use cases

### Conversational Self-Service Deployment

Configure SmartDialog flows for customer self-service in industries such as utilities and public services, where end-users complete tasks through scripted conversational steps. The dialogs endpoint handles flow CRUD and the conversations endpoint exposes the transcripts each flow has produced, so deployment and quality monitoring can be scripted rather than done manually in a dashboard.

Example prompt: Create a SmartDialog flow named 'meter-reading-2026' with three steps and confirm it appears in GET /dialogs

### Conversation Quality Audit

Audit conversations handled by a SmartDialog flow by pulling the transcripts via /conversations and feeding them into a review pipeline that flags failed intents or escalation triggers. This lets ops teams measure dialog effectiveness without manual log scraping.

Example prompt: Fetch the latest conversations from /conversations and summarise which dialog flows had the most escalations to a human agent

### Dialog Versioning Workflow

Maintain dialog flow versions in source control by reading the dialog definition via GET `/dialogs/{id}`, storing it in a repo, and pushing updates back via the update endpoint. This brings change history to a domain that is usually managed inside a vendor UI.

Example prompt: Pull the JSON definition for dialog id 42 via GET `/dialogs/42`, commit it to git, and after editing push the updated definition back via the dialog update endpoint

### Agent-Driven Dialog Management via Jentic

Give an internal agent a single tool that creates and inspects SmartDialog flows on demand. The agent searches Jentic for 'create a SmartDialog dialog', loads the schema, and executes - without an operator needing to log into the SmartDialog dashboard.

Example prompt: Search Jentic for 'create a SmartDialog dialog', load the schema, and execute to spin up a new flow for handling password reset conversations

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/dialogs` | List dialog flows |
| POST | `/dialogs` | Create a new dialog flow |
| GET | `/dialogs/{id}` | Fetch a dialog by id |
| PUT | `/dialogs/{id}` | Update an existing dialog |
| GET | `/conversations` | List conversations handled by dialogs |

## Key resources

- **Dialogs** — Create, list, fetch, and update conversational dialog flow definitions
- **Conversations** — Retrieve conversation transcripts produced by dialog flows

## Why Jentic

- **Setup:** Wiring the SmartDialog API by hand means learning its bearer auth and threading dialog ids through its flow-configuration paths yourself. Through Jentic you install once, import the SmartDialog API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** SmartDialog puts the dialog id in the URL path (`/dialogs/{id}`), so a rule can pin your agent to reading and updating specific dialogs. You choose the operations it may call, so creating dialogs is not included unless you add it.
- **Credential handling:** Your SmartDialog bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a SmartDialog dialog' or 'list conversations', and Jentic returns the matching SmartDialog operation with its input schema so the agent calls the right endpoint without browsing docs.

## Related APIs

- **Slack API** — Slack handles internal team messaging while SmartDialog handles end-customer conversational flows
- **Discord API** — Discord exposes generic chat and bot primitives; SmartDialog exposes scripted conversational flows aimed at customer self-service
- **Calendly API** — Calendly schedules the human handoff after a SmartDialog flow escalates beyond self-service

## FAQ

### Why is there no official OpenAPI spec for SmartDialog API?

Arena does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call SmartDialog API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the SmartDialog API use?

SmartDialog uses HTTP Bearer token authentication on the Authorization header. Through Jentic, the token is held encrypted in the vault and supplied to the call at runtime, so the agent context never holds the raw secret.

### Can I create dialog flows programmatically with the SmartDialog API?

Yes. POST /dialogs accepts a dialog definition body and creates a new flow. GET `/dialogs/{id}` returns the resulting configuration so you can verify the create succeeded.

### What are the rate limits for the SmartDialog API?

Arena does not publish hard rate limits in the public spec. In practice, the platform is meant for management traffic rather than message-per-second loads - keep dialog list polling to once per minute or less and rely on conversation listings for batch reads.

### How do I list all dialogs through Jentic?

Run pip install jentic, then search Jentic with 'list SmartDialog dialogs', load the returned schema for GET /dialogs, and execute. The response is a list of dialog flow definitions you can iterate over.

### Can I read the conversations a dialog has handled?

Yes. GET /conversations returns conversation records produced by dialogs, which you can filter to a specific dialog via the appropriate query parameter described in the spec.

### Can I limit what my agent is allowed to do with the SmartDialog API?

Yes. You run Jentic One yourself, so your own rules decide which SmartDialog operations the agent may call and which bearer token it uses. Because the dialog id sits in the URL path at `/dialogs/{id}`, you can pin the agent to fetching and updating specific dialogs while excluding creation via POST /dialogs and transcript reads via GET /conversations. Only the operations you allow are ever available to the agent.