Yunqi (ClickZetta / Singdata Lakehouse)

Yunqi Analytics Agent Open API

Embeds Analytics Agent natural-language analysis into third-party applications. An administrator-issued appSecretKey is exchanged for a loginToken; queries are asynchronous and polled until finished.

GitHub OpenAPI

Operations 5

GET /open/api/v1/appSecretKey/generateAuthToken 获取认证 Token #
POST /open/session/safe_new 创建对话会话 #
POST /open/text2insight/query 发起数据分析请求 #
POST /open/safe_question_poll 轮询问题结果 #
POST /open/text2insight/stop 停止问题 #

Documentation

📖
GettingStarted
https://www.yunqi.tech/documents/open-api-quick-start

Specifications

⚙
OpenAPI
https://artifacts.apis.io/yunqi/openapi/yunqi-analytics-agent-api-openapi.yml

Other Resources

🔗
ChangeLog
https://www.yunqi.tech/documents/datagpt-release
🔗
APIsJSON
https://artifacts.apis.io/yunqi/apis.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/yunqi:yunqi-analytics-agent-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

yunqi-analytics-agent-api-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: ClickZetta Analytics Agent Open API
  version: 1.0.0
  summary: 把 Analytics Agent 的自然语言问数能力嵌入第三方应用。
  description: |
    Analytics Agent 开放 API 让第三方应用以自然语言向指定数据域提问，并取回指标、SQL、图表数据和分析总结。
    图表渲染和报告排版由调用方自行完成。

    ## 调用流程
    1. **GenerateAuthToken**：用管理员分配的 `appSecretKey` 换取 `loginToken`。
    2. **CreateSession**（可选）：创建会话。同一会话可以连续提问，Agent 会保留上下文。
    3. **Text2InsightQuery**：提交问题，立即返回 `questionId`，状态为 `running`。
    4. **SafeQuestionPoll**：每 2 秒轮询一次，直到最后一条消息的 `dataType` 为 `finish`、`finish_stop` 或 `error`。
       建议单次请求超时 60 秒，总超时 360 秒。
    5. **Text2InsightStop**（可选）：停止仍在运行的问题，操作不可撤销。

    ## 认证
    `loginToken`、`tenantId`、`userId` 必须**同时**出现在 URL query 和 JSON 请求体中，缺少 query 参数会导致请求失败。
    Token 有有效期，过期后需要重新调用 GenerateAuthToken。
    `tenantId` 和 `userId` 可在产品左下角头像进入的设置页查看；`domainId` 是分析域设置页 URL 末尾的数字。

    ## 结果判断
    所有接口都返回 `{ "success": boolean, "data": ... }`。HTTP 200 只代表请求已返回，调用方必须检查 `success`。
    `success=false` 的常见原因：Token 无效或过期、参数缺失、会话或问题不存在、权限不足、模型不可用。
  contact:
    name: Singdata
    email: service@yunqi.tech
    url: https://www.yunqi.tech/documents/open-api-overview
  termsOfService: https://www.yunqi.tech/documents/user-agreement
externalDocs:
  description: Analytics Agent 开放 API 文档
  url: https://www.yunqi.tech/documents/open-api-overview
servers:
  - url: https://api.clickzetta.com/clickzetta-campaign-data
    description: 国内 SaaS 环境
  - url: https://ap-southeast-1-alicloud.api.singdata.com/clickzetta-campaign-data
    description: 海外 SaaS 环境（新加坡）。私有化部署的地址请向对接人获取。
security:
  - loginToken: []
tags:
  - name: Authentication
    description: 用应用密钥换取访问 Token。
    externalDocs:
      url: https://www.yunqi.tech/documents/open-api-generate-auth-token
  - name: Session
    description: 管理对话会话，一个会话可以包含多次连续问答。
    externalDocs:
      url: https://www.yunqi.tech/documents/open-api-create-session
  - name: Question
    description: 提交自然语言问题、轮询分析结果和停止分析。
    externalDocs:
      url: https://www.yunqi.tech/documents/open-api-response-guide

paths:
  /open/api/v1/appSecretKey/generateAuthToken:
    get:
      operationId: generateAuthToken
      summary: 获取认证 Token
      description: 用管理员分配的应用密钥换取 `loginToken`，后续所有接口都需要它。应用密钥在“管理 → 用户管理 → 编辑用户 → App Secret Key → + 生成Key”中生成，请妥善保管。
      tags: [Authentication]
      security: []
      parameters:
        - name: appSecretKey
          in: query
          required: true
          description: 应用密钥，由平台管理员生成并分配。
          schema:
            type: string
      responses:
        '200':
          description: 请求已返回。`success=false` 表示 appSecretKey 无效或已过期。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateAuthTokenResponse'
              examples:
                success:
                  summary: 获取成功
                  value: { success: true, data: { token: eyJhbGciOiJIUzI1NiJ9... } }
                invalidKey:
                  summary: 应用密钥无效或已过期
                  value: { success: false }
      externalDocs:
        url: https://www.yunqi.tech/documents/open-api-generate-auth-token

  /open/session/safe_new:
    post:
      operationId: createSession
      summary: 创建对话会话
      description: 在指定数据域下创建对话会话，返回 sessionId。已有 sessionId 时可以直接复用，不必每次提问都新建会话。
      tags: [Session]
      parameters:
        - $ref: '#/components/parameters/TenantIdQuery'
        - $ref: '#/components/parameters/UserIdQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
            example: { tenantId: 10, userId: 1, domainId: 106, title: Q1 销售分析, loginToken: eyJhbGciOiJIUzI1NiJ9... }
      responses:
        '200':
          description: 请求已返回。`success=false` 表示 Token 无效、参数缺失或权限不足。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSessionResponse'
              example: { success: true, data: 4729 }
      externalDocs:
        url: https://www.yunqi.tech/documents/open-api-create-session

  /open/text2insight/query:
    post:
      operationId: queryText2Insight
      summary: 发起数据分析请求
      description: 向 Analytics Agent 提交自然语言问题。接口是异步的，立即返回 questionId 和 `running` 状态，结果需要通过 SafeQuestionPoll 轮询获取。
      tags: [Question]
      parameters:
        - $ref: '#/components/parameters/TenantIdQuery'
        - $ref: '#/components/parameters/UserIdQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Text2InsightQueryRequest'
            example:
              tenantId: 10
              userId: 1
              domainId: 106
              sessionId: 4729
              msg: 给我看下北京二手房过去6年销售额，按区看
              loginToken: eyJhbGciOiJIUzI1NiJ9...
              modelSettings: { model_name: qwen/qwen3.6-plus }
      responses:
        '200':
          description: 请求已返回。`success=false` 表示 Token 无效、会话不存在、参数缺失或模型不可用。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Text2InsightQueryResponse'
              example: { success: true, data: { questionId: 34339, sessionId: 4729, status: running } }
      externalDocs:
        url: https://www.yunqi.tech/documents/open-api-text2insight-query

  /open/safe_question_poll:
    post:
      operationId: pollQuestion
      summary: 轮询问题结果
      description: |
        返回该问题到目前为止产生的全部消息。建议每 2 秒调用一次，单次请求超时 60 秒，总超时 360 秒。
        当 `responses` 最后一条消息的 `dataType` 为 `finish`、`finish_stop` 或 `error` 时停止轮询。
        典型消息顺序：notify → message（知识检索）→ message（执行过程）→ metric → code → echarts_plus → summary → finish。
      tags: [Question]
      parameters:
        - $ref: '#/components/parameters/TenantIdQuery'
        - $ref: '#/components/parameters/UserIdQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuestionRequest'
            example: { tenantId: 10, userId: 1, domainId: 106, questionId: 34339, loginToken: eyJhbGciOiJIUzI1NiJ9... }
      responses:
        '200':
          description: 请求已返回。`success=false` 表示 Token 无效、questionId 不存在或权限不足。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuestionPollResponse'
              examples:
                running:
                  summary: 分析进行中
                  value:
                    success: true
                    data:
                      responses:
                        - { id: '745601', dataType: notify, message: Thinking next step }
                finished:
                  summary: 分析完成（节选）
                  value:
                    success: true
                    data:
                      responses:
                        - id: '745620'
                          dataType: metric
                          message: 'Metric: 过去6年各区总成交金额'
                          metricDsl: '{"useDefaultLimit":true,"metricId":{"metricType":"SQL_SIMPLE","id":631}}'
                        - id: '745625'
                          dataType: echarts_plus
                          chartType: ECHARTS
                          calculateSql: SELECT region AS 区域, SUM(transaction_price) AS 总成交金额 FROM ... GROUP BY region
                        - id: '745630'
                          dataType: summary
                          message: Analysis complete
                          summaryData: "**北京二手房过去6年各区总成交金额：**\n- 朝阳区：10349.27 亿元\n- 海淀区：5850.22 亿元"
                        - { id: '745631', dataType: finish, message: Analysis complete }
      externalDocs:
        url: https://www.yunqi.tech/documents/open-api-safe-question-poll

  /open/text2insight/stop:
    post:
      operationId: stopText2Insight
      summary: 停止问题
      description: 停止一个仍在运行的问题，仅对 `running` 状态有效，操作不可撤销。停止后轮询结果的最后一条消息为 `finish_stop`。
      tags: [Question]
      parameters:
        - $ref: '#/components/parameters/TenantIdQuery'
        - $ref: '#/components/parameters/UserIdQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Text2InsightStopRequest'
            example: { tenantId: 10, userId: 1, sessionId: 4729, questionId: 34339, loginToken: eyJhbGciOiJIUzI1NiJ9... }
      responses:
        '200':
          description: 请求已返回。`success=false` 表示 Token 无效、问题不存在、问题已完成或权限不足。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example: { success: true }
      externalDocs:
        url: https://www.yunqi.tech/documents/open-api-text2insight-stop

components:
  securitySchemes:
    loginToken:
      type: apiKey
      in: query
      name: loginToken
      description: 通过 GenerateAuthToken 获取的认证 Token。必须同时放在 URL query 和 JSON 请求体的 `loginToken` 字段中。Token 有有效期，过期后需要重新获取。

  parameters:
    TenantIdQuery:
      name: tenantId
      in: query
      required: true
      description: 租户 ID，必须与请求体中的 tenantId 一致。
      schema: { type: integer, format: int64 }
    UserIdQuery:
      name: userId
      in: query
      required: true
      description: 用户 ID，必须与请求体中的 userId 一致。
      schema: { type: integer, format: int64 }

  schemas:
    AuthContext:
      type: object
      description: 每个请求体都要携带的身份字段，取值与 URL query 中的同名参数一致。
      required: [tenantId, userId, loginToken]
      properties:
        tenantId: { type: integer, format: int64, description: 租户 ID。 }
        userId: { type: integer, format: int64, description: 用户 ID。 }
        loginToken: { type: string, description: 通过 GenerateAuthToken 获取的认证 Token。 }

    CreateSessionRequest:
      description: CreateSession 的请求体。
      allOf:
        - $ref: '#/components/schemas/AuthContext'
        - type: object
          required: [domainId]
          properties:
            domainId: { type: integer, format: int64, description: 数据域 ID，对应一个数据集。 }
            title: { type: string, description: 会话标题，用于标识该会话。 }

    Text2InsightQueryRequest:
      description: Text2InsightQuery 的请求体。
      allOf:
        - $ref: '#/components/schemas/AuthContext'
        - type: object
          required: [domainId, sessionId, msg]
          properties:
            domainId: { type: integer, format: int64, description: 数据域 ID。 }
            sessionId: { type: integer, format: int64, description: 对话会话 ID，通过 CreateSession 获取或复用已有值。 }
            msg: { type: string, description: 问题内容，用自然语言描述的分析需求。 }
            modelSettings:
              $ref: '#/components/schemas/ModelSettings'

    ModelSettings:
      type: object
      description: 模型配置，不传时使用默认模型。
      properties:
        model_name: { type: string, description: 指定使用的模型名称，例如 qwen/qwen3.6-plus。 }

    QuestionRequest:
      description: SafeQuestionPoll 的请求体。
      allOf:
        - $ref: '#/components/schemas/AuthContext'
        - type: object
          required: [domainId, questionId]
          properties:
            domainId: { type: integer, format: int64, description: 数据域 ID。 }
            questionId: { type: integer, format: int64, description: 问题 ID，通过 Text2InsightQuery 获取。 }

    Text2InsightStopRequest:
      description: Text2InsightStop 的请求体。
      allOf:
        - $ref: '#/components/schemas/AuthContext'
        - type: object
          required: [sessionId, questionId]
          properties:
            sessionId: { type: integer, format: int64, description: 对话会话 ID。 }
            questionId: { type: integer, format: int64, description: 要停止的问题 ID。 }

    SuccessResponse:
      type: object
      description: 所有接口共用的响应外层。HTTP 200 时仍需检查 success。
      required: [success]
      properties:
        success: { type: boolean, description: 请求是否成功。 }

    GenerateAuthTokenResponse:
      description: GenerateAuthToken 的响应。
      allOf:
        - $ref: '#/components/schemas/SuccessResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                token: { type: string, description: 认证 Token，用于后续接口调用。 }

    CreateSessionResponse:
      description: CreateSession 的响应，data 即新建的 sessionId。
      allOf:
        - $ref: '#/components/schemas/SuccessResponse'
        - type: object
          properties:
            data: { type: integer, format: int64, description: 创建成功的 sessionId。 }

    Text2InsightQueryResponse:
      description: Text2InsightQuery 的响应。
      allOf:
        - $ref: '#/components/schemas/SuccessResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                questionId: { type: integer, format: int64, description: 问题 ID，用于轮询和停止。 }
                sessionId: { type: integer, format: int64, description: 会话 ID。 }
                status: { type: string, description: 当前状态，提交成功时为 running。, examples: [running] }

    QuestionPollResponse:
      description: SafeQuestionPoll 的响应。
      allOf:
        - $ref: '#/components/schemas/SuccessResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                responses:
                  type: array
                  description: 分析过程中产生的全部消息，按时间顺序排列。
                  items:
                    $ref: '#/components/schemas/AgentMessage'

    AgentMessage:
      type: object
      description: |
        Agent 产生的一条消息。业务字段可能出现在不同层级，按以下顺序读取：
        1. 消息顶层，例如 `summaryData`；
        2. `modelRes.data` 中的同名字段；
        3. 把 `rawRes` 解析为 JSON 后，读取其 `data` 中的同名字段。
      required: [id, dataType]
      properties:
        id: { type: string, description: 消息 ID。 }
        dataType:
          $ref: '#/components/schemas/AgentMessageType'
        message: { type: string, description: 消息文本，例如进度提示、指标名称或图表标题。 }
        modelRes:
          type: object
          description: 模型返回的原始结构。
          properties:
            code: { type: integer, description: 模型响应码，例如 200。 }
            data: { type: object, description: 模型返回的业务数据，字段同消息顶层。 }
        rawRes: { type: string, description: 原始结果的 JSON 字符串，顶层和 modelRes.data 都取不到字段时解析它。 }
        summaryData: { type: string, description: 'summary：Markdown 格式的分析总结；为空时读取 message。' }
        metricDsl: { type: string, description: 'metric：语义层指标 DSL（JSON 字符串）。' }
        physicalMetricDsl: { type: string, description: 'metric：物理层指标 DSL（JSON 字符串）。' }
        chartType: { type: string, description: 'echarts_plus：图表类型，例如 ECHARTS。' }
        columns: { description: 'echarts_plus：图表的列定义（列名和数据类型）。' }
        calculateSql: { type: string, description: 'echarts_plus：获取图表数据的 SQL。' }
        codeType: { type: string, description: 'code：代码语言，例如 sql。' }
        code: { type: string, description: 'code：生成的代码内容。' }
        knowledgeData:
          type: object
          description: 'message：知识检索结果，条目在 detailItems 中。'
          properties:
            detailItems:
              type: array
              items:
                type: object
                properties:
                  id: { type: integer, description: 知识条目 ID。 }
                  type: { type: string, description: 条目类型，例如 TEXT。 }
                  value: { type: string, description: 条目内容。 }

    AgentMessageType:
      type: string
      description: |
        消息类型：
        - `notify`：进度提示，例如“正在思考”
        - `message`：知识检索结果或执行过程日志
        - `metric`：指标计算结果，包含 DSL
        - `code`：生成的代码，通常是 SQL
        - `echarts_plus`：图表数据
        - `summary`：最终分析总结
        - `finish`：分析正常结束（终止状态）
        - `finish_stop`：用户主动停止（终止状态）
        - `error`：执行出错（终止状态）
      enum: [notify, message, metric, code, echarts_plus, summary, finish, finish_stop, error]