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/v1Key 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
| Endpoint | Method | Description |
|---|---|---|
/v1/me | GET | Validate API key and get current user |
/v1/chat | POST | Chat with a database using natural language |
/v1/chat/{chatId} | GET | Retrieve chat messages and artifacts |
/v1/generate-query | POST | Generate a SQL query from a natural language prompt |
/v1/task/{taskId} | GET | Check the status of an async task |
/v1/databases | GET | List all accessible databases |
/v1/databases/{databaseId} | GET | Get database details |
/v1/databases/{databaseId}/tables | GET | List database tables |
/v1/databases/{databaseId}/tables/{tableId} | GET | Get table details |
/v1/artifact | GET | List artifacts (paginated) |
/v1/artifact/{artifactId} | GET | Get artifact details |
/v1/artifact/{artifactId}/data | GET | Execute a SQL artifact and get paginated results |
/openapi.json | GET | Get 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
- Quickstart — Make your first API call in minutes
- Authentication — Create and manage API keys
- Async Tasks — Understand the async task pattern