DataTalk Docs

Overview

Overview of the DataTalk Public API

The DataTalk Public API lets you programmatically query your connected SQL databases using natural language. You can generate SQL queries, retrieve chat history, retrieve database metadata, and execute queries — all through a simple REST interface.

Base URL

All API endpoints are available under:

https://api.datatalk.bi/v1

Key Features

  • Natural Language to SQL — Send a prompt and get back a SQL query tailored to your database schema
  • Chat History — Retrieve past conversations and their artifacts
  • Database Introspection — List databases, explore table structures, and read descriptions
  • Async Task System — Long-running operations return a task ID for polling or webhook delivery
  • Webhook Notifications — Get notified via callback URL when tasks complete

Quick Overview

EndpointMethodDescription
/v1/meGETValidate API key and get current user
/v1/chatPOSTChat with a database using natural language
/v1/chat/{chatId}GETRetrieve chat messages and artifacts
/v1/generate-queryPOSTGenerate a SQL query from a natural language prompt
/v1/task/{taskId}GETCheck the status of an async task
/v1/databasesGETList all accessible databases
/v1/databases/{databaseId}GETGet database details
/v1/databases/{databaseId}/tablesGETList database tables
/v1/databases/{databaseId}/tables/{tableId}GETGet table details
/v1/artifactGETList artifacts (paginated)
/v1/artifact/{artifactId}GETGet artifact details
/v1/artifact/{artifactId}/dataGETExecute a SQL artifact and get paginated results
/openapi.jsonGETGet the OpenAPI specification

Authentication

All endpoints require a Bearer token using an API key with the dt_ prefix. See Authentication for details.

Data Access

POST /chat with "dataAccess": true and POST /generate-query let the AI read query results while it works. This requires data access to be enabled in the tenant settings and, for each database, in that database's Access Control settings; a database can only restrict the tenant setting, not widen it. Running an artifact's query with GET /artifact/{artifactId}/data always works, whatever this setting.

Language and Time Zone

The AI answers in the language of your prompt. Chat titles are written in your organization's system language (set in the tenant settings); there is no request parameter to change it. For relative dates such as "today" or "last month", POST /chat and POST /generate-query accept an optional timezone (an IANA name like Europe/Rome); without it the AI uses UTC.

Rate Limits

60 requests per minute per API key (10 for POST /chat). See Error Handling.

Next Steps

On this page