Quickstart

This guide walks you through the complete flow: listing your databases, generating a SQL query from a natural language prompt, polling the task, and retrieving the results.

Prerequisites

A DataTalk account with at least one connected database
An API key (see Authentication)

Step 1: List Your Databases

First, find out which databases you have access to.

curl https://api.datatalk.bi/v1/databases \
  -H "Authorization: Bearer dt_your_api_key"

Response:

{
  "data": [
    {
      "id": "abc-123",
      "name": "Sales DB",
      "type": "postgresql",
      "createdAt": "2025-01-15T10:00:00.000Z",
      "tableCount": 24
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Step 2: Generate a Query

Send a natural language prompt along with the database ID.

curl -X POST https://api.datatalk.bi/v1/generate-query \
  -H "Authorization: Bearer dt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Show me the top 10 customers by revenue",
    "dbId": "abc-123"
  }'

Response (202 Accepted):

{
  "taskId": "task-456",
  "status": "PENDING"
}

Step 3: Poll the Task

The query generation is asynchronous. Poll the task endpoint until it completes.

curl https://api.datatalk.bi/v1/task/task-456 \
  -H "Authorization: Bearer dt_your_api_key"

While processing, you'll get a Retry-After: 2 header. Once complete:

{
  "taskId": "task-456",
  "type": "GENERATE_QUERY",
  "status": "COMPLETED",
  "result": {
    "artifactId": "art-789",
    "sql": "SELECT c.name, SUM(o.total) as revenue FROM customers c JOIN orders o ON c.id = o.customer_id GROUP BY c.name ORDER BY revenue DESC LIMIT 10",
    "title": "Top 10 Customers by Revenue"
  },
  "usage": {
    "inputTokens": 1250,
    "outputTokens": 85,
    "totalTokens": 1335,
    "costUsd": 0.0042
  },
  "createdAt": "2025-01-15T10:05:00.000Z",
  "completedAt": "2025-01-15T10:05:03.000Z"
}

Step 4: Get the Query Data

Use the artifactId from the result to execute the SQL and get paginated data.

curl "https://api.datatalk.bi/v1/artifact/art-789/data?page=1&pageSize=20" \
  -H "Authorization: Bearer dt_your_api_key"

Response (200 OK):

{
  "artifactId": "art-789",
  "title": "Top 10 Customers by Revenue",
  "data": [
    { "name": "Acme Corp", "revenue": 150000 },
    { "name": "Globex Inc", "revenue": 120000 }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalCount": 10,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

JavaScript Example

const API_BASE = "https://api.datatalk.bi/v1";
const API_KEY = "dt_your_api_key";

const headers = {
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

// Generate query
const genRes = await fetch(`${API_BASE}/generate-query`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    prompt: "Show me the top 10 customers by revenue",
    dbId: "abc-123",
  }),
});
const { taskId } = await genRes.json();

// Poll until complete
async function pollTask(taskId) {
  while (true) {
    const res = await fetch(`${API_BASE}/task/${taskId}`, { headers });
    const task = await res.json();

    if (task.status === "COMPLETED" || task.status === "FAILED") return task;

    const retryAfter = res.headers.get("Retry-After") ?? "2";
    await new Promise((r) => setTimeout(r, parseInt(retryAfter) * 1000));
  }
}

const result = await pollTask(taskId);
const { artifactId } = result.result;

// Fetch the data directly
const dataRes = await fetch(`${API_BASE}/artifact/${artifactId}/data?page=1&pageSize=100`, { headers });
const data = await dataRes.json();
console.log(data);

Using Webhooks (Alternative to Polling)

Instead of polling, you can configure webhook endpoints in Settings > API > Webhooks to receive push notifications when tasks complete. See Webhooks for details.