API Reference

The Workliq AI REST API. Dashboard endpoints use a Bearer token from /api/auth/login; the programmatic /api/external/v1 endpoints use an X-API-Key (Pro+).

Base URL https://api.workliq.me · full OpenAPI spec at /docs

# Login
POST /api/auth/login
{"email":"user@example.com","password":"..."}
# Returns: {"access_token":"...","plan":"free"}

# Register
POST /api/auth/register
{"name":"...","email":"...","password":"min 8 chars"}

# Me
GET /api/auth/me
Authorization: Bearer <token>

# Upload CSV / Excel / Parquet / JSON
POST /api/analyst/datasets/upload
Content-Type: multipart/form-data
file=@data.csv

# List datasets
GET /api/analyst/datasets

# Dataset health score
GET /api/analyst/datasets/{id}/health

# Insights
GET /api/analyst/datasets/{id}/insights

# Anomalies
GET /api/analyst/datasets/{id}/anomalies

# Forecast
GET /api/analyst/datasets/{id}/forecast

POST /api/analyst/ask
Authorization: Bearer <token>
{"question":"Show revenue by product","dataset_id":"abc123"}

# Returns: sql, python_equivalent, data, chart_type_hint, from_cache

# Segmentation
POST /api/analyst/ml
{"dataset_id":"...","analysis_type":"segment","n_clusters":3}

# Regression
POST /api/analyst/ml
{"dataset_id":"...","analysis_type":"regression","target_column":"revenue","feature_columns":["cost","qty"]}

POST /api/analyst/stats
{"dataset_id":"...","test_type":"ttest","column":"revenue","group_column":"product","group_a":"Laptop","group_b":"Phone"}
# test_type: ttest | normality | anova | correlation

# Create a key (dashboard: Profile → API keys, or:)
POST /api/analyst/profile/api-keys
Authorization: Bearer <token>
{"name":"CI pipeline"}
# Returns the key ONCE: {"key":"wl_live_..."} — store it securely.

# All /api/external/v1/* endpoints authenticate with the key header:
GET  /api/external/v1/health
GET  /api/external/v1/datasets
GET  /api/external/v1/datasets/{id}
POST /api/external/v1/datasets            # multipart file upload
POST /api/external/v1/ask
X-API-Key: wl_live_...
{"dataset_id":"...","question":"total revenue by month"}
# Per-key rate limit: 60 req/min default (429 when exceeded).

# Subscribe to analysis events
POST /api/external/v1/webhooks
X-API-Key: wl_live_...
{"url":"https://your-app.com/hooks/workliq",
 "events":["dataset.analyzed","anomaly.detected"],
 "secret_hmac":"optional-signing-secret"}

# Events fired by the analysis pipeline:
#  dataset.analyzed  — analysis complete: {dataset_id, health_grade, n_insights, top_insight}
#  anomaly.detected  — high-severity anomalies: {dataset_id, count, anomalies[]}
# Delivery: POST {"event","payload","ts"} with header X-Workliq-Event, plus
# X-Workliq-Signature: sha256=<HMAC-SHA256 of body> when secret_hmac is set.
# 5xx failures retry with backoff; 4xx do not.

GET    /api/external/v1/webhooks
DELETE /api/external/v1/webhooks/{id}

pip install workliq

# --- Python ---
from workliq import Workliq
wl = Workliq(api_key="wl_live_...")     # or set WORKLIQ_API_KEY
wl.health()                             # verify the key
ds = wl.upload("sales.csv")             # POST /v1/datasets
wl.wait_for_analysis(ds.id)             # polls until analysis is done
r  = wl.ask(ds.id, "revenue by month") # POST /v1/ask
print(r.sql, r.rows)                    # SQL + result rows
wl.register_webhook("https://you/hook", ["dataset.analyzed"])

# --- CLI (installed with the package) ---
export WORKLIQ_API_KEY=wl_live_...
workliq health
workliq upload sales.csv
workliq ask <dataset_id> "what's the revenue trend?" --show-sql
workliq webhooks add https://you/hook dataset.analyzed anomaly.detected

# Source: github.com/abhay0963/Workliq-Ai/tree/main/sdk/python

GET /health
# {"status":"ok","product":"Workliq AI","version":"1.0.0"}