# Integrate data questions into business systems with REST API

Use REST API to integrate data questions and answers into business systems.

使用指南 · 模块: integrations · 应用开发者 · 部署形态：资料未说明 · 已确认产品版本：资料未说明 · 来源：现有文档

The query endpoint shown here is under `/v1` on the deployment instance, suitable for application teams integrating data questions into business systems, portals, service workflows, or automation platforms. A single endpoint is enough to get started: `POST /v1/integration/query`. Send data sources and a question, and receive a natural-language answer.

## Before you begin

- An AskTable deployment instance and its external URL.
- A project API-Key. Use `asker` for questions only; use `admin` for management endpoints (creating data sources, changing permissions, deleting Agents).
- Creation location: left main navigation → “Settings” → “API-Key” → “Create API-KEY.” The full value is shown only once, on creation.
- At least one ready data source and its ID (such as `ds_xxxxxxxx`).
- Documentation entry: bottom avatar → “Documentation” → “REST API” opens the instance's Redoc directly.

## Steps

**Confirm the API root and documentation URLs**

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

| Purpose                           | URL                                         |
| --------------------------------- | ------------------------------------------- |
| API root                          | `https://asktable.example.com/v1`           |
| Interactive documentation (Redoc) | `https://asktable.example.com/v1/redoc`     |
| Swagger UI                        | `https://asktable.example.com/v1/docs`      |
| OpenAPI specification             | `https://asktable.example.com/openapi.json` |

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

**Include the authentication header**

The project API key integration shown here uses this header:

```text
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.

**Ask a question**

`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:

```bash
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`:

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

**Read the response body**

```json
{
  "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.

**Expand to other resource endpoints as needed**

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.

**Prepare for production**

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.

## Key constraints

| Item                                        | Value or default                                 | Where to change it                           |
| ------------------------------------------- | ------------------------------------------------ | -------------------------------------------- |
| API root path                               | `/v1`                                            | No UI switch                                 |
| Documentation URLs                          | `<your-site>/v1/redoc`, `<your-site>/v1/docs`    | Bottom avatar → “Documentation” → “REST API” |
| Authentication header                       | `Authorization: Bearer <API-Key>`                | Caller                                       |
| Permission for `POST /v1/integration/query` | `priv_asker` (an `asker` Key is sufficient)      | “Settings” → “API-Key”                       |
| `datasource_ids`                            | Required, at least one                           | Request body                                 |
| `question`                                  | Required, up to 4096 characters                  | Request body                                 |
| `role_id`                                   | Optional; omission means no permission filtering | Request body                                 |
| Success status code                         | 201                                              | No UI switch                                 |
| `status` values                             | `success` or `failed`                            | Response body                                |
| Project API-Key count                       | Up to 10 per project                             | “Settings” → “API-Key”                       |

## Troubleshooting

| Symptom                                          | Identifying condition                                                            | Resolution                                                                                                                    |
| ------------------------------------------------ | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| HTTP 401 with `code` `AUTH_ERROR`                | Key is missing, incorrect, or deleted                                            | Create a new project API-Key; confirm header format `Authorization: Bearer YOUR_API_KEY`                                      |
| HTTP 403 with `code` `PERMISSION_DENIED`         | An `asker` Key called a management endpoint, or the project role is insufficient | Use an `admin` Key for management calls; confirm it belongs to the target project                                             |
| HTTP 404 with `code` `DATASOURCE_NOT_FOUND`      | An ID in `datasource_ids` does not exist in the project                          | Copy the correct ID from “Data sources”                                                                                       |
| HTTP 400 with `code` `DATASOURCE_META_NOT_READY` | Metadata is not ready; `message` includes its current status                     | Wait for sync to finish, or trigger sync manually on “Data sources”                                                           |
| HTTP 422 with `code` `VALIDATION_ERROR`          | `message` lists each field and reason                                            | Correct the fields: `datasource_ids` cannot be empty and `question` must not exceed 4096 characters                           |
| `status` is `failed` and `answer` is `null`      | HTTP status is normal, but analysis did not complete                             | Open the conversation in “All conversations” using `conversation_id` to see the cause; data source or model issues are common |
| Cannot open the returned `conversation_id`       | The ID belongs to another project or the conversation was deleted                | Confirm the Key and project match; `conversation_id` cannot be used across projects                                           |
| API URL returns 404                              | Request path is missing or has an extra `/v1` prefix                             | The correct single-question path is `POST /v1/integration/query`                                                              |

## Next steps

- Let AI clients discover and call these capabilities themselves: [MCP](https://docs.asktable.com/en/integrations/mcp)
- Operate directly in terminals or scripts: [Command-line tool](https://docs.asktable.com/en/integrations/cli)
- Configure a Coze plugin for bots: [Connect Coze](https://docs.asktable.com/en/integrations/coze)