Skip to main content
You can embed Deep Analysis in your own application with the GraphQL API. The Honeydew UI, the Slack and Teams apps, and the MCP server use the same calls: submit a question, then poll for messages as the analysis runs. If your application can wait for the full answer, ask_deep_analysis_question_sync returns it in one call, without progress.

​
Prerequisites

  • GraphQL API access for your organization, and an API key with Viewer role or higher
  • One or more agents to answer the questions

​
Architecture

Call Honeydew from your server, so the API key and secret never reach the browser. Your server sets the X-Honeydew-Workspace and X-Honeydew-Branch headers on every call. Chats belong to the user of the API key. To keep per-user ownership, give each end user a Honeydew user and a per-user API key, which support enables for your organization. Each chat then belongs to its end user, who also finds it in the Honeydew UI. With one shared key, your server records which end user owns each chat, and checks it before passing a chat ID to Honeydew.

​
Call flow

​
Steps

1

Create a chat

Call create_chat with the agent name, either a fixed agent or one picked by agent routing. Store the returned chat_id; follow-up questions use the same chat.
2

Subscribe to the chat

Call subscribe_to_chat with the chat_id. Subscribe before asking, so the queue receives every message of the analysis.
3

Ask the question

Call ask_deep_analysis_question. It returns null as soon as the analysis starts.
4

Poll for messages

Call get_new_messages every 5 seconds and render each message by its content type. Stop polling when a StopUpdate arrives.
5

Ask follow-ups

Call ask_deep_analysis_question again with the same chat_id, and poll the same subscription again. Show the suggested_responses of the StopUpdate as one-click follow-ups.

​
Route questions to an agent

Instead of a fixed agent, your server can let Honeydew pick one for each new conversation with agent routing. Before create_chat, call agents_for_question with the first question:
  • One agent: pass its name to create_chat.
  • Several agents: they come most relevant first. Let the user pick one, by its display_name.
  • No agent: tell the user that no agent fits the question, and create no chat.
To improve routing results, see What the Router Considers.

​
Render messages

To let users stop a running analysis, call abort_chat.

​
Reload and resume

To show a past conversation, call get_chat and render its history. The messages use the same format as get_new_messages. To continue it, or to resume after a subscription expired, call subscribe_to_chat with from_message_id set to the last message_id you have plus one. The queue then starts with the messages you missed. A chat with is_readonly: true can be shown but not continued: subscribe_to_chat and ask_deep_analysis_question return CHAT_IS_READONLY for it.
Polling counts toward the API rate limit, which applies per API key: every running chat on a shared key polls against the same budget, while per-user keys each get their own. Back off when a call fails.

​
Manage chats

  • List chats: get_all_chats returns the chats of the key’s user, newest first, with limit and offset for paging. A key with the Admin role also lists the chats of other users. With a shared key, filter the list by the chat owners your server records.
  • Fetch a chat: get_chat returns one chat by chat_id, with its history, as described under Reload and resume.
  • Rename a chat: rename_chat sets its title to new_title.
  • Give feedback: update_chat_feedback stores the user’s feedback on a chat, replacing earlier feedback. Pass null to clear it. The feedback appears in AI question history.
  • Delete a chat: delete_chat deletes a chat of the key’s user. It can no longer be listed, fetched or continued.