# 11 AI Data
Note: These endpoints let an AI agent (or your own program) query your own CJ business data with SQL through the CJ AI data gateway, and read the knowledge base and field dictionary it needs to write that SQL.
- Data scope is enforced by CJ. The gateway always limits the query to the owner of the
CJ-Access-Tokenand adds the fixed conditions of the selected menu (for example, Sample Orders only returns sample orders). You cannot query other customers' data, and you do not need to (and cannot) pass any customer id.- Points: 1.1 Execute SQL costs 10 points per call. Points are deducted before the query runs, the same as other APIs, and are automatically refunded when the query does not succeed (rejected, execution failed, gateway unavailable, or invalid parameters) (top-level
resultis false, ordata.successis false). 1.2 Explain SQL, 2.1 Get Knowledge Base and 2.2 Get Field Dictionary are free. See Points Resource Rules.- Recommended flow: call 2.2 to get the fields you can use, write the SQL, check it for free with 1.2, then run it with 1.1.
Available menus (menuCode)
| menuCode | Page on My CJ |
|---|---|
| mycj_store_orders | Store Orders |
| mycj_sample_orders | Sample Orders |
| mycj_wholesale_orders | Wholesale Orders |
| mycj_inventory_orders | Inventory Orders |
| mycj_undelivered_orders | Undelivered Orders |
| mycj_disputes | Disputes |
| mycj_customization | Customization |
| mycj_cart | Cart |
| mycj_export_list | Export List |
| mycj_my_inventory | My Inventory |
# 1 SQL
# 1.1 Execute SQL(POST)
Runs one SELECT statement against your data and returns the rows. 10 points per call.
# URL
https://developers.cjdropshipping.com/api2.0/v1/aiData/nlSql
# CURL
curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/aiData/nlSql' \
--header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
"sql": "SELECT order_number, status, amount, create_date FROM dd_cj_order.sync_direct_order ORDER BY create_date DESC LIMIT 2",
"menuCode": "mycj_sample_orders",
"remark": "latest sample orders"
}'
| Parameter | Definition | Type | Required | Length | Note |
|---|---|---|---|---|---|
| sql | SQL statement | string | Y | One SELECT statement only. Write tables as schema.table, for example dd_cj_order.sync_direct_order. Only the tables in queryableTables and the fields in fields of 2.2 Get Field Dictionary can be used | |
| menuCode | Menu code | string | N | 64 | See the menu table above. If omitted, the gateway picks the menu from the tables in the SQL and returns it in data.resolvedMenuCode |
| remark | Purpose of the query | string | N | 200 | One sentence describing what you are querying, for example latest sample orders. Do not put concrete values such as phone numbers here. Longer text is truncated |
The request body does not accept any customer identity field or execution mode. Whether the SQL is executed or only explained is decided by the URL: this endpoint executes, 1.2 Explain SQL only explains.
# Return
success
{
"code": 200,
"result": true,
"message": "Success",
"data": {
"success": true,
"traceId": "2609281200000000001",
"errorCode": null,
"message": null,
"finalSql": "SELECT order_number, status, amount, create_date FROM (SELECT order_number, status, create_date, amount FROM dd_cj_order.sync_direct_order WHERE ((merchantn_number IN ('1965387421098765432'))) AND (create_date >= to_timestamp(1735660800)) AND (order_type IN (0, 1)) AND (impstorage_flag IS DISTINCT FROM 'ISIMP') AND (status IS DISTINCT FROM '9') AND (other_info_json->>'isDelete' IS DISTINCT FROM '1')) AS sync_direct_order ORDER BY create_date DESC LIMIT 2",
"rows": [
{
"order_number": "SD2609281200001",
"status": 3,
"amount": "25.80",
"create_date": "2026-09-28 12:00:01"
},
{
"order_number": "SD2609271800002",
"status": 6,
"amount": "12.40",
"create_date": "2026-09-27 18:00:02"
}
],
"wrappedRelations": ["dd_cj_order.sync_direct_order"],
"maskedColumns": [],
"unresolvedColumns": [],
"maskUnverifiedColumns": [],
"injectedPredicates": [
"merchantn_number IN (<1 values>)",
"create_date >= to_timestamp(1735660800)"
],
"appliedMaxRows": 500,
"limitSource": "DB_DEFAULT",
"appliedRowScope": "merchantn_number IN (<1 values>)",
"timeFloorApplied": 1735660800000,
"precheck": null,
"scopeCheck": null,
"outOfScopeRelations": [],
"scopeWarning": null,
"resolvedMenuCode": null,
"menuCandidates": null,
"menuResolveTrace": null,
"denySubjects": []
},
"requestId": "7dbe69b9-dd82-4ee3-907c-a6fca833e3ce"
}
code: 200means the open platform delivered the gateway's answer. Checkdata.successto know whether the query itself succeeded. Values in the example are illustrative.
| Field | Definition | Type | Note |
|---|---|---|---|
| data.success | Whether the query succeeded | boolean | false when the gateway rejected or could not run the SQL; see data.errorCode |
| data.traceId | Gateway trace id | string | Provide it when contacting CJ support |
| data.errorCode | Gateway error code | string | Null on success. See the gateway error codes below |
| data.message | Gateway error message | string | Null on success. English text explaining how to fix the SQL. Use errorCode in your program |
| data.denySubjects | Names involved in the rejection | list<string> | Fields, tables or functions that caused the rejection, for example ["salesman"] for COLUMN_NOT_REGISTERED. Empty on success |
| data.finalSql | The SQL actually executed | string | Your SQL after CJ added your data scope, the menu's fixed conditions, the time lower bound and the row limit |
| data.rows | Result rows | list<object> | Keys are the column names in your SELECT. Null for 1.2 Explain SQL |
| data.injectedPredicates | Conditions added by CJ | list<string> | For reference only |
| data.appliedRowScope | Data scope applied | string | Your own data only |
| data.appliedMaxRows | Row limit applied | int | The result never exceeds this number of rows, even if your LIMIT is larger |
| data.limitSource | Where the row limit comes from | string | |
| data.timeFloorApplied | Time lower bound applied | long | Unix time in milliseconds; records earlier than this are not returned. Null when none is applied |
| data.maskedColumns | Masked columns | list<string> | Columns whose values are masked in rows |
| data.resolvedMenuCode | Menu chosen by the gateway | string | Set only when menuCode was not passed |
| other fields | Diagnostic information | wrappedRelations, unresolvedColumns, maskUnverifiedColumns, precheck, scopeCheck, outOfScopeRelations, scopeWarning, menuCandidates, menuResolveTrace. For troubleshooting only; do not depend on them |
gateway rejected the SQL
{
"code": 200,
"result": true,
"message": "Success",
"data": {
"success": false,
"traceId": "2609281200000000002",
"errorCode": "COLUMN_NOT_REGISTERED",
"message": "The SQL uses fields that are not available: salesman. Get the available fields from the field dictionary of this menu and rewrite the SQL with fields[].name.",
"finalSql": null,
"rows": null,
"denySubjects": ["salesman"]
},
"requestId": "323fda9d-3c94-41dc-a944-5cc1b8baf5b1"
}
Common gateway error codes (data.errorCode)
| errorCode | Meaning | What to do |
|---|---|---|
| COLUMN_NOT_REGISTERED | The SQL uses a field that is not available | Get the fields with 2.2 Get Field Dictionary and rewrite the SQL |
| OBJECT_NOT_GRANTED | The SQL uses a table that this menu cannot query | Use only the tables in queryableTables |
| SQL_NO_FROM | The SQL has no table | Write at least one table in FROM |
| MENU_NOT_GRANTED | Your account has no permission for this menu | Use another menu, or check the menu code |
| UC_CONFIG_INVALID | The menu's query configuration is abnormal | Contact CJ support with traceId |
| NL_SQL_EXECUTION_FAILED | The SQL failed when executed | Check the SQL syntax and column types |
| IDENTITY_NOT_LOGIN | The token could not be resolved to a customer | Get a new access token |
Points are deducted for 1.1 even when
data.successisfalse. Use 1.2 Explain SQL (free) to check new SQL first.
error
{
"code": 1611001,
"result": false,
"message": "AI data query failed, please try again later",
"data": null,
"requestId": "323fda9d-3c94-41dc-a944-5cc1b8baf5b1"
}
| Field | Definition | Type | Length | Note |
|---|---|---|---|---|
| code | error code | int | 20 | Reference error code. 1600002 missing access token; 1600300 invalid parameter (for example empty sql); 1611001 the AI data service is temporarily unavailable, please retry later; 16900500 insufficient points |
| result | Whether or not the return is normal | boolean | 1 | |
| message | return message | string | 200 | |
| data | return data | object | interface data return | |
| requestId | requestId | string | 48 | Flag request for logging errors |
# 1.2 Explain SQL(POST)
Checks one SELECT statement without executing it and returns finalSql, the SQL that 1.1 would execute. Free. Use it to check new SQL before calling 1.1.
# URL
https://developers.cjdropshipping.com/api2.0/v1/aiData/nlSql/explain
# CURL
curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/aiData/nlSql/explain' \
--header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
"sql": "SELECT order_number, status, amount, create_date FROM dd_cj_order.sync_direct_order ORDER BY create_date DESC LIMIT 2",
"menuCode": "mycj_sample_orders",
"remark": "latest sample orders"
}'
The request parameters are the same as 1.1 Execute SQL.
# Return
The same as 1.1, except that data.rows is always null. When the SQL would be rejected, data.success is false with the same data.errorCode.
# 2 Knowledge
# 2.1 Get Knowledge Base(GET)
Returns the knowledge base of a menu: its tables, the meaning of each field, and the fixed conditions CJ adds. It is written for AI agents to build SQL. Free.
# URL
https://developers.cjdropshipping.com/api2.0/v1/aiData/kb/artifact?menuCode=mycj_sample_orders
# CURL
curl --location --request GET 'https://developers.cjdropshipping.com/api2.0/v1/aiData/kb/artifact?menuCode=mycj_sample_orders' \
--header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
| Parameter | Definition | Type | Required | Length | Note |
|---|---|---|---|---|---|
| menuCode | Menu code | string | Y | 64 | See the menu table above. Letters, digits, _ and - only |
# Return
success (shortened)
{
"code": 200,
"result": true,
"message": "Success",
"data": {
"menuCode": "mycj_sample_orders",
"kbVersion": "mycj_sample_orders@672d241585ca",
"tables": ["sync_direct_order", "sync_direct_product", "sync_direct_product_group", "sync_order_client_info"],
"columns": [
{
"table": "sync_direct_order",
"exposedName": "amount",
"physicalType": "numeric",
"virtual": false,
"note": "总支付金额"
}
],
"fixedPredicates": [
{
"exposedNames": ["order_type"],
"renderedExample": "order_type IN (0, 1)",
"aiMustNotWrite": false
}
]
},
"requestId": "7dbe69b9-dd82-4ee3-907c-a6fca833e3ce"
}
| Field | Definition | Type | Note |
|---|---|---|---|
| data.menuCode | Menu code | string | |
| data.kbVersion | Knowledge base version | string | Changes when the knowledge base changes |
| data.tables | Tables of the menu | list<string> | Schema dd_cj_order for order menus |
| data.columns | Fields you can select | list<object> | table: the table it belongs to; exposedName: the name to use in SQL; physicalType: the column type; virtual: true means CJ computes the value, write exposedName directly; note: the meaning of the field (in Chinese) |
| data.fixedPredicates | Fixed conditions added by CJ | list<object> | renderedExample shows the condition. You do not need to write them yourself |
Note: The knowledge base is generated when the gateway is released and may lag behind the field permissions. The fields you can use right now are those returned by 2.2 Get Field Dictionary. The
noteof each field is in Chinese.
When the menu code is invalid or you have no permission for the menu, data.success is false and data.errorCode tells the reason (for example MENU_CODE_MALFORMED, MENU_NOT_GRANTED, KB_ARTIFACT_NOT_FOUND). Errors of the open platform itself are the same as 1.1.
# 2.2 Get Field Dictionary(GET)
Returns the tables and fields you can use right now in the SQL of a menu, based on your current permissions. Free.
# URL
https://developers.cjdropshipping.com/api2.0/v1/aiData/kb/fields?menuCode=mycj_sample_orders
# CURL
curl --location --request GET 'https://developers.cjdropshipping.com/api2.0/v1/aiData/kb/fields?menuCode=mycj_sample_orders' \
--header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
| Parameter | Definition | Type | Required | Length | Note |
|---|---|---|---|---|---|
| menuCode | Menu code | string | Y | 64 | See the menu table above. Letters, digits, _ and - only |
# Return
success (shortened)
{
"code": 200,
"result": true,
"message": "Success",
"data": {
"menuCode": "mycj_sample_orders",
"schema": "dd_cj_order",
"queryableTables": ["sync_direct_order", "sync_direct_product", "sync_direct_product_group", "sync_order_client_info"],
"fields": [
{"name": "order_number", "table": "sync_direct_order", "virtual": false},
{"name": "status", "table": "sync_direct_order", "virtual": false},
{"name": "country", "table": "sync_order_client_info", "virtual": false}
],
"notes": [
"Only the fields available to you are listed: granted to you, selectable, and in a table listed in queryableTables. A field that is not listed is not available to you; use another field instead of retrying the same name."
]
},
"requestId": "7dbe69b9-dd82-4ee3-907c-a6fca833e3ce"
}
| Field | Definition | Type | Note |
|---|---|---|---|
| data.menuCode | Menu code | string | |
| data.schema | Schema of the tables | string | Write tables as schema.table in SQL, for example dd_cj_order.sync_direct_order |
| data.queryableTables | Tables you can query | list<string> | |
| data.fields | Fields you can use | list<object> | name: field name to use in SQL; table: the table it belongs to; virtual: true means CJ computes the value, write name directly. All listed fields can be selected, filtered and sorted |
| data.notes | Usage notes | list<string> |
Fields that are not listed are not available to you; rewrite the SQL instead of retrying the same name. Errors are the same as 2.1.
← 10 Ticket 12 Listing →