OpenAPI 概述

OpenAPI 是 Snail AI 提供的外部集成接口，面向第三方系统、自定义前端、聊天机器人等场景，允许外部应用通过标准 HTTP 接口接入 Snail AI 的核心能力。

适用场景

• 第三方系统集成：将 Snail AI 的智能体对话能力嵌入到企业内部系统（如 CRM、工单系统）
• 自定义前端：构建自定义的聊天界面，通过 OpenAPI 与 Snail AI 后端交互
• 聊天机器人：在飞书、钉钉、企业微信等即时通讯平台中接入智能体
• 知识库查询：将 RAG 知识库的搜索和问答能力开放给外部系统
• 自动化流程：在工作流自动化工具中调用智能体进行自动化处理

Base URL

{protocol}://{host}:{port}/snail-ai/open-api

示例：

http://localhost:8080/snail-ai/open-api

认证方式

OpenAPI 使用与 Admin API 相同的 Token 认证机制，通过 Snail-Ai-Auth HTTP Header 传递 JWT Token。

Snail-Ai-Auth: <your-token>

Token 可通过以下方式获取：

1. 用户登录：通过 Admin API 的 POST /snail-ai/user/login 接口获取
2. 应用 Token：在管理后台创建应用时自动生成的应用级 Token

详见 认证方式 文档。

可用接口

接口	说明
认证方式	Token 获取、管理与请求频率限制
对话接口	智能体流式对话（SSE）
知识库查询	知识库语义搜索与 RAG 问答

快速体验

1. 获取 Token

curl -X POST 'http://localhost:8080/snail-ai/user/login' \
  -H 'Content-Type: application/json' \
  -d '{"username": "admin", "password": "your-password"}'

2. 调用智能体对话

curl -X POST 'http://localhost:8080/snail-ai/open-api/chat' \
  -H 'Content-Type: application/json' \
  -H 'Snail-Ai-Auth: <your-token>' \
  -d '{
    "agentId": 1,
    "openId": "external-user-001",
    "content": "你好，请介绍一下你自己"
  }' \
  --no-buffer

3. 搜索知识库

curl -X POST 'http://localhost:8080/snail-ai/open-api/rag/search' \
  -H 'Content-Type: application/json' \
  -H 'Snail-Ai-Auth: <your-token>' \
  -d '{
    "ragId": 1,
    "query": "退款政策是什么？"
  }'

通用响应格式

{
  "code": 1,
  "msg": "success",
  "data": ...
}

错误码	说明
1	请求成功
0	通用业务错误
401	认证失败
403	权限不足
429	请求频率超限
500	服务器内部错误

与 Admin API 的区别

特性	Admin API	OpenAPI
面向对象	管理后台用户	第三方系统/外部用户
功能范围	全量管理功能	对话和查询功能
用户标识	系统内部用户 ID	外部自定义 openId
路径前缀	/snail-ai/	/snail-ai/open-api/
认证方式	JWT Token（Snail-Ai-Auth）	JWT Token（Snail-Ai-Auth）