API Documentation

Reference docs for the DataLumio public APIs — generate a key, then use it to run quantitative analysis on your data files.

Quantitative Analysis

Two APIs that work together as a single pipeline: get a key, then use it to run analyses.

How It Works

These two APIs work together as a single pipeline, not as independent features. Think of it as two stages: getting access, then using access.

Stage 1

Getting access (API Key Generation API)

Only a user with an active membership can obtain a key, and they can only get it for their own account:

A user calls our key-generation endpoint with their account email — the same email their membership is tied to.
The server looks up that email, confirms the account exists, and checks whether they currently have an active (non-cancelled) membership. If either check fails, the request is rejected (404 or 403) — no key is issued.
The server also checks whether that user already has an active key. This system deliberately allows only one active key per user at a time — it's a control point, not a limitation for its own sake: it means there's always exactly one credential to track, monitor usage against, and revoke if something goes wrong, rather than an unbounded number of live keys per account.
If all checks pass, the server generates a random secret key, and — critically — stores only a one-way hash of it in the database, never the key itself. The raw key is placed in the response body and sent back to the caller that one time only. After this response, even the system itself cannot recover the raw key from what's stored; only its hash exists, which is used purely to verify a future request, not to reveal the original value.
From this point on, the user (or whoever they choose to pass it to) uses that raw key as their credential for Stage 2. A separate status-check endpoint exists purely so they can later check whether a key is active and how much it's been used, without that check ever exposing the key value again.

Stage 2

Using access (Quantitative Analysis API)

This is the endpoint that actually does work, and it doesn't know or care who the caller is beyond the key they present:

The caller sends the data file to our analysis endpoint along with their key in a dedicated authentication header.
The server hashes the incoming key and looks up that hash in the database. If it doesn't match an active key, the request is rejected before anything else happens (401) — no file is even read.
If the key is valid, the server checks the file's extension against the supported list. If it's not a recognized format, it's rejected immediately (400) without ever touching storage.
The uploaded file is then written to cloud storage, inside a private folder scoped specifically to that key, so different keys' files never mix or collide with each other.
The stored file is handed to the same analysis engine used internally elsewhere in the platform — it runs descriptive statistics, correlation analysis, and (depending on what the data looks like) regression, clustering, or other statistical tasks, then compiles the findings into a formatted Word document.
That report is uploaded back to storage, and a direct link to it is returned in the response.
Whether the call succeeded or failed at any point after key validation, a record is written to an internal request log tied to that specific key — this is what powers the usage numbers you see on the status-check endpoint, and gives full traceability over what each key has been used for.

Why it's split into two APIs instead of one

Separating "get a key" from "use a key" means the credential only needs to be issued once and then reused for as many analyses as needed, without re-checking membership status on every single file upload. It also means the sensitive step (proving who you are / that you're a paying member) only ever happens over your account email, while the high-frequency step (running analyses, possibly from a script or third-party integration) only ever needs a lightweight key — not your account credentials — reducing how often sensitive account information has to be transmitted.

API 1: Quantitative Analysis API

This endpoint lets an authenticated client submit a data file (Excel, CSV, PDF, or Word) and receive back a fully generated quantitative analysis report. The server downloads no external data — you upload the file directly in the request. Internally, the file is stored, run through statistical analysis (descriptive statistics, correlations, regressions, clustering, and visualizations depending on the data), and compiled into a Word document report hosted on our storage and returned as a link.

Every request must include a valid API key. Each attempt — whether it succeeds or fails — is logged internally against that key for auditing and usage tracking.

Request

Full endpoint, header, and request details are provided securely to verified developers after your API key is generated.

POST/v1/analyze

Headers

Header	Required	Description
Api-Key	Yes	Your personal API key, provided securely after generation.

Body — multipart/form-data

Field	Type	Required	Description
file	File	Yes	The data file to analyze. Supported formats: `.xlsx`, `.xls`, `.csv`, `.pdf`, `.docx`. One file per request. All sheets in a workbook are analyzed automatically.

Example

# Example request available in your developer dashboard
# after your API key has been generated.

Response

Success — 200 OK — returned once the report has been generated and stored successfully.

{
  "message": "Report generated successfully!",
  "url": "https://example.com/reports/sample-report.docx"
}

Field	Type	Description
message	string	Confirmation message.
url	string	Direct link to download the generated report document.

Errors

Status	Description
401 Unauthorized	No API key was included in the request.
401 Unauthorized	The key doesn't exist or has been deactivated.
400 Bad Request	The uploaded file's extension isn't one of the supported types.
400 Bad Request	The file was accepted but couldn't be analyzed (e.g. empty, corrupted, or unreadable content).
500 Internal Server Error	Something failed while storing or processing the file — not caused by the input itself.

API 2: API Key Generation API

This is a self-service endpoint that lets a registered user with an active membership generate their own API key for the Quantitative Analysis API above. A user identifies themselves with their account email — no separate login token is required, consistent with how the rest of the platform works.

To keep usage traceable, each user is limited to one active key at a time. If a key already exists, a new one won't be issued until the existing one is deactivated. The raw key value is shown exactly once, at the moment of creation — it is never stored in plain text and can't be retrieved again afterward, only revoked and reissued.

A companion lookup lets a user check whether they currently hold an active key and see basic usage stats, without ever exposing the key value itself again.

Request — Generate a key

Full endpoint and request details are provided securely to verified developers after your API key is generated.

POST/v1/keys

Headers

Header	Required	Description
Content-Type	Yes	application/json

Body

Field	Type	Required	Description
email	string (email)	Yes	The email address of the registered, active-membership account requesting the key.

Example

# Example request available in your developer dashboard
# after your account membership is verified.

Response — Generate a key

Success — 200 OK

{
  "message": "API key created successfully.",
  "api_key": "sample-1234-abcd-key",
  "id": 101
}

Field	Type	Description
message	string	Confirmation message.
api_key	string	The newly generated key. Shown only this one time — save it immediately.
id	integer	Internal reference ID for the key record.

Errors

Status	Description
404 Not Found	No account exists with that email.
403 Forbidden	The account exists but does not currently have an active membership.
409 Conflict	This account already holds an active key.

Request — Check key status

Full endpoint and request details are provided securely to verified developers after your API key is generated.

GET/v1/keys

Query Parameters

Parameter	Type	Required	Description
email	string (email)	Yes	The account email to check.

Example

# Example request available in your developer dashboard
# after your API key has been generated.

Response — Check key status

Success — 200 OK, key exists:

{
  "has_active_key": true,
  "id": 101,
  "request_count": 8,
  "created_at": "2026-01-01T00:00:00.000Z",
  "last_used_at": "2026-01-05T00:00:00.000Z"
}

Success — 200 OK, no key yet:

{
  "has_active_key": false
}

Field	Type	Description
has_active_key	boolean	Whether this account currently has an active key.
id	integer	Internal reference ID for the key (omitted if no active key).
request_count	integer	Number of times the key has been used to call the Analysis API.
created_at	datetime	When the key was generated.
last_used_at	datetime	Timestamp of the key's most recent use (null if never used).

Errors

Status	Description
404 Not Found	No account exists with that email.