AIPro API

Common calling conventions

To call the QuickBI OpenAPI, you sign requests with an AK/SK. The platform automatically identifies the user and organization from the AK, so you do not need to pass user_id or tenant_id. You also do not need to understand the internal authentication mechanism between QBI and ABI services.

Except for Server-Sent Events (SSE) APIs, all responses use the following structure:

{
  "success": true,
  "data": {},
  "message": null,
  "code": 200,
  "trace_id": "trace-id"
}

A business error is indicated by success=false and a specific code in the response, even though the HTTP status code is typically 200. In contrast, FastAPI returns an HTTP 422 status code for invalid request parameters.

Submit chat (asynchronous)

• Path: /openapi/v2/abi/chat/completions/async

• Method:POST

• Content-Type: application/json

• Description: Submits a plain-text chat asynchronously, immediately returning a session ID and a message ID. The caller then uses the SSE API to retrieve execution events.

• Input parameters

  Parameter	Type	Description	Required
  message	String	The user's message. Must be between 1 and 10,000 characters in length.	Yes
  session_id	String	The ID of an existing session, with a maximum length of 36 characters. If omitted, a new session is created.	No
  model	String	The model alias available to the tenant, such as qwen3.7-plus or deepseek-v4-pro. The maximum length is 64 characters. An empty string is equivalent to omitting the parameter. This parameter is ignored if mode is lite.	No
  mode	String	The session mode. Valid values are standard for full capabilities and lite for lightweight Q&A. The default is standard. This parameter applies only when creating a new session.	No
  options	Object	An object for toggling per-request features. These settings apply only to the current request. Currently supports enable_ask_user (Boolean). If false, the AI does not ask a clarification question and instead proceeds based on its default assumptions. If omitted, the system uses the server-side default. Setting this to true cannot override server-enforced limitations (e.g., the feature is always disabled if mode is lite). The API returns a 400 error if this object contains unknown keys or invalid value types.	No

• Return parameters

  Parameter	Type	Description
  session_id	String	The session ID.
  conversation_id	String	This field provides the message ID for the current chat turn. Use this ID to connect to the SSE stream.

• Request example

  {
    "message": "Analyze this month's sales trends",
    "model": "qwen3.7-plus",
    "mode": "standard",
    "options": {
      "enable_ask_user": false
    }
  }

• Response example

  {
    "success": true,
    "data": {
      "session_id": "s1",
      "conversation_id": "c1"
    },
    "message": null,
    "code": 202,
    "trace_id": "t1"
  }

• Common errors

  Code	Description
  400	The mode is invalid, the specified model is not in the list of model aliases available to the tenant, or the options object contains unknown keys or invalid value types.
  403	You do not have permission to access the specified session.
  404	The specified session does not exist.
  429	The user has insufficient credit.
  500/502	An internal server error occurred, or a call to the downstream CodeAgent service failed.

Get conversation event stream (query)

• API path: /openapi/v2/abi/chat/completions/async/stream

• Request method: GET

• Return type: text/event-stream

• Description: Gets or resumes an asynchronous conversation event stream. This fixed path is compatible with the precise URI signature verification rules of the QuickBI Open Platform and is the recommended format for gateway calls.

• Input parameters

  Parameter	Location	Type	Description	Required
  conversation_id	Query	String	Conversation message ID. Length: 1–36.	Yes
  last_event_id	Query	String	ID of the last received SSE event, used to resume the stream.	No
  Last-Event-ID	Header	String	Standard SSE resumption cursor. If both this header and the last_event_id parameter are provided, this header takes precedence.	No

• Response headers

  Header	Description
  X-Trace-Id	Request trace ID.
  X-Conversation-Id	Conversation message ID.
  Cache-Control	Fixed to no-cache.
  X-Accel-Buffering	Fixed to no to disable proxy buffering.

• Request example

  GET /openapi/v2/abi/chat/completions/async/stream?conversation_id=c1
  Last-Event-ID: 1721990000000-5

• Response example

  id: 1721990000001-0
  data: {"type":"message.content","data":{"text":"YoY sales increased"}}

You can replay completed conversations from the persistent record. The API returns a 404 code if the conversation does not exist or does not belong to the current user. If a conversation is in progress and Redis is unavailable, the API returns a 503 code.

Cancel an in-progress conversation

• API path: /openapi/v2/abi/chat/cancel

• Request method: POST

• Content-Type: application/json

• Description: Cancels an in-progress conversation in a specified session. Only the session owner can make this request. If no conversation is in progress, the request succeeds idempotently.

• Input parameters

  Parameter	Type	Description	Required
  session_id	String	The unique ID for the session. Must be 1 to 36 characters long.	Yes

• Request example

  {
    "session_id": "s1"
  }

• Response example

  {
    "success": true,
    "data": {
      "session_id": "s1"
    },
    "message": null,
    "code": 200,
    "trace_id": "t1"
  }

2. Agent integration

These interfaces are designed for external agents and dialogue systems, covering the complete workflow: discovering data, onboarding an asset, awaiting model training, making conversational queries, and reviewing query history. The platform automatically resolves the user and their organization from the customer AK, so the caller does not need to pass these identity parameters. All URIs use fixed paths and support only GET and POST methods.

Upload and publish component

• API path: /openapi/v2/abi/components/upload

• Request method: POST

• Content-Type: multipart/form-data

• API description: Creates and immediately publishes a custom component.

• Request parameters

  Parameter	Type	Description	Required
  package	File	A ZIP file of the component artifact, not exceeding 10 MB. The root directory or a single top-level wrapper directory must contain main.js and meta.js. The main.css file is optional.	Yes
  name	String	The component name. Must be unique within the tenant, non-empty after trimming leading and trailing whitespace, and have a maximum length of 200 characters.	Yes
  desc	String	A description for the component, with a maximum length of 200 characters.	No
  externalAssets	String	A string containing a JSON array of external dependencies. If provided, this value overrides the externals defined in the manifest file.	No
  sourceArchive	String	A Base64-encoded ZIP file of the source code. The data:*;base64, prefix is optional. The decoded file must not exceed 10 MB.	No
  thumbnail	File	A thumbnail for the component. Supported formats: png, jpg, jpeg, and svg. The file size must not exceed 200 KB.	No

• Response parameters

  Parameter	Type	Description
  componentId	String	The component ID.
  jsUrl	String	The URL of the main.js file.
  metaJsUrl	String	The URL of the meta.js file.
  cssUrl	String	The URL of the main.css file. This value is null if the file does not exist.
  sourceArchiveUrl	String	The URL of the source code archive.
  thumbnailUrl	String	The URL of the thumbnail.
  revision	String	The current revision.
  autoInstalled	Boolean	Indicates whether the component was automatically installed.

• Request example

  POST /openapi/v2/abi/components/upload
  Content-Type: multipart/form-data
  
  name=Sankey
  package=@sankey.zip
  thumbnail=@thumbnail.png

• Response example

  {
    "success": true,
    "data": {
      "componentId": "c1",
      "jsUrl": "/api/v2/abi/components/c1/assets?name=main.js&v=r1",
      "metaJsUrl": "/api/v2/abi/components/c1/assets?name=meta.js&v=r1",
      "cssUrl": null,
      "sourceArchiveUrl": null,
      "thumbnailUrl": null,
      "revision": "r1",
      "autoInstalled": true
    },
    "code": 200,
    "trace_id": "t1"
  }

Update component

• API path: /openapi/v2/abi/components/update

• Request method: POST

• Content-Type: multipart/form-data

• API description: Partially updates an existing component. Fields that are not provided in the request are not modified. Replacing the package file generates a new revision, but updating only the metadata, source code archive, or thumbnail does not change the revision.

• Request parameters

  Parameter	Type	Description	Required
  component_id	String	The ID of the component to update.	Yes
  name	String	The new component name, up to 200 characters. If left blank, the name is not updated.	No
  desc	String	The new description, up to 200 characters. To clear the existing description, provide an empty string.	No
  sourceArchive	String	The new Base64-encoded source code ZIP file.	No
  package	File	The new component artifact ZIP file. Validation rules are the same as for the upload API.	No
  thumbnail	File	The new thumbnail. Validation rules are the same as for the upload API.	No

• Response parameters: The response parameters are the same as those for the upload API, with an additional revisionChanged field that indicates whether the update created a new revision.

• Request example

  POST /openapi/v2/abi/components/update
  Content-Type: multipart/form-data
  
  component_id=c1
  desc=Updated component description

List components

• API path: /openapi/v2/abi/components/list

• Request method: GET

• API description: Retrieves the components available to the current tenant.

• Response parameters: The response returns anitems array and atotal count. If the results are not paginated, total equals the length of the items array.

• Request example

  GET /openapi/v2/abi/components/list?keyword=Sankey&page=1&page_size=20

Get component details

• API path: /openapi/v2/abi/components/detail

• Request method: GET

• Request parameters

  Parameter	Type	Description	Required
  component_id	String	The ID of the component.	Yes

• Response parameters: The response returns componentId, name, desc, metaJson, externalAssets, packageFilename, jsUrl, metaJsUrl, cssUrl, sourceArchiveUrl, thumbnailUrl, currentRevision, visibilityType, enabled, created_at, and updated_at.

Read component asset

• API path: /openapi/v2/abi/components/asset

• Request method: GET

• API description: Reads the text content of a compiled component asset. This API is intended for use in a sandbox environment or with a personal access key (AK) and secret key (SK).

• Request parameters

  Parameter	Type	Description	Required
  component_id	String	The ID of the component. Must belong to the current tenant.	Yes
  name	String	The name of the asset. Allowed values are main.js, meta.js, and main.css.	Yes

• Response parameters: The response returns name, content, contentType, and revision.

• Request example

  GET /openapi/v2/abi/components/asset?component_id=c1&name=meta.js

• Response example

  {"success":true,"data":{"name":"meta.js","content":"{...}","contentType":"text/javascript;charset=utf-8","revision":"r1"},"code":200,"trace_id":"t1"}

Delete component

• API path: /openapi/v2/abi/components/delete

• Request method: POST

• Content-Type: application/json

• API description: Deletes a component along with its installation and visibility scope records. The API call succeeds even if it fails to clean up files in object storage.

• Request parameters

  Parameter	Type	Description	Required
  component_id	String	The ID of the component to delete.	Yes

• Request example

  {"component_id":"c1"}

• Response example

  {"success":true,"data":null,"message":null,"code":200,"trace_id":"t1"}

• Common error codes

  Error code	Description
  400	Validation failed for the ZIP file, manifest, Base64 string, externalAssets, or thumbnail.
  403	The current user lacks management permissions (upload, update, or delete).
  404	The component does not exist or does not belong to the current tenant.
  409	The component name is already in use within the tenant.
  500	The database query or save operation failed.
  502	A text component artifact in object storage is not valid UTF-8.
  503	Object storage is unavailable or a write operation failed.

CreateTicket4AiPro: Generate an AIPro embedding ticket

• POP path: /openapi/v2/pop/ticket/createTicket4AiPro

• Request method: POST

• Content-Type: application/x-www-form-urlencoded

• Description: Issues a login-free ticket of type AI_PRO_TICKET(31) for an enabled AIPro embedding configuration.

• Request parameters

  Parameter	Type	Description	Required
  aiProId	String	The ID of the AIPro embedding configuration. The configuration must exist, belong to the current organization, and have a status of 1.	Yes
  ticketNum	Int	The number of times the ticket can be used. Valid values: 1 to 99999. Default: 1.	No
  userId	String	The QuickBI userId of the user to bind to the ticket. You must provide either this parameter or a combination of accountName and accountType.	Conditionally
  accountName	String	The account name of the user to bind to the ticket. Use this with accountType when userId is not provided.	Conditionally
  accountType	Int	The account type. The value must map to the QuickBI AccountTypeEnum.	Conditionally
  expireTime	Int	The expiration time in minutes. The value must be greater than 0. Default: 240.	No
  systemUid	String	A custom system identifier. Must be less than 150 characters long.	No
  customParam	String	A custom pass-through parameter. If not empty, this value must be a valid JSON string.	No

  The userId parameter takes precedence over the accountName and accountType combination. If neither is provided, the ticket is bound to the creator of the embedding configuration by default. The calling account must be an organization administrator or a member with the COPILOT_ABI feature and COPILOT_ABI_MANAGE operational permissions. This requirement is consistent with other AIPro embedding management APIs.

• Request example

  POST /openapi/v2/pop/ticket/createTicket4AiPro
  Content-Type: application/x-www-form-urlencoded
  
  aiProId=a1&ticketNum=1&expireTime=240

• Response example

  {
    "RequestId": "req-1",
    "Success": true,
    "Result": "generated-ticket"
  }

• Login-free URL

  https://{QuickBI-access-domain}/token3rd/ai/chat?accessTicket={accessTicket}&aiProId={aiProId}

  The /token3rd/ai/chat path requires a type 31 ticket generated by this API. Do not use the create4Abi API, which issues a type ABI_ARTIFACT(28) artifact ticket. Using an artifact ticket to open the AIPro chat page will result in an AE0580800019 Access Denied error.

• Common errors

  Error code	Description
  AE0566662010	The configuration does not exist or does not belong to the current organization.
  AE0566662011	The embedding configuration is disabled.
  AE0530010025	The ticketNum value is out of the allowed range.
  AE0510000038	Invalid parameter.
  AE0591000014	Cannot resolve the bound user.

ModifyAiproEmbedConfig: Create or modify an embedding configuration

• POP path: /openapi/v2/pop/aipro/modifyAiproEmbedConfig

• Request method: POST

• Content-Type: application/json

• Description: Creates an embedding configuration if aiProId is empty or not provided. Partially updates an existing configuration if aiProId is provided. This API must be called by an organization administrator or a member with COPILOT_ABI management permissions.

• Request parameters

  Parameter	Type	Description	Required
  aiProId	String	The configuration ID. Omit to create a new configuration, or provide an ID to modify an existing one.	If modifying
  showName	String	The configuration name. Required and must be unique within the organization when creating. If left blank during modification, the name is not updated.	If creating
  agentName	String	Agent nickname. The default nickname for a new agent is "Intelligent Data Analysis Assistant".	No
  chatHistoryStatus	Int	Specifies whether to show chat history. Valid values: 1 (show), 0 (do not show). Defaults to 1 for new configurations.	No
  memoryEnabled	Int	Specifies whether to enable memory. Valid values: 1 (on), 0 (off). Defaults to 0 for new configurations.	No
  uploadEnabled	Int	Specifies whether to allow file uploads. Valid values: 1 (on), 0 (off). Defaults to 0 for new configurations.	No
  config	String	A JSON string containing the front-end appearance settings for the embedded component.	No

  A new configuration is created with its status set to status=0 (disabled). This API does not support modifying the status. After creation, you must enable the configuration on the embedding configuration management page before you can issue tickets.

• Request example

  {
    "showName": "Customer Portal",
    "agentName": "Intelligent Data Analysis Assistant",
    "chatHistoryStatus": 1,
    "memoryEnabled": 0,
    "uploadEnabled": 0,
    "config": "{\"themes\":{\"type\":\"light\"}}"
  }

• Response example

  {
    "RequestId": "req-1",
    "Success": true,
    "Result": true
  }

• Common error codes

  Error code	Description
  AE0510000005	The showName parameter is empty during creation.
  AE0566662010	The specified configuration does not exist or does not belong to the current organization.
  AE0566662017	The configuration name is already in use within the organization.

QueryAiproEmbedConfig: Query embedding configurations

• POP path: /openapi/v2/pop/aipro/queryAiproEmbedConfig

• Request method: POST

• Description: Queries AIPro embedding configurations for the current organization. The API returns results in descending order of their database ID, up to a maximum of 10,000 records. This API must be called by an organization administrator or a member with COPILOT_ABI management permissions.

• Request parameters

  Parameter	Type	Description	Required
  keyword	String	A keyword for a fuzzy search on the showName parameter.	No

• Response parameters

  Parameter	Type	Description
  aiProId	String	The embedding configuration ID. Used in the CreateTicket4AiPro request.
  showName	String	The configuration name.
  agentName	String	The agent nickname.
  status	Int	The status of the configuration. Valid values: 1 (enabled), 0 (disabled).
  chatHistoryStatus	Int	Specifies whether chat history is shown. Valid values: 1 (show), 0 (do not show).
  memoryEnabled	Int	Specifies whether memory is enabled. Valid values: 1 (on), 0 (off).
  uploadEnabled	Int	Specifies whether file uploads are allowed. Valid values: 1 (on), 0 (off).
  config	String	A JSON string containing the appearance configuration.
  createUser	String	The user ID of the creator.
  createUserName	String	The user nickname of the creator.
  modifyUser	String	The user ID of the last modifier.
  gmtCreate	Datetime	The creation time.
  gmtModified	Datetime	The modification time.

• Response example

  {
    "RequestId": "req-1",
    "Success": true,
    "Result": [
      {
        "aiProId": "a1",
        "showName": "Customer Portal",
        "agentName": "Intelligent Data Analysis Assistant",
        "status": 1,
        "chatHistoryStatus": 1,
        "memoryEnabled": 0,
        "uploadEnabled": 0,
        "config": "{\"themes\":{\"type\":\"light\"}}",
        "createUser": "u1",
        "createUserName": "John Doe",
        "modifyUser": "u1",
        "gmtCreate": "2026-09-01 10:00:00",
        "gmtModified": "2026-09-01 10:00:00"
      }
    ]
  }

Common embedding errors

Create artifact

• Path:/openapi/v2/abi/artifacts/create

• Method: POST

• Content-Type:application/json

• Description: Creates an AI dashboard artifact, saves it to the database, and returns its artifact ID and version. You can then retrieve the artifact content with the content API or generate a login-free preview URL with the embed-ticket API.

• Request parameters

  Parameter	Type	Description	Required
  artifact_type	String	The artifact type.	Yes
  title	String	The artifact title. Cannot be empty.	Yes
  content	Object	The artifact content object, which contains a dsl field (DashboardSpec).	Yes
  session_id	String	The session ID.	No
  conversation_id	String	The conversation ID.	No

• Response parameters

  Parameter	Type	Description
  artifact_id	String	The artifact ID.
  draft_id	String	The draft ID, used for subsequent edits.
  version	Int	The current version.

• Example request

  {
    "artifact_type": "ai_dashboard",
    "title": "Sales Trend Dashboard",
    "content": {
  
      "dsl": {"type": "ai_dashboard", "title": "Sales Trend Dashboard", "charts": [ ]}
  
    }
  }

• Example response

  {
    "success": true,
    "data": {
      "artifact_id": "3f8e9b2a-...",
      "draft_id": "d7c1a5b3-...",
      "version": 1
    },
    "code": 200,
    "trace_id": "t1"
  }

Read artifact content

• Path:/openapi/v2/abi/artifacts/content

• Method: GET

• Description: Retrieves the content of an artifact by its ID and version. Because the gateway requires an exact URI match for signature verification, pass the artifact_id as a query parameter instead of using a RESTful path template.

• Request parameters

  Parameter	Location	Type	Description	Required
  artifact_id	Query	String	The artifact ID.	Yes
  version	Query	Int	The version to retrieve. If this parameter is omitted, the latest version is returned.	No

• Response parameters

  Parameter	Type	Description
  artifact_id	String	The artifact ID.
  version	Int	The current version.
  current_version	Int	The latest version. If version is less than current_version, the retrieved version is not the latest.
  content	Object	The artifact content.
  created_at	String	The time at which the artifact was created.
  updated_at	String	The time at which the artifact was last updated.

• Example

  GET /openapi/v2/abi/artifacts/content?artifact_id=a1&version=1

Generate a login-free ticket

• Path:/openapi/v2/abi/artifacts/embed-ticket

• Method: POST

• Content-Type:application/json

• Description: Exchanges an artifact ID for a login-free ticket and an iframe preview URL. By default, the ticket is valid for the user associated with the AK making the call. To specify a different user, use the ticket_user_id parameter; this user must have permission to access the artifact.

• Request parameters

  Parameter	Type	Description	Required
  artifact_id	String	The artifact ID.	Yes
  ticket_num	Int	The number of times the ticket can be used. Default: 1.	No
  expire_minutes	Int	The validity period of the ticket in minutes. Default: 240.	No
  ticket_user_id	String	Specifies the user ID to bind to the ticket. This user must have permission to access the artifact.	No
  watermark_param	String	A JSON string that contains watermark parameters.	No
  global_param	String	A JSON string that contains global pass-through parameters.	No

• Response parameters

  Parameter	Type	Description
  embed_url	String	The embeddable preview URL.
  ticket	String	The login-free ticket.
  expire_at	String	The time at which the ticket expires.

• Example request

  {
    "artifact_id": "a1",
    "ticket_num": 99999,
    "expire_minutes": 525600
  }

• Example response

  {
    "success": true,
    "data": {
      "embed_url": "https://bi.aliyun.com/token3rd/ai-dashboard/view/pc.htm?accessTicket=xxx&artifactId=a1",
      "ticket": "generated-ticket",
      "expire_at": "2027-09-10T12:00:00"
    },
    "code": 200,
    "trace_id": "t1"
  }

• Common error codes

  Code	Description
  400	Parameter validation failed.
  403	The current user (or the user specified by ticket_user_id) does not have permission to access the artifact.
  404	The artifact was not found.
  502	The request to the Quick BI service to generate a ticket failed.

  The embedded preview URL can be used to display the AI dashboard in an iframe or as a clickable link. This can be used in conjunction with the AIPro embedding described in the III. Embedded integration section.