Hanzo
API Reference

Hanzo Chat API

REST API for Hanzo Chat, an AI chat interface with multi-model support,

REST API for Hanzo Chat, an AI chat interface with multi-model support,

Hanzo Chat API · Guide & examples → · All API references →

Base URLhttps://hanzo.chat
Version1.0.0
Operations206
GuideHanzo Chat API guide

Authentication

  • BearerAuth — HTTP bearer

All Hanzo APIs share one bearer credential and common error and pagination conventions. See API conventions.

curl -H "Authorization: Bearer $HANZO_API_KEY" https://hanzo.chat

Endpoints

API Keys

MethodEndpointDescription
GET/v1/chat/api-keysList agent API keys
POST/v1/chat/api-keysCreate an agent API key
GET/v1/chat/api-keys/{id}Get an API key by ID
DELETE/v1/chat/api-keys/{id}Delete an API key

Actions

MethodEndpointDescription
GET/v1/chat/agents/actionsList agent actions
POST/v1/chat/agents/actions/{agent_id}Add or update actions for an agent
DELETE/v1/chat/agents/actions/{agent_id}/{action_id}Delete an agent action
POST/v1/chat/assistants/v1/actions/{assistant_id}Add or update actions for an assistant (v1)
DELETE/v1/chat/assistants/v1/actions/{assistant_id}/{action_id}/{model}Delete an assistant action (v1)
POST/v1/chat/assistants/v2/actions/{assistant_id}Add or update actions for an assistant (v2)
DELETE/v1/chat/assistants/v2/actions/{assistant_id}/{action_id}/{model}Delete an assistant action (v2)
POST/v1/chat/actions/{action_id}/oauth/bindSet CSRF cookie for action OAuth flow
GET/v1/chat/actions/{action_id}/oauth/callbackAction OAuth callback

Admin Auth

MethodEndpointDescription
POST/v1/chat/admin/login/localAdmin local login
GET/v1/chat/admin/verifyVerify admin session
GET/v1/chat/admin/oauth/openid/checkCheck if OpenID is configured for admin
GET/v1/chat/admin/oauth/openidInitiate admin OpenID login
GET/v1/chat/admin/oauth/openid/callbackAdmin OpenID callback
POST/v1/chat/admin/oauth/exchangeExchange OAuth code for admin tokens

Agents

MethodEndpointDescription
GET/v1/chat/agentsList agents
POST/v1/chat/agentsCreate an agent
GET/v1/chat/agents/categoriesGet agent categories with counts
GET/v1/chat/agents/{id}Get an agent (basic info)
PATCH/v1/chat/agents/{id}Update an agent
DELETE/v1/chat/agents/{id}Delete an agent
GET/v1/chat/agents/{id}/expandedGet agent with full configuration details
POST/v1/chat/agents/{id}/duplicateDuplicate an agent
POST/v1/chat/agents/{id}/revertRevert agent to a previous version
GET/v1/chat/agents/toolsList available agent tools
GET/v1/chat/agents/tools/callsGet tool call history
GET/v1/chat/agents/tools/{toolId}/authVerify tool authentication
POST/v1/chat/agents/tools/{toolId}/callExecute a tool call
POST/v1/chat/agents/chatChat with an agent
POST/v1/chat/agents/chat/{endpoint}Chat with an ephemeral agent
POST/v1/chat/agents/chat/abortAbort an ongoing agent generation
GET/v1/chat/agents/chat/stream/{streamId}Subscribe to a generation stream
GET/v1/chat/agents/chat/activeGet active generation job IDs
GET/v1/chat/agents/chat/status/{conversationId}Check generation status for a conversation

Agents - Open Responses

MethodEndpointDescription
POST/v1/chat/agents/v1/responsesCreate a response
GET/v1/chat/agents/v1/responses/modelsList agents as models
GET/v1/chat/agents/v1/responses/{id}Get a stored response

Agents - OpenAI Compatible

MethodEndpointDescription
POST/v1/chat/agents/v1/chat/completionsOpenAI-compatible chat completions
GET/v1/chat/agents/v1/modelsList agents as models
GET/v1/chat/agents/v1/models/{model}Get agent/model details

Assistants v1

MethodEndpointDescription
GET/v1/chat/assistants/v1List assistants (v1)
POST/v1/chat/assistants/v1Create an assistant (v1)
GET/v1/chat/assistants/v1/{id}Retrieve an assistant (v1)
PATCH/v1/chat/assistants/v1/{id}Modify an assistant (v1)
DELETE/v1/chat/assistants/v1/{id}Delete an assistant (v1)
GET/v1/chat/assistants/v1/documentsGet assistant documents
GET/v1/chat/assistants/v1/toolsList available assistant tools
POST/v1/chat/assistants/v1/chatChat with an assistant (v1)
POST/v1/chat/assistants/v1/chat/abortAbort assistant chat (v1)

Assistants v2

MethodEndpointDescription
GET/v1/chat/assistants/v2List assistants (v2)
POST/v1/chat/assistants/v2Create an assistant (v2)
GET/v1/chat/assistants/v2/{id}Retrieve an assistant (v2)
PATCH/v1/chat/assistants/v2/{id}Modify an assistant (v2)
DELETE/v1/chat/assistants/v2/{id}Delete an assistant (v2)
GET/v1/chat/assistants/v2/documentsGet assistant documents (v2)
GET/v1/chat/assistants/v2/toolsList available assistant tools (v2)
POST/v1/chat/assistants/v2/chatChat with an assistant (v2)
POST/v1/chat/assistants/v2/chat/abortAbort assistant chat (v2)

Auth

MethodEndpointDescription
POST/v1/chat/auth/loginLogin
POST/v1/chat/auth/logoutLogout
POST/v1/chat/auth/refreshRefresh token
POST/v1/chat/auth/registerRegister a new user
POST/v1/chat/auth/requestPasswordResetRequest password reset email
POST/v1/chat/auth/resetPasswordReset password with token
GET/v1/chat/auth/2fa/enableEnable 2FA
POST/v1/chat/auth/2fa/verifyVerify 2FA setup
POST/v1/chat/auth/2fa/verify-tempVerify 2FA with temporary token
POST/v1/chat/auth/2fa/confirmConfirm 2FA activation
POST/v1/chat/auth/2fa/disableDisable 2FA
POST/v1/chat/auth/2fa/backup/regenerateRegenerate 2FA backup codes
GET/v1/chat/auth/graph-tokenGet Microsoft Graph token

Avatar

MethodEndpointDescription
POST/v1/chat/assistants/v2/avatar/{assistant_id}Upload assistant avatar (v2)
POST/v1/chat/files/images/avatarUpload user avatar
POST/v1/chat/files/images/agents/{agent_id}/avatarUpload agent avatar
POST/v1/chat/files/images/assistants/{assistant_id}/avatarUpload assistant avatar (v1)

Balance

MethodEndpointDescription
GET/v1/chat/balanceGet user token balance
MethodEndpointDescription
GET/v1/chat/bannerGet server announcement banner

Categories

MethodEndpointDescription
GET/v1/chat/categoriesGet all categories

Config

MethodEndpointDescription
GET/v1/chat/configGet startup configuration

Conversations

MethodEndpointDescription
GET/v1/chat/convosList conversations
DELETE/v1/chat/convosDelete a conversation
GET/v1/chat/convos/{conversationId}Get a conversation
GET/v1/chat/convos/gen_title/{conversationId}Get generated title for conversation
DELETE/v1/chat/convos/allDelete all conversations
POST/v1/chat/convos/archiveArchive or unarchive a conversation
POST/v1/chat/convos/updateUpdate a conversation title
POST/v1/chat/convos/importImport conversations from JSON file
POST/v1/chat/convos/forkFork a conversation
POST/v1/chat/convos/duplicateDuplicate a conversation

Endpoints

MethodEndpointDescription
GET/v1/chat/endpointsGet configured endpoints

Files

MethodEndpointDescription
GET/v1/chat/filesList user files
POST/v1/chat/filesUpload a file
DELETE/v1/chat/filesDelete files
GET/v1/chat/files/configGet file upload configuration
GET/v1/chat/files/agent/{agent_id}Get files for an agent
GET/v1/chat/files/download/{userId}/{file_id}Download a file
GET/v1/chat/files/code/download/{session_id}/{fileId}Download code execution output

Images

MethodEndpointDescription
POST/v1/chat/files/imagesUpload an image

Keys

MethodEndpointDescription
GET/v1/chat/keysGet user key expiry info
PUT/v1/chat/keysCreate or update a user API key
DELETE/v1/chat/keysDelete all user keys
DELETE/v1/chat/keys/{name}Delete a user key by name

MCP

MethodEndpointDescription
GET/v1/chat/mcp/toolsGet all available MCP tools
GET/v1/chat/mcp/connection/statusGet connection status for all MCP servers
GET/v1/chat/mcp/connection/status/{serverName}Get connection status for a specific MCP server
GET/v1/chat/mcp/{serverName}/auth-valuesCheck which auth values exist for an MCP server
POST/v1/chat/mcp/{serverName}/reinitializeReinitialize an MCP server
GET/v1/chat/mcp/{serverName}/oauth/initiateInitiate MCP OAuth flow
GET/v1/chat/mcp/{serverName}/oauth/callbackMCP OAuth callback
POST/v1/chat/mcp/{serverName}/oauth/bindSet CSRF binding cookie for MCP OAuth
GET/v1/chat/mcp/oauth/tokens/{flowId}Get OAuth tokens for a completed flow
GET/v1/chat/mcp/oauth/status/{flowId}Check OAuth flow status
POST/v1/chat/mcp/oauth/cancel/{serverName}Cancel an OAuth flow
GET/v1/chat/mcp/serversList user-managed MCP servers
POST/v1/chat/mcp/serversCreate a user-managed MCP server
GET/v1/chat/mcp/servers/{serverName}Get an MCP server by name
PATCH/v1/chat/mcp/servers/{serverName}Update an MCP server
DELETE/v1/chat/mcp/servers/{serverName}Delete an MCP server

Memories

MethodEndpointDescription
GET/v1/chat/memoriesGet all user memories
POST/v1/chat/memoriesCreate a memory
PATCH/v1/chat/memories/preferencesUpdate memory preferences
PATCH/v1/chat/memories/{key}Update a memory
DELETE/v1/chat/memories/{key}Delete a memory

Messages

MethodEndpointDescription
GET/v1/chat/messagesQuery messages
POST/v1/chat/messages/branchCreate a branch message
POST/v1/chat/messages/artifact/{messageId}Edit artifact content in a message
GET/v1/chat/messages/{conversationId}Get all messages in a conversation
POST/v1/chat/messages/{conversationId}Save a message to a conversation
GET/v1/chat/messages/{conversationId}/{messageId}Get a specific message
PUT/v1/chat/messages/{conversationId}/{messageId}Update a message
DELETE/v1/chat/messages/{conversationId}/{messageId}Delete a message
PUT/v1/chat/messages/{conversationId}/{messageId}/feedbackUpdate message feedback

Models

MethodEndpointDescription
GET/v1/chat/modelsList available models

OAuth

MethodEndpointDescription
GET/oauth/googleInitiate Google OAuth
GET/oauth/google/callbackGoogle OAuth callback
GET/oauth/facebookInitiate Facebook OAuth
GET/oauth/facebook/callbackFacebook OAuth callback
GET/oauth/openidInitiate OpenID Connect login
GET/oauth/openid/callbackOpenID Connect callback
GET/oauth/githubInitiate GitHub OAuth
GET/oauth/github/callbackGitHub OAuth callback
GET/oauth/discordInitiate Discord OAuth
GET/oauth/discord/callbackDiscord OAuth callback
GET/oauth/appleInitiate Apple OAuth
POST/oauth/apple/callbackApple OAuth callback
GET/oauth/samlInitiate SAML login
POST/oauth/saml/callbackSAML callback
GET/oauth/errorOAuth error handler

Permissions

MethodEndpointDescription
GET/v1/chat/permissions/search-principalsSearch for users and groups to grant permissions
GET/v1/chat/permissions/{resourceType}/rolesGet available roles for a resource type
GET/v1/chat/permissions/{resourceType}/effective/allGet effective permissions for all accessible resources
GET/v1/chat/permissions/{resourceType}/{resourceId}Get all permissions for a resource
PUT/v1/chat/permissions/{resourceType}/{resourceId}Bulk update permissions for a resource
GET/v1/chat/permissions/{resourceType}/{resourceId}/effectiveGet effective permissions for a specific resource

Presets

MethodEndpointDescription
GET/v1/chat/presetsList user presets
POST/v1/chat/presetsCreate or update a preset
POST/v1/chat/presets/deleteDelete a preset

Prompts

MethodEndpointDescription
GET/v1/chat/promptsList user prompts
POST/v1/chat/promptsCreate a new prompt group with initial prompt
GET/v1/chat/prompts/allGet all prompt groups (ACL-aware)
GET/v1/chat/prompts/groupsList prompt groups (paginated)
GET/v1/chat/prompts/groups/{groupId}Get a prompt group by ID
PATCH/v1/chat/prompts/groups/{groupId}Update a prompt group
DELETE/v1/chat/prompts/groups/{groupId}Delete a prompt group
POST/v1/chat/prompts/groups/{groupId}/promptsAdd a prompt to an existing group
GET/v1/chat/prompts/{promptId}Get a prompt
DELETE/v1/chat/prompts/{promptId}Delete a prompt
PATCH/v1/chat/prompts/{promptId}/tags/productionMake a prompt the production version

Roles

MethodEndpointDescription
GET/v1/chat/roles/{roleName}Get a role by name
PUT/v1/chat/roles/{roleName}/promptsUpdate prompt permissions for a role
PUT/v1/chat/roles/{roleName}/agentsUpdate agent permissions for a role
PUT/v1/chat/roles/{roleName}/memoriesUpdate memory permissions for a role
PUT/v1/chat/roles/{roleName}/people-pickerUpdate people picker permissions for a role
PUT/v1/chat/roles/{roleName}/mcp-serversUpdate MCP servers permissions for a role
PUT/v1/chat/roles/{roleName}/marketplaceUpdate marketplace permissions for a role
PUT/v1/chat/roles/{roleName}/remote-agentsUpdate remote agents permissions for a role
MethodEndpointDescription
GET/v1/chat/search/enableCheck if search is enabled

Settings

MethodEndpointDescription
GET/v1/chat/user/settings/favoritesGet user favorites
POST/v1/chat/user/settings/favoritesUpdate user favorites

Share

MethodEndpointDescription
GET/v1/chat/shareList shared links
GET/v1/chat/share/{shareId}Get shared conversation messages
PATCH/v1/chat/share/{shareId}Update a shared link
DELETE/v1/chat/share/{shareId}Delete a shared link
GET/v1/chat/share/link/{conversationId}Get shared link for a conversation
POST/v1/chat/share/{conversationId}Create a shared link

Speech

MethodEndpointDescription
POST/v1/chat/files/speech/sttSpeech to text
POST/v1/chat/files/speech/ttsStream text to speech
POST/v1/chat/files/speech/tts/manualManual text to speech
GET/v1/chat/files/speech/tts/voicesGet available TTS voices
GET/v1/chat/files/speech/config/getGet custom speech configuration

Tags

MethodEndpointDescription
GET/v1/chat/tagsGet all conversation tags
POST/v1/chat/tagsCreate a conversation tag
PUT/v1/chat/tags/{tag}Update a conversation tag
DELETE/v1/chat/tags/{tag}Delete a conversation tag
PUT/v1/chat/tags/convo/{conversationId}Update tags for a conversation

User

MethodEndpointDescription
GET/v1/chat/userGet current user
GET/v1/chat/user/termsGet terms acceptance status
POST/v1/chat/user/terms/acceptAccept terms of service
POST/v1/chat/user/pluginsUpdate user plugins
DELETE/v1/chat/user/deleteDelete user account
POST/v1/chat/user/verifyVerify email with token
POST/v1/chat/user/verify/resendResend verification email

Hanzo Chat API guide · All Hanzo APIs · OpenAPI spec

How is this guide?

On this page

AuthenticationEndpointsAPI KeysActionsAdmin AuthAgentsAgents - Open ResponsesAgents - OpenAI CompatibleAssistants v1Assistants v2AuthAvatarBalanceBannerCategoriesConfigConversationsEndpointsFilesImagesKeysMCPMemoriesMessagesModelsOAuthPermissionsPresetsPromptsRolesSearchSettingsShareSpeechTagsUser