Get started

Quickstart

Get a key, add a file, and ask your first question. About five minutes, and the free plan needs no card.

Get an API key

Sign up with your email and a project name. Your key is shown once, straight after signup. It is bound to a workspace called General. Keep it in an environment variable, never in code a browser can load.

export FACTQL_API_KEY="fl_live_..."

Look up your IDs

GET /whoami tells you which tenant and workspace the key points at. The file endpoints need both.

curl "https://api.factql.ai/whoami" -H "X-API-Key: $FACTQL_API_KEY"

Response

{
  "key": { "prefix": "fl_live_Z7Ei", "name": "Default", "environment": "live" },
  "account": { "type": "developer", "plan": "free" },
  "client_id": "tenant-f568009e0b87",
  "workspace_id": "03137418-f921-4114-9e0a-29930c541146",
  "workspace": { "workspace_id": "03137418-…", "name": "General", "slug": "general" },
  "sample": false
}

Add a file

Upload a CSV or Excel file. Each sheet becomes a table. You can also connect a database in the app; see Adding your data.

curl -X POST "https://api.factql.ai/clients/$CLIENT_ID/workspaces/$WORKSPACE_ID/files" \
  -H "X-API-Key: $FACTQL_API_KEY" \
  -F "file=@orders_2026.csv"

Wait until it's ready

FactQL reads the new tables and describes their columns. When status is ready, you can ask about them. A small file takes a minute or two.

curl "https://api.factql.ai/clients/$CLIENT_ID/schema/status?workspace_id=$WORKSPACE_ID" \
  -H "X-API-Key: $FACTQL_API_KEY"

Ask a question

Your key is bound to the workspace, so the question is all you send. For chats with follow-ups, use Conversations. The Python examples use requests (pip install requests). The Node examples need Node 18 or later and use top-level await, so save them as an .mjs file (or set "type": "module").

curl -X POST "https://api.factql.ai/query" \
  -H "X-API-Key: $FACTQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "What were the top 5 products by revenue?"}'