Integrate data questions into business systems with REST API

Assume the AskTable URL is https://asktable.example.com:

The current instance's Redoc is authoritative for endpoints and fields; versions may add or remove them.

The project API key integration shown here uses this header:

Authorization: Bearer YOUR_API_KEY

The existing integration instructions distinguish asker and admin keys. This distinction does not establish permissions for every system administration or internal endpoint; check the specific schema declaration and current instance.

POST /v1/integration/query is the stable question entry point and returns HTTP 201 on success. Provide at least one datasource_ids entry; question is limited to 4096 characters:

curl -X POST 'https://asktable.example.com/v1/integration/query' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "datasource_ids": ["ds_xxxxxxxx"],
    "question": "Your data question"
  }'

To restrict data scope by role, include role_id and role_variables:

{
  "datasource_ids": ["ds_xxxxxxxx"],
  "role_id": "role_xxxxxxxx",
  "role_variables": { "dept_id": "D001" },
  "question": "Your data question"
}

{
  "conversation_id": "00000000-0000-0000-0000-000000000000",
  "answer": "Natural-language answer; null on failure",
  "status": "success"
}

status has only two values: success and failed. conversation_id traces this call; use it to open the same conversation in “All conversations” for further inspection.

The same /v1 root also has resource endpoints for data sources, data Agents, skills, roles, policies, conversations, dashboards, canvases, model groups, and more. The Key type and project permissions determine which can be called; refer to Redoc for exact paths.

1. Use a separate project API-Key for each application or environment rather than sharing an administrator Key.
2. Call only from the server; do not put the Key in browsers, mobile clients, or iframe pages.
3. Set request timeouts and retry limits, distinguishing authentication failures, permission denials, parameter errors, unready data sources, and service timeouts.
4. Record caller, project, time, duration, HTTP status, and conversation_id in business logs, not sensitive data from complete questions.
5. Decide role_id and role_variables on the server. Do not accept arbitrary values passed directly by callers, which could expand data scope.