Analysis API

The Analysis API drives Diafunc's automatic-analysis workflow programmatically. Create an analysis recipe, upload tabular data, set targets and budget, queue a run, and stream progress — all without provisioning any project, table, or notebook by hand. The server owns provisioning, so the API never asks the caller for an internal entity ID.

It is the same surface that powers the Analyze wizard in the web UI, the diafunc analyze command, and the MCP server's analysis tools.

The Analysis API is served under five sibling top-level paths: /api/v1/analyses, /api/v1/analysis-presets, /api/v1/analysis-events, /api/v1/runs, and /api/v1/triggers. Note that runs and triggers are their own top-level resources, not nested under /analyses.

Every request must carry an API token via the Authorization header. The set of analyses an API token can act on is capped by the token's scopes; tokens scoped to a single project see only that project's analyses.

See Authentication for the shared token, scope, and error model.

The Analysis API is organized around the following resource groups:

Analyses — create an analysis, list recent analyses, look up by id, replace the editable fields wholesale, or delete an analysis (which also tears down the underlying project and any in-flight run).

Typed updates — one endpoint per editable field (name, description, visibility, introduction, hours, budget, targets, questions, segment), so callers can mutate exactly the property they care about without round-tripping the rest of the recipe.

Data ingest — upload the raw-data table for an analysis as a multipart file, fetch it from a remote HTTPS URL (with SSRF protection — no private addresses, no metadata endpoints, redirect re-validation, size cap, content-type sniff), or post it inline as a CSV string for small payloads.

Run lifecycle — queue a run for an analysis, list recent runs, look up a single run, cancel a non-terminal run, and stream the run's progress outputs as they are emitted.

Triggers — schedule analyses to run on a one-shot ISO-8601 timestamp or on a cron expression; list, update, or remove a trigger.

Lab navigation — resolve an analysis to its lab notebook URL once the first run has produced one, without exposing the underlying project or notebook id.

Columns — list the column names and types of an analysis's uploaded data, useful for picking targets or segment columns from a UI.

One-shot run — create an analysis with name, description, targets, hours, and budget; upload the CSV; queue a run; poll the run until it reaches a terminal state.

Iterative tuning — create an analysis once, upload data, then PATCH targets, hours, or budget between runs as you refine what you want to learn from the data. Each run picks up the latest recipe.

Scheduled re-runs — create an analysis, attach a cron trigger to it, and let the platform queue a fresh run on the schedule. The trigger reuses the analysis's data table, so re-uploading new data into the same analysis is enough to keep recurring reports fresh.

Sharing results — set the analysis's visibility to PUBLIC and share the lab navigation URL; viewers with the link can read the resulting notebook without an API token.

Data uploads against an analysis with a run in QUEUED, DISPATCHING, or RUNNING state return 409 Conflict — the body identifies the active run. Either let the run finish or cancel it before re-uploading. Run-queue attempts on a recipe missing required fields (hours, budget, at least one target) return 400 with the list of missing fields.