# 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-Token and 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 result is false, or data.success is 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: 200 means the open platform delivered the gateway's answer. Check data.success to 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.success is false. 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 note of 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.