API · Upload a file

Upload a file

POST/clients/{client_id}/workspaces/{workspace_id}/files

Add a CSV or Excel file to a workspace. Each sheet becomes a table you can ask about once the schema is ready.

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"

Path

client_idstring · required

Your tenant, from GET /whoami.

workspace_idstring · required

The workspace, from GET /whoami.

Form data

filefile · required

A .csv or .xlsx file, up to 50 MB.

forceboolean

Rebuild the tables even when the file is byte-for-byte the same as the current version. Default false. It doesn't get around a table-name clash with another file.

Response

200

{
  "filename": "orders_2026.csv",
  "version": 1,
  "tables": [
    { "table_name": "orders_2026", "sheet_name": "orders_2026", "row_count": 600, "column_count": 8 }
  ],
  "sha256": "ffe98cef…",
  "unchanged": false
}

Same name again: a new versionreplaces the file's tables.
Identical bytes: nothing changes, and the response has "unchanged": true and a message. Send force=true to rebuild anyway.
First upload: the response can include "schema_status": "discovering", meaning FactQL has started reading the new tables.
Next: poll Schema status until it reads ready.

Errors

400The file is empty, isn't .csv or .xlsx, or can't be read.

401The key is missing, invalid or revoked.

403The key belongs to a different tenant, or it's the read-only sample key.

404The workspace doesn't exist.

409The workspace is connected to a database, or a table name from this file is already used by another file.

413The file is larger than 50 MB.