Skip to content
Amio Docs

Endpoints

This is a hand-written first version. A full machine-readable (OpenAPI) spec is coming and will replace this page.

All requests need the Authorization: Bearer <token> header, see Authentication. The base URL is https://chatbot-engine.amio.io. Request and response bodies are JSON with snake_case field names. Paths with :botId, :answerId and similar are IDs returned by the list endpoints. Bot-scoped paths return 404 for bots outside your organization.

Common tasks

Section titled “Common tasks”

List bots

Section titled “List bots”

GET /bots returns your bots with id, name, language, timezone, type, is_active, chat_theme_id, and market_id.

Terminal window
curl https://chatbot-engine.amio.io/bots -H "Authorization: Bearer $AMIO_TOKEN"

List answers

Section titled “List answers”

GET /bots/:botId/answers returns every answer of the bot with id, name, published, intent, and request_outcome.

Terminal window
curl https://chatbot-engine.amio.io/bots/$BOT_ID/answers -H "Authorization: Bearer $AMIO_TOKEN"

GET /bots/:botId/answers/:answerId returns one answer including its conversation.

Create an answer

Section titled “Create an answer”

POST /bots/:botId/answers returns 201 with the new answer.

Field Type Notes
name string Optional, 1 to 255 characters.
conversation_json object Required. The answer’s message flow, in the same structure GET returns.

In a multi-bot, only the primary variant can create answers (otherwise 409).

Terminal window
curl -X POST https://chatbot-engine.amio.io/bots/$BOT_ID/answers \
  -H "Authorization: Bearer $AMIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Opening hours", "conversation_json": { ... }}'

Update an answer

Section titled “Update an answer”

PATCH /bots/:botId/answers/:answerId. Send only the fields you change.

Field Type Notes
name string 1 to 255 characters.
published boolean Publish or unpublish the answer.
conversation_json object New message flow.
conversation_json_hash string Hash of the flow, as sent by the admin.
inherit_conversation boolean For non-primary multi-bot variants: use the primary’s flow.
template_refs, variable_refs, answer_refs object Each has required creates and deletes arrays. Tracks which blocks, variables, and answers the flow uses.
Terminal window
curl -X PATCH https://chatbot-engine.amio.io/bots/$BOT_ID/answers/$ANSWER_ID \
  -H "Authorization: Bearer $AMIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Opening hours (updated)", "published": true}'

List knowledge bases

Section titled “List knowledge bases”

GET /indexes returns your knowledge bases with id, name, schedule_params, index_group_id, market_id, and sources (each with id, type, format, url, name).

Terminal window
curl https://chatbot-engine.amio.io/indexes -H "Authorization: Bearer $AMIO_TOKEN"

Trigger a re-index

Section titled “Trigger a re-index”

POST /indexes/:indexId/executions queues an indexing run and returns 201 with the execution. It takes no body. Poll GET /indexes/:indexId/executions/:executionId for progress, or list runs with GET /indexes/:indexId/executions?max=10&offset=0.

Terminal window
curl -X POST https://chatbot-engine.amio.io/indexes/$INDEX_ID/executions \
  -H "Authorization: Bearer $AMIO_TOKEN"

Create a knowledge base

Section titled “Create a knowledge base”

POST /indexes.

Field Type Notes
name string Required.
sources array Required, at least one. Each source has type (for example web_scraping, url), url, and optional format and config. The URL is checked on creation.
schedule_params object or null { "cronExpression": "..." } for scheduled re-indexing.
index_group_id, market_id string or null Optional assignment.

PATCH /indexes/:indexId accepts name, schedule_params, index_group_id, market_id.

Endpoint list

Section titled “Endpoint list”

Bots

Section titled “Bots”
  • GET /bots: list bots.
  • GET /bots/:botId: get a bot including its bot JSON.
  • PATCH /bots/:botId: update bot settings.
  • DELETE /bots/:botId: delete a bot and its data.
  • POST /bots/:botId/clone: clone a bot.
  • POST /bots/:botId/deactivate: deactivate a bot.
  • PUT /bots/:botId/variables: update the variables assigned to a bot.
  • POST /bots/:botId/nlp-provider: set the bot’s NLP provider.
  • GET /bots/:botId/agent-settings: get AI agent settings.
  • PUT /bots/:botId/agent-settings: replace AI agent settings.
  • GET /bots/:botId/bot-email-config: get the bot’s email configuration.
  • PATCH /bots/:botId/bot-email-config: update the email configuration.
  • POST /bots/:botId/email-preview: render an email preview.
  • GET /bot-templates: list starter bot templates.

Answers

Section titled “Answers”
  • GET /bots/:botId/answers: list answers.
  • POST /bots/:botId/answers: create an answer.
  • GET /bots/:botId/answers/:answerId: get an answer.
  • PATCH /bots/:botId/answers/:answerId: update an answer.
  • DELETE /bots/:botId/answers/:answerId: delete an answer.
  • GET /bots/:botId/answers/:answerId/variants: list multi-bot variants of the answer.
  • GET /bots/:botId/answers/:answerId/references: list what the answer references.
  • GET /bots/:botId/answers/:answerId/referenced-conversations: conversations that reference the answer.
  • GET /bots/:botId/answers/:answerId/referenced-variables: variables used by the answer.

Events

Section titled “Events”
  • GET /bots/:botId/events: list events.
  • POST /bots/:botId/events: create an event.
  • GET /bots/:botId/events/:eventId: get an event.
  • PATCH /bots/:botId/events/:eventId: update an event.
  • DELETE /bots/:botId/events/:eventId: delete an event.
  • GET /bots/:botId/events/:eventId/variants: list multi-bot variants.
  • GET /bots/:botId/events/:eventId/referenced-conversations: conversations that reference the event.
  • GET /bots/:botId/events/:eventId/referenced-variables: variables used by the event.

Blocks (templates)

Section titled “Blocks (templates)”
  • GET /bots/:botId/templates: list blocks.
  • POST /bots/:botId/templates: create a block.
  • GET /bots/:botId/templates/:templateId: get a block.
  • PATCH /bots/:botId/templates/:templateId: update a block.
  • DELETE /bots/:botId/templates/:templateId: delete a block.
  • GET /bots/:botId/templates/:templateId/variants: list multi-bot variants.
  • GET /bots/:botId/templates/:templateId/references: list what the block references.
  • GET /bots/:botId/templates/:templateId/referenced-conversations: conversations that use the block.
  • GET /bots/:botId/templates/:templateId/referenced-variables: variables used by the block.

Intents and NLP models

Section titled “Intents and NLP models”
  • GET /intents/:intentId: get an intent.
  • PATCH /intents/:intentId: update an intent.
  • POST /nlp-models: create an NLP model.

Multi-bots

Section titled “Multi-bots”
  • GET /multi-bots: list multi-bots.
  • POST /multi-bots: create a multi-bot.
  • GET /multi-bots/:multiBotId: get a multi-bot.
  • PATCH /multi-bots/:multiBotId: update a multi-bot.
  • DELETE /multi-bots/:multiBotId: delete a multi-bot.
  • POST /multi-bots/:multiBotId/variants: add a variant bot.
  • GET /multi-bots/:multiBotId/variants/:botId/progress: progress of a variant being created.
  • DELETE /multi-bots/:multiBotId/variants/:botId: remove a variant.

Knowledge bases (indexes)

Section titled “Knowledge bases (indexes)”
  • GET /indexes: list knowledge bases.
  • POST /indexes: create a knowledge base.
  • GET /indexes/:indexId: get a knowledge base.
  • PATCH /indexes/:indexId: update a knowledge base.
  • DELETE /indexes/:indexId: delete a knowledge base.
  • GET /indexes/embedding-models: list available embedding models.
  • POST /indexes/:indexId/search: run a test search (query required; optional top_n 1 to 100, mode of raw, rag, or products, language).
  • POST /indexes/:indexId/sources: add a source.
  • PATCH /indexes/:indexId/sources/:sourceId: update a source.
  • DELETE /indexes/:indexId/sources/:sourceId: remove a source.
  • POST /indexes/:indexId/executions: start an indexing run.
  • GET /indexes/:indexId/executions: list runs.
  • GET /indexes/:indexId/executions/:executionId: get a run.

Index groups

Section titled “Index groups”
  • GET /index-groups: list index groups.
  • POST /index-groups: create a group.
  • GET /index-groups/:groupId: get a group.
  • PATCH /index-groups/:groupId: update a group.
  • DELETE /index-groups/:groupId: delete a group.

Tools

Section titled “Tools”
  • GET /tools: list tools.
  • POST /tools: create a tool.
  • GET /tools/:toolId: get a tool.
  • PATCH /tools/:toolId: update a tool.
  • DELETE /tools/:toolId: delete a tool.
  • GET /tools/:toolId/references: list where the tool is used.
  • POST /tools/:toolId/test: run a test call of the tool.
  • POST /mcp/list-tools: discover the tools offered by an MCP server.

Variables

Section titled “Variables”
  • GET /variables: list variables.
  • POST /variables: create a variable.
  • PATCH /variables/:variableId: update a variable.
  • DELETE /variables/:variableId: delete a variable.
  • GET /variables/:variableId/references: list where the variable is used.

Markets

Section titled “Markets”
  • GET /markets: list markets.
  • POST /markets: create a market.
  • GET /markets/:marketId: get a market.
  • PATCH /markets/:marketId: update a market.
  • DELETE /markets/:marketId: delete a market.

Chat themes

Section titled “Chat themes”
  • GET /chat-themes: list chat themes.
  • POST /chat-themes: create a theme.
  • GET /chat-themes/:chatThemeId: get a theme.
  • PATCH /chat-themes/:chatThemeId: update a theme.
  • DELETE /chat-themes/:chatThemeId: delete a theme.

Analytics

Section titled “Analytics”
  • GET /analytics/request-outcomes: request outcome statistics (gzip-compressed).
  • GET /analytics/user-feedback: user feedback ratings.
  • GET /analytics/bot-stats-csv: bot statistics as CSV.
  • GET /analytics/conversations: list conversations.
  • GET /analytics/conversations/:contactId/history: message history of a conversation.
  • GET /analytics/conversations/:contactId/requests: the individual requests of a conversation.

Integrations

Section titled “Integrations”
  • GET /integrations: list integrations.
  • POST /bots/:botId/integrations: add an integration to a bot.
  • PATCH /bots/:botId/integrations/:integrationId: update an integration.
  • DELETE /bots/:botId/integrations/:integrationId: remove an integration.

Deployments

Section titled “Deployments”
  • GET /deployments: list deployments across the organization.
  • GET /bots/:botId/deployments: list the bot’s deployments.
  • POST /bots/:botId/deployments: create a channel and deploy the bot to it.
  • PUT /bots/:botId/deployments: deploy the bot to an existing channel.
  • DELETE /bots/:botId/deployments: remove a deployment.

Files

Section titled “Files”
  • POST /files/upload: upload a file (multipart) and get back its URL.

Utils

Section titled “Utils”
  • POST /utils/test-api-call: test an external API call configuration.
  • GET /utils/preview-xml-feed: preview an XML product feed.
  • POST /utils/site-identity: analyze a website’s identity (name, colors) for onboarding.
  • POST /utils/bug-report: submit a bug report.
  • GET /utils/plain-chat-identity: identity for the support chat in the admin.
  • GET /utils/plain-chat-unread: unread count for the support chat.
  • POST /utils/daktela-email-details: look up Daktela email details.