DataVision API Reference
Embed natural-language data analysis directly into your applications. Upload datasets, ask questions in plain English, and receive AI-powered insights and interactive Plotly charts.
Overview
The DataVision API is a REST endpoint that accepts multipart/form-data requests. You can upload a CSV or Excel file along with a natural-language question, and the API returns an AI-generated analysis with text insights and an optional Plotly chart configuration.
How it works
Upload
Send your dataset + question
Analyze
AI parses, analyzes, and visualizes
Receive
Get insights + chart config in JSON
Authentication
Authenticate every request by including your API key as a Bearer token in the Authorization header.
Generating your API key
- 1Log in to your DataVision AI account.
- 2Navigate to Account Settings.
- 3Scroll to API Keys and click Generate New Key.
- 4Give it a recognizable name (e.g., "Python Scripting" or "Prod Backend").
Important: Copy your key immediately after generating it. For security, the full key cannot be viewed again.
Endpoint
All API interactions go through a single endpoint. The endpoint accepts multipart/form-data only.
Request Parameters
All parameters are sent as multipart/form-data fields. There are two request flows.
Initial Analysis — Upload a File
| Parameter | Type | Status | Description |
|---|---|---|---|
message | string | Required | Your question in plain English. |
file | file | Required | Dataset to analyze (CSV, XLS, or XLSX). |
Follow-up Questions — Cached Context
| Parameter | Type | Status | Description |
|---|---|---|---|
message | string | Required | Your follow-up question. |
cached_schema | string | Required | Schema string from your previous response. |
cached_df_json | string | Required | Dataframe JSON from your previous response. |
Tip: Using cached context avoids re-uploading files and reduces credit cost.
Code Examples
Copy-paste examples to start integrating immediately. Pick your language below.
import requests
url = "https://datavision-ai.vercel.app/api/chat"
api_key = "dv_live_YOUR_API_KEY_HERE"
headers = {
"Authorization": f"Bearer {api_key}"
}
# ── Initial analysis (upload a file) ──
data = {
"message": "Show me total sales by region as a bar chart"
}
files = {
"file": ("sales_data.csv", open("sales_data.csv", "rb"), "text/csv")
}
response = requests.post(url, headers=headers, data=data, files=files)
if response.status_code == 200:
result = response.json()
print("AI Analysis:", result.get("text_overview"))
print("Credits left:", result.get("creditsRemaining"))
# Save context for follow-ups
cached_schema = result.get("cached_schema")
cached_df_json = result.get("cached_df_json")
else:
print(f"Error {response.status_code}: {response.text}")Response Codes
The API uses standard HTTP response codes. Here are the ones you should handle:
Success Response Shape
{
"text_overview": "The dataset shows total sales of $1.2M across 4 regions...",
"plotly_config": { ... },
"cached_schema": "col1:string, col2:number, ...",
"cached_df_json": "[{...}, {...}]",
"creditsRemaining": 42
}| Field | Type | Description |
|---|---|---|
text_overview | string | AI-generated text analysis of the data. |
plotly_config | object | null | Plotly chart JSON config, if a chart was generated. |
cached_schema | string | Schema of the dataset — pass this in follow-up requests. |
cached_df_json | string | Serialized dataframe — pass this in follow-up requests. |
creditsRemaining | number | Your remaining credit balance after this request. |
Credits & Rate Limits
Each API request consumes credits from your account balance. New accounts start with 100 free credits.
Credits per request when uploading a new file for analysis.
Credits per follow-up using cached context from a prior request.
Rate Limit Errors
If you consistently hit rate limits, consider spacing out requests or upgrading your plan for higher throughput.