REST API Reference

The complete HTTP surface of mmm-framework-server — the FastAPI application behind the platform — grouped by functional area and generated from the live OpenAPI schema at v1.0.0.

mmm-framework-server is the separate server package that hosts the agent, sessions, projects, and every job endpoint. Start it with uvicorn mmm_framework_server.main:app (default port :8000); in development the React frontend proxies /api to it. Model fits run in-kernel, so no Redis or external worker is required.

For machine consumption, the raw schema this page is built from is published at shared/openapi.json. A running server also serves the interactive Swagger UI at /docs and the same schema at /openapi.json.

Authentication. In the default single-user development posture the API is open — no route carries an authentication dependency, so a default install should be treated as trusting everyone who can reach its ports and deployed behind your own perimeter. In the hosted multi-user posture (MMM_AGENT_HOSTED=1) sessions must be server-minted via POST /sessions and the unguessable session ID acts as a bearer capability scoping plots, files, and kernels, while the /auth/* routes provide the built-in organization/JWT layer used by the frontend. See Security & Deployment Posture and Trust & Security for the full picture.

This page is generated

Do not edit the reference sections by hand. Regenerate with python3 tools/build_rest_docs.py run from docs/ after re-exporting shared/openapi.json from the live app. The generator asserts that every operation in the schema is rendered.

Conventions

Identifiers. thread_id names an Oracle session (chat thread, workspace, kernel); project_id names a project. Session-scoped resources (plots, tables, files, reports) are salted to their thread.
Non-blocking jobs. Heavy work follows one pattern: a POST returns a job_id, and a sibling GET …/{job_id} polls until the persisted result is ready (validation, spec-curve, planner, experiment design, deck generation, garden tests, notebook cells).
Errors. Request-shape failures return 422 with the standard HTTPValidationError body; authorization failures on scoped resources surface as 404 (existence is not leaked).
Downloads. …/download endpoints stream a file (HTML report, PPTX deck, CSV export) even where the generated schema below shows a generic JSON response.
Per-request LLM overrides. POST /chat accepts optional headers (x-provider, x-model-name, x-api-key, x-base-url, and the x-expert-* variants) that override the configured model for that session's orchestrator and expert; authorization is the optional org-auth bearer token.

Generated from shared/openapi.json — MMM Agent API v1.0.0 — 202 operations across 167 paths. Do not edit this section by hand; re-run python3 tools/build_rest_docs.py.

Sessions & Chat 25

The Oracle: the streaming /chat loop plus per-session lifecycle and state — model spec, causal DAG, assumptions, workflow tracker, history, rewind, and export.

DELETE/assumption/{thread_id}/{key}Retract Assumption Endpoint

Parameters

Name	In	Type	Required
`key`	path	string	required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — RetractAssumptionBody

Field	Type	Required	Notes
`reason`	string	required

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/assumption_history/{thread_id}/{key}Get Assumption History Endpoint

Distinct route prefix so {key:path} can't shadow the list endpoint.

Parameters

Name	In	Type	Required
`key`	path	string	required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/assumptions/{thread_id}List Assumptions Endpoint

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`history`	query	boolean	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/assumptions/{thread_id}Record Assumption Endpoint

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — RecordAssumptionBody

Field	Type	Required
`key`	string	required
`value`	any	required
`rationale`	string	required
`category`	string = "other"	optional
`change_note`	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/chatChat Endpoint

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional
`x-api-key`	header	string, nullable	optional
`x-base-url`	header	string, nullable	optional
`x-expert-api-key`	header	string, nullable	optional
`x-expert-base-url`	header	string, nullable	optional
`x-expert-model`	header	string, nullable	optional
`x-expert-provider`	header	string, nullable	optional
`x-model-name`	header	string, nullable	optional
`x-provider`	header	string, nullable	optional

Request body

application/json (required) — ChatRequest

Field	Type	Required
`message`	string	required
`thread_id`	string = "default_thread"	optional
`page_context`	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/dag/{thread_id}Dag Endpoint

Return the current DAG (if any) plus a fresh identifiability report. Pulls DAG from dashboard_data['dag']['spec'] which propose_dag writes.

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

PUT/dag/{thread_id}Update Dag

Manually update the DAG for a session.

Accepts React Flow node/edge format, converts to DAGSpec, validates, and persists into the agent state dashboard_data.dag.

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — DAGUpdateRequest

Field	Type	Required	Notes
`nodes`	array of object	required
`edges`	array of object	required

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/history/{thread_id}Get History

Return the checkpoint timeline for this thread, newest first.

Each entry includes the checkpoint id, parent id, a short label derived from the next node, and the count of messages at that point. The frontend uses this to drive Back and Retry.

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/rewind/{thread_id}Rewind

Fork the thread back to an earlier checkpoint.

update_state(target_config, {}) writes a new checkpoint whose parent is target_config's checkpoint_id and inherits its values. The thread's tip moves to this fork, so subsequent reads return the rewound state.

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — RewindRequest

Field	Type	Required	Notes
`checkpoint_id`	string	required

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/sessionsList Sessions Endpoint

Parameters

Name	In	Type	Required
`limit`	query	integer	optional
`project_id`	query	string, nullable	optional
`skip`	query	integer	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/sessionsCreate Session Endpoint

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — CreateSessionRequest

Field	Type	Required
`name`	string, nullable	optional
`project_id`	string, nullable	optional
`modeling_mode`	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/sessions/{thread_id}Get Session Endpoint

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

PATCH/sessions/{thread_id}Update Session Endpoint

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — UpdateSessionRequest

Field	Type	Required	Notes
`name`	string, nullable	optional
`project_id`	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

DELETE/sessions/{thread_id}Delete Session Endpoint

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/sessions/{thread_id}/artifactsList Artifacts Endpoint

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/sessions/{thread_id}/exportExport Session Endpoint

Download the session's Python work as a standalone, runnable script.

Synthesizes a preamble that reconstitutes tool-injected state (dataset, fitted model, helpers), then replays the conversation's tool calls (fits as build_and_fit with the fitted spec embedded, model ops, EDA) and execute_python cells in order — so the download is a real, portable reproduction of the session, not a code dump that NameErrors. scope narrows to last (final user turn) or turn:<k> (1-based); invalid values export everything. See agents/session_export.build_session_script.

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`scope`	query	string	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/sessions/{thread_id}/filesList Files Endpoint

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/sessions/{thread_id}/load-modelLoad Model Endpoint

Load a saved fitted model into the session directly. UI buttons call this instead of asking the agent to run the load_fitted_model tool.

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — LoadModelRequest

Field	Type	Required	Notes
`name`	string	required

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

PATCH/sessions/{thread_id}/modeSet Session Mode Endpoint

Switch a session's modeling mode (mmm | causal_inference | general_bayes | descriptive). The next /chat turn reads it to select the prompt framing + tools.

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — SetSessionModeRequest

Field	Type	Required	Notes
`modeling_mode`	string	required

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

PATCH/spec/{thread_id}Update Spec

Server-authoritative manual edit of the model configuration.

Writes the edited model_spec directly into the agent state and locks the leaf fields the user actually changed (diffed server-side) so the LLM can no longer silently overwrite them. unlock_paths hands fields back to the LLM.

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — SpecUpdateRequest

Field	Type	Required
`model_spec`	object	required
`lock_paths`	array of string, nullable	optional
`unlock_paths`	array of string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/spec/{thread_id}/resolveResolve Spec Change

Confirm or decline an LLM-proposed change to a user-locked field.

approve applies the proposed value (and keeps the field locked at the new value). reject keeps the user's value and writes a note into the thread so the LLM has decline-memory and won't re-propose the same change next turn.

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — SpecResolveRequest

Field	Type	Required	Notes
`path`	string	required
`action`	string	required

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/state/{thread_id}Get State

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

DELETE/state/{thread_id}Clear State

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/workflow/{thread_id}Workflow Status Endpoint

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

PATCH/workflow/{thread_id}/{step}Update Workflow Step Endpoint

Parameters

Name	In	Type	Required
`step`	path	integer	required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — WorkflowStepBody

Field	Type	Required	Notes
`status`	string	required
`notes`	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

Data: Upload, EDA & Data Studio 9

Getting data into a session: raw upload, dataset preview, outlier-treatment actions, and the staged Data Studio pipeline (upload → interactive EDA → clean → commit as the working dataset).

GET/data-studio/{thread_id}Data Studio State

The current staging manifest + a fresh preview (for hydration on reopen).

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/data-studio/{thread_id}/commitData Studio Commit

Promote the cleaned staged frame to the session's working dataset. Writes MFF-long CSV, sets dataset_path + spec roles via a STATE-ONLY aupdate_state (no ToolMessage — same pattern as /outliers/apply).

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — StudioCommitRequest

Field	Type	Required	Notes
`reason`	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/data-studio/{thread_id}/discardData Studio Discard

Discard the staging area. Does NOT touch a prior committed dataset_path.

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/data-studio/{thread_id}/edaData Studio Eda

Run the requested EDA analyses on the current staged + transformed frame. Figures are returned INLINE (never pushed to the session Plots tab).

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — StudioEdaRequest

Field	Type	Required
`analyses`	array of string, nullable	optional
`variables`	array of string, nullable	optional
`sensitivity`	string = "default"	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

PUT/data-studio/{thread_id}/pipelineData Studio Pipeline

Replace the whole transform pipeline (+ roles) and re-preview the frame.

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — StudioPipelineRequest

Field	Type	Required	Notes
`steps`	array of object = []	optional
`roles`	object, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/data-studio/{thread_id}/uploadData Studio Upload

Stage a raw upload (.csv/.xlsx/.parquet) for the Data Studio. Lands under thread_dir/data_studio/raw/, (re)initialises the staging manifest with heuristic default roles, and returns the columns + a preview. Does NOT set the session's working dataset — that happens on commit.

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Request body

multipart/form-data (required) — Body_data_studio_upload_data_studio__thread_id__upload_post

Field	Type	Required	Notes
`file`	string (binary)	required

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/dataset/preview/{thread_id}Dataset Preview

Return a time-series for one MFF variable, optionally filtered by one dimension.

Query params: variable — value of VariableName (e.g. 'TV', 'Sales') dim — dimension column to filter on (e.g. 'Geography') value — the dimension value; pass '(national)' to filter NaN rows

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`dim`	query	string, nullable	optional
`value`	query	string, nullable	optional
`variable`	query	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/outliers/{thread_id}/applyApply Outliers Endpoint

Apply confirmed outlier-treatment actions from the UI (EDA tab confirm buttons), without a chat round-trip.

Applies a STATE-ONLY update via aupdate_state (same pattern as PUT /dag): no ToolMessage/AIMessage is appended — an orphan tool message injected outside a real tool call corrupts Anthropic message threads.

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — OutlierApplyRequest

Field	Type	Required	Notes
`action_ids`	array of string	required
`reason`	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/uploadUpload File

Upload a file scoped to a session. Files land in the session WORKSPACE directory (so execute_python and the Files tab share one location), are registered in data_files, and an ABSOLUTE path is returned so the agent can read it from any tool (execute_python runs in the workspace; fit/inspect run in the server cwd).

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Request body

multipart/form-data (required) — Body_upload_file_upload_post

Field	Type	Required	Notes
`file`	string (binary)	required

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

Projects, Team & Knowledge Base 35

Project CRUD and everything scoped to a project: members, onboarding, the guide session, knowledge-base ingest/search, data connections, deliverables, scorecards, sign-offs, pacing, and history.

DELETE/kb/{document_id}Kb Delete Endpoint

Parameters

Name	In	Type	Required
`document_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projectsList Projects Endpoint

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projectsCreate Project Endpoint

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — ProjectCreateRequest

Field	Type	Required	Notes
`name`	string	required
`description`	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}Get Project Endpoint

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

PATCH/projects/{project_id}Update Project Endpoint

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — ProjectUpdateRequest

Field	Type	Required	Notes
`name`	string, nullable	optional
`description`	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

DELETE/projects/{project_id}Delete Project Endpoint

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/data-connectionsList Data Connections Endpoint

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/data-connectionsCreate Data Connection Endpoint

Save a reusable data-source connection (a non-secret bucket/query/table reference; credentials stay ambient via ADC).

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — DataConnectionCreate

Field	Type	Required
`name`	string	required
`kind`	string	required
`config`	object = {}	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

PATCH/projects/{project_id}/data-connections/{connection_id}Update Data Connection Schedule Endpoint

Set or clear a connection's auto-sync interval.

Parameters

Name	In	Type	Required
`connection_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — ConnectionScheduleUpdate

Field	Type	Required	Notes
`sync_interval_minutes`	number, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

DELETE/projects/{project_id}/data-connections/{connection_id}Delete Data Connection Endpoint

Parameters

Name	In	Type	Required
`connection_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/data-connections/{connection_id}/previewPreview Data Connection Endpoint

Read the first rows of a connection (capped) for a UI preview.

Gated as a write: it executes the connection's (billable) query/read and stamps last_synced.

Parameters

Name	In	Type	Required
`connection_id`	path	string	required
`project_id`	path	string	required
`rows`	query	integer	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/data-connections/{connection_id}/testTest Data Connection Endpoint

Parameters

Name	In	Type	Required
`connection_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/data-qualityData Quality Endpoint

Latest pre-fit data-quality summary for a project (from the agent's EDA), surfaced inline at the onboarding 'add data' step. Reads the most-recently updated session that has an EDA envelope; returns {found: false} otherwise.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/deliveryList Delivery Endpoint

Actual in-flight delivery rows stored for the project (issue #123).

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/deliveryUpload Delivery Endpoint

Ingest actual delivery (CSV/TSV or JSON: spend by channel/period) into the delivery registry (issue #123), so pacing compares against the saved plan without spend passed inline. A CSV may be LONG (channel/period/spend columns) or WIDE (a date/period column + one column per channel); re-uploading a period overwrites it.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

multipart/form-data (required) — Body_upload_delivery_endpoint_projects__project_id__delivery_post

Field	Type	Required	Notes
`file`	string (binary)	required

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

DELETE/projects/{project_id}/deliveryDelete Delivery Endpoint

Clear stored delivery for the project (optionally one channel).

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`channel`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/estimandsProject Estimands Endpoint

Declarative estimands for every fitted model in the project, grouped into (estimand × KPI) comparability clusters for the Performance page. Models on the same estimand+KPI sit side-by-side; different-KPI models stay separate (not directly comparable). Assembled from estimand rows persisted on each model_run artifact at fit time — no model loads. Older runs need the backfill (python -m mmm_framework.platform.backfill --what estimands).

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/guideProject Guide Session Endpoint

The project's global guide thread: one persistent session per project that the floating chat bubble talks to (full agent + project KB). Created on first use, reused after — it's a normal session, so it also shows up in the Workspace if the user wants the full view.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/historyProject History Endpoint

Cycle-over-cycle trajectory series for the Performance page: per-channel ROI posteriors (CI contraction), spend shares (allocation migration), share gaps, calibration status, and the portfolio series (misallocation proxy, marginal ROI, EVPI). Assembled purely from stored run_metrics rows — no model loads.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/kbKb List Endpoint

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/kbKb Upload Endpoint

Add a document to a project's knowledge base: store it, then chunk + embed it (in a threadpool) so it becomes searchable. Pass template=true to tag it as a template document (surfaced by the agent's list_templates).

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

multipart/form-data (required) — Body_kb_upload_endpoint_projects__project_id__kb_post

Field	Type	Required	Notes
`file`	string (binary)	required
`template`	boolean = false	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/kb/searchKb Search Endpoint

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`k`	query	integer	optional
`q`	query	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/membersList Members Endpoint

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

PUT/projects/{project_id}/membersSet Members Endpoint

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — MembersRequest

Field	Type	Required	Notes
`members`	array of object	required

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/onboardingProject Onboarding Endpoint

Save the client/project profile, assign team members, and render the profile into a project_brief.md in the project's knowledge base — so both the global guide chat and every session chat can retrieve it. Safe to re-run: the meta merges and the brief is replaced.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — OnboardingRequest

Field	Type	Required
`client_name`	string, nullable	optional
`industry`	string, nullable	optional
`website`	string, nullable	optional
`markets`	string, nullable	optional
`goals`	string, nullable	optional
`kpis`	string, nullable	optional
`channels`	string, nullable	optional
`constraints`	string, nullable	optional
`audience`	string, nullable	optional
`notes`	string, nullable	optional
`members`	array of object, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/onboarding-statusOnboarding Status Endpoint

Self-serve onboarding checklist + next action for a project.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/pacingProject Pacing Endpoint

In-flight pacing for the project (issue #123): the stored actual delivery vs the planned series auto-sourced from the latest saved budget plan, with per-channel divergence, off-pace flags, and an alert digest. Model-free (no fit load) — the expected-outcome delta comes from the check_pacing agent tool. Returns available: false with a reason when there is no saved plan or no delivery yet.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`threshold`	query	number, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/pacing/alertProject Pacing Alert Endpoint

The most recently persisted off-pace alert for the project (issue #123), written by the background pacing-alert sweep. Returns {alert: null} when the project is on pace or the sweep has never run — a cheap poll the FE can use to badge the Pacing tab without recomputing on every page load.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/platform-figuresList Platform Figures Endpoint

Platform-reported attribution figures stored for the project (issue #120).

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/platform-figuresUpload Platform Figures Endpoint

Ingest platform-reported attribution (CSV/TSV or JSON) into the registry (issue #120), so triangulation re-uses it without an inline dict. A CSV has a channel + value column (+ optional source/metric/ attribution_window/incremental/period). Figures are stored **non-incremental** (last-touch) unless a row sets incremental true.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

multipart/form-data (required) — Body_upload_platform_figures_endpoint_projects__project_id__platform_figures_post

Field	Type	Required	Notes
`file`	string (binary)	required

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

DELETE/projects/{project_id}/platform-figuresDelete Platform Figures Endpoint

Clear stored platform figures for the project (optionally one channel).

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`channel`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/scorecardProject Scorecard Endpoint

Recommendation scorecard (issue #109): each channel's realized experiment readout joined to the ROI the model predicted for it (with its credible interval), the error, and whether the realized value landed inside the predicted interval — the model's interval calibration over time. Joined server-side from persisted estimands + the experiment registry; no model loads.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/signoffCreate Signoff Endpoint

Record a formal sign-off approving the model's current assumptions/priors (issue #110): who approved, when, and a hash-chained, tamper-evident audit entry over the assumption snapshot. The accountability chain a procurement / audit reviewer asks for ('who approved these priors?').

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — SignoffRequest

Field	Type	Required
`approver`	string	required
`role`	string, nullable	optional
`note`	string = ""	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/signoffsList Signoffs Endpoint

The project's sign-off audit trail (newest first) + a chain-integrity check (verification.intact is false if a past record was tampered with).

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/triangulationProject Triangulation Endpoint

Triangulation panel — MMM × experiment (× platform) — for the project's channels, reconciled server-side from persisted data (issue #119). Joins the per-channel contribution_roi estimands persisted at fit time with the calibrated/completed experiment readouts in the registry; no model loads. kpi/run_id pin which fitted model's MMM numbers are used (default: the latest contribution_roi model). Any platform-attribution figures ingested for the project (issue #120) are folded in as the third source.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`kpi`	query	string, nullable	optional
`run_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

Experiments & Design 20

The experiment registry with its lifecycle transitions, the Design Studio (design / identify / optimize / simulate jobs), ghost-ads power, and pre-registered analysis plans.

GET/analysis-plansList Analysis Plans Endpoint

Parameters

Name	In	Type	Required
`limit`	query	integer	optional
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/analysis-plansLock Analysis Plan Endpoint

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — LockPlanRequest

Field	Type	Required
`thread_id`	string	required
`name`	string = "Analysis Plan"	optional
`dag`	object, nullable	optional
`research_question`	object, nullable	optional
`assumptions`	array of any, nullable	optional
`extra`	object, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/analysis-plans/{plan_id}Get Analysis Plan Endpoint

Parameters

Name	In	Type	Required
`plan_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

DELETE/analysis-plans/{plan_id}Delete Analysis Plan Endpoint

Parameters

Name	In	Type	Required
`plan_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/experimentsList Experiments Endpoint

Parameters

Name	In	Type	Required
`channel`	query	string, nullable	optional
`project_id`	query	string, nullable	optional
`status`	query	string, nullable	optional
`subchannel`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/experimentsUpsert Experiment Endpoint

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — ExperimentUpsertRequest

Field	Type	Required
`id`	string, nullable	optional
`project_id`	string, nullable	optional
`thread_id`	string, nullable	optional
`channel`	string, nullable	optional
`subchannel`	string, nullable	optional
`design_type`	string, nullable	optional
`status`	string, nullable	optional
`start_date`	string, nullable	optional
`end_date`	string, nullable	optional
`estimand`	string, nullable	optional
`value`	number, nullable	optional
`se`	number, nullable	optional
`notes`	string, nullable	optional
`recommending_run_id`	string, nullable	optional
`design`	object, nullable	optional
`readout`	object, nullable	optional
… 1 more fields (see openapi.json)

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/experiments/{experiment_id}Get Experiment Endpoint

Parameters

Name	In	Type	Required
`experiment_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

DELETE/experiments/{experiment_id}Delete Experiment Endpoint

Parameters

Name	In	Type	Required
`experiment_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/experiments/{experiment_id}/transitionTransition Experiment Endpoint

Validated lifecycle move (draft→planned→running→completed→calibrated, abandoned from any active state). 409 on an illegal transition so the UI can distinguish state-machine conflicts from bad input.

Parameters

Name	In	Type	Required
`experiment_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — ExperimentTransitionRequest

Field	Type	Required
`status`	string	required
`note`	string, nullable	optional
`value`	number, nullable	optional
`se`	number, nullable	optional
`estimand`	string, nullable	optional
`start_date`	string, nullable	optional
`end_date`	string, nullable	optional
`readout`	object, nullable	optional
`calibrated_run_id`	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/calibration-coverageCalibration Coverage Endpoint

Channels × evidence tier (calibrated / stale / model_only) with information decay applied at read time, plus coverage percentages. The in-flight pacing signal is folded in (issue #123): a channel drifting off-pace is a reason to re-look even when its evidence is fresh — the T5 re-evaluation surface reads pacing_status/off_pace per channel + the top-level pacing_alert.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`as_of`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/experiment-designExperiment Design Endpoint

Compute a runnable experiment design: randomized matched-pair geo lift (or observational matched-market DiD) with DiD power/MDE curves, or a budget-neutral randomized flighting schedule for national data. Pure data computation — no model load.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — ExperimentDesignRequest

Field	Type	Required
`channel`	string	required
`design_key`	string, nullable	optional
`method`	string, nullable	optional
`design`	string = "scaling"	optional
`intensity_pct`	number = 50.0	optional
`n_pairs`	integer, nullable	optional
`duration`	integer = 8	optional
`amplitude_pct`	number = 50.0	optional
`block_weeks`	integer = 2	optional
`levels`	array of number, nullable	optional
`seed`	integer = 42	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/experiment-design/identifyStart Structural Identification

Start a NON-BLOCKING structural-identification analysis: designs a multi-level flighting schedule and reports how well its refit would identify the channel's saturation (psi), adstock carryover (alpha) and coefficient (beta) — an optimistic Laplace upper bound, never a guarantee. Poll the returned job_id.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — ExperimentIdentifyRequest

Field	Type	Required
`channel`	string	required
`levels`	array of number, nullable	optional
`block_weeks`	integer, nullable	optional
`duration`	integer = 12	optional
`max_draws`	integer = 200	optional
`seed`	integer = 42	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/experiment-design/identify/{job_id}Get Structural Identification

Poll a structural-identification job: {status, result|null, error|null}.

Parameters

Name	In	Type	Required
`job_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/experiment-design/optimizeStart Experiment Optimization

Start a NON-BLOCKING experiment-setup optimization: explores the design grid and returns the Pareto front (MDE × short-term cost × duration) + a recommended setup with cool-down. Poll the returned job_id.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — ExperimentOptimizeRequest

Field	Type	Required
`channel`	string	required
`margin`	number, nullable	optional
`price`	number, nullable	optional
`kpi_kind`	string = "revenue"	optional
`duration_min`	integer = 4	optional
`duration_max`	integer = 12	optional
`intensity_min`	number = 50.0	optional
`intensity_max`	number = 100.0	optional
`include_holdout`	boolean = true	optional
`durations`	array of integer, nullable	optional
`scaling_intensities`	array of number, nullable	optional
`net_value_axis`	boolean = true	optional
`response_horizon_weeks`	integer = 26	optional
`max_draws`	integer = 80	optional
`seed`	integer = 42	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/experiment-design/optimize/{job_id}Get Experiment Optimization

Poll an experiment-optimization job: {status, result|null, error|null}.

Parameters

Name	In	Type	Required
`job_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/experiment-design/optionsExperiment Design Options Endpoint

What designs the project's data supports (geo designs need >= 4 geos), plus the recommended one.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`channel`	query	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/experiment-design/simulateStart Experiment Simulation

Start a NON-BLOCKING model-anchored economics + A/A·A/B simulation. Loads the project's latest saved model in the background and runs the experiment_economics op; poll the returned job_id for the result.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — ExperimentSimulateRequest

Field	Type	Required
`channel`	string	required
`design_key`	string, nullable	optional
`design`	string = "scaling"	optional
`intensity_pct`	number = 50.0	optional
`n_pairs`	integer, nullable	optional
`duration`	integer = 8	optional
`amplitude_pct`	number = 50.0	optional
`block_weeks`	integer = 2	optional
`levels`	array of number, nullable	optional
`margin`	number, nullable	optional
`price`	number, nullable	optional
`kpi_kind`	string = "revenue"	optional
`seed`	integer = 42	optional
`max_draws`	integer = 100	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/experiment-design/simulate/{job_id}Get Experiment Simulation

Poll an experiment-simulation job: {status, result|null, error|null}.

Parameters

Name	In	Type	Required
`job_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/experiment-prioritiesExperiment Priorities Endpoint

The latest EIG/EVOI priority grid with decay + registry state applied at read time. 404 when the project has no run metrics yet (fit a model first, or backfill: python -m mmm_framework.platform.backfill).

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`as_of`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/ghost-ads/powerGhost Ads Power Endpoint

User-level ghost-ads power calculator — stateless (no dataset or model load): two-proportion / count / revenue MDE, ITT vs treatment-on-treated dilution, users-required inversion, and an optional simulation check of the normal approximation.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — GhostAdsPowerRequest

Field	Type	Required
`users_reached`	integer	required
`baseline_rate`	number = 0.02	optional
`treated_fraction`	number = 0.5	optional
`outcome`	string = "binary"	optional
`baseline_mean`	number, nullable	optional
`baseline_dispersion`	number = 1.0	optional
`value_sd`	number, nullable	optional
`alpha`	number = 0.05	optional
`power_target`	number = 0.8	optional
`two_sided`	boolean = true	optional
`exposure_rate`	number = 1.0	optional
`cost_per_user`	number, nullable	optional
`value_per_conversion`	number, nullable	optional
`target_lift_abs`	number, nullable	optional
`simulate`	boolean = false	optional
`n_sims`	integer = 2000	optional
… 1 more fields (see openapi.json)

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

Validation & Model QA 5

Non-blocking validation jobs on the project’s latest saved model (validate / PPC / residuals / channels / refutation / cross-validation / SBC / coverage), persisted run history, and the specification curve.

POST/projects/{project_id}/spec-curveStart Spec Curve

Start a NON-BLOCKING spec-curve / model-averaging sweep (issue #118): fit a pre-registered set of defensible specs against the project's dataset and LOO-stack them, so the robustness of each channel's ROI to the modelling choices is auditable. The declared spec set is pre-registered to the assumption log BEFORE the sweep so it provably was not chosen after seeing the answers. Multi-fit NUTS — poll the returned job_id for the result.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — SpecCurveRequest

Field	Type	Required
`variants`	array of object, nullable	optional
`rationale`	string = ""	optional
`max_draws`	integer = 400	optional
`compute_loo`	boolean = true	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/spec-curve/{job_id}Get Spec Curve

Poll a spec-curve job: {status, result|null, error|null, n_specs}.

Parameters

Name	In	Type	Required
`job_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/validateStart Model Validation

Start a NON-BLOCKING validation run on the project's latest saved model. check selects which validation to run (validate / ppc / residuals / channels / refutation / cross_validation). Poll the returned job_id.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — ValidationRunRequest

Field	Type	Required	Notes
`check`	string = "validate"	optional
`thread_id`	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/validate/{job_id}Get Model Validation

Poll a validation job: {status, check, result|null, error|null}. result is {content, tables:[ref], plots:[ref]} — fetch refs via /tables/{id} and /plots/{id}.

Parameters

Name	In	Type	Required
`job_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/validationsList Model Validations

History of validation runs for a project — every completed/pending run survives reload: UI-started jobs AND chat-run checks (the agent's validate_model / run_* / run_calibration_check tools persist here too). Pass ?thread_id= to scope the list to the session that launched each run (rows persisted before session stamping existed are excluded). Summary rows only; fetch a run's full result via GET /projects/{id}/validate/{job_id}.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

Planner & Budget 9

Budget plans (create, list, fetch, delete, CSV export) and the non-blocking planner optimize / scenario jobs behind the Almanac page.

GET/budget-plansList Budget Plans Endpoint

List saved budget plans for the caller's org, optionally filtered.

Parameters

Name	In	Type	Required
`model_id`	query	string, nullable	optional
`project_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/budget-plansUpsert Budget Plan Endpoint

Create or update a saved budget plan (no model load — the FE persists an already-computed studio result).

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — BudgetPlanUpsertRequest

Field	Type	Required
`plan_id`	string, nullable	optional
`project_id`	string, nullable	optional
`name`	string	required
`description`	string, nullable	optional
`model_id`	string, nullable	optional
`kind`	string = "optimization"	optional
`spend_changes`	object, nullable	optional
`baseline_outcome`	number, nullable	optional
`scenario_outcome`	number, nullable	optional
`outcome_change`	number, nullable	optional
`outcome_change_pct`	number, nullable	optional
`channel_details`	object, nullable	optional
`plan_payload`	object, nullable	optional

Responses

201 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/budget-plans/{plan_id}Get Budget Plan Endpoint

Parameters

Name	In	Type	Required
`plan_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

DELETE/budget-plans/{plan_id}Delete Budget Plan Endpoint

Parameters

Name	In	Type	Required
`plan_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/budget-plans/{plan_id}/export.csvExport Budget Plan Csv

Download a saved plan as a CSV flight plan (allocation + geo + flighting) — the executable deliverable a planner hands a partner (B5).

Parameters

Name	In	Type	Required
`plan_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/planner/optimizeStart Planner Optimization

Start a NON-BLOCKING budget plan: optimal allocation (national or per-geo) + an optional forward flighting calendar. Poll the returned job_id.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — PlannerOptimizeRequest

Field	Type	Required
`total_budget`	number, nullable	optional
`budget_change_pct`	number, nullable	optional
`min_multiplier`	number = 0.0	optional
`max_multiplier`	number = 2.0	optional
`channel_bounds`	object, nullable	optional
`by_geo`	boolean = false	optional
`flighting`	object, nullable	optional
`max_draws`	integer = 120	optional
`abs_bounds`	object, nullable	optional
`groups`	array of object, nullable	optional
`min_channel_spend`	number \| object, nullable	optional
`objective`	string = "mean"	optional
`mode`	string = "fixed"	optional
`value_per_kpi`	number = 1.0	optional
`frontier`	boolean \| object, nullable	optional
`target_kpi`	number, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/planner/optimize/{job_id}Get Planner Optimization

Poll a planner optimization job: {status, result|null, error|null}.

Parameters

Name	In	Type	Required
`job_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/planner/scenarioStart Planner Scenario

Start a NON-BLOCKING what-if scenario (uncertainty included). Poll the returned job_id.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — PlannerScenarioRequest

Field	Type	Required
`spend_changes`	object	required
`time_period`	array of integer, nullable	optional
`max_draws`	integer = 120	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/planner/scenario/{job_id}Get Planner Scenario

Poll a planner scenario job: {status, result|null, error|null}.

Parameters

Name	In	Type	Required
`job_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

Learning Programs (Sextant) 8

Model-free continuous-learning programs: geo response-surface experiments run in waves — create programs, ingest waves, fit posteriors, and design the next wave.

GET/projects/{project_id}/learning-programsList Learning Programs Endpoint

The project's continuous-learning programs (each row carries its latest fit SNAPSHOT under summary).

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`status`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/learning-programsCreate Learning Program Endpoint

Create a learning program: validate the config (dollars), build + save the initial LearningState, insert the sessions row.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — LearningProgramCreateRequest

Field	Type	Required	Notes
`name`	string, nullable	optional
`config`	object	required

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/learning-programs/{program_id}Get Learning Program Endpoint

One program + its wave timeline (design/observation/snapshot rows).

Parameters

Name	In	Type	Required
`program_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

DELETE/projects/{project_id}/learning-programs/{program_id}Delete Learning Program Endpoint

Delete a program (cascades its waves) AND reap its on-disk directory (state.npz holds the client's accumulated panel + posterior draws).

Parameters

Name	In	Type	Required
`program_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/learning-programs/{program_id}/design-waveDesign Learning Wave Endpoint

Design the next central-composite wave around the program's current center (no fit; optimize=true runs the bounded Laplace-KG scoring in a worker thread so the event loop never blocks). Stores a 'designed' wave row.

Parameters

Name	In	Type	Required
`program_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — LearningDesignWaveRequest

Field	Type	Required
`delta`	number = 0.6	optional
`probe_pairs`	array of array of integer, nullable	optional
`n_geo`	integer, nullable	optional
`n_holdout`	integer = 0	optional
`seed`	integer = 0	optional
`optimize`	boolean = false	optional
`candidate_deltas`	array of number, nullable	optional
`kg_n_outcomes`	integer = 32	optional
`stratify`	boolean = true	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/learning-programs/{program_id}/fitRefit Learning Program Endpoint

Pure refit on the evidence already accumulated (e.g. with overridden ENBS economics). 202 + job_id. 409 while another fit job for this program is still pending/running.

Parameters

Name	In	Type	Required
`program_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — LearningFitRequest

Field	Type	Required
`margin`	number, nullable	optional
`population`	number, nullable	optional
`wave_cost`	number, nullable	optional
`fit_kwargs`	object, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/learning-programs/{program_id}/jobs/{job_id}Get Learning Job Endpoint

Poll a learning-fit job: {status: pending|running|done|error, result: SNAPSHOT|null, error|null, project_id, program_id}.

Parameters

Name	In	Type	Required
`job_id`	path	string	required
`program_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/learning-programs/{program_id}/wavesIngest Learning Wave Endpoint

Ingest wave evidence (rows / CSV text / registry experiment ids) and refit in the background. 202 + job_id; poll .../jobs/{job_id} — the done payload's result is the fit SNAPSHOT. 409 while a fit job for the same program is still pending/running (concurrent fits race on state.npz).

Parameters

Name	In	Type	Required
`program_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — LearningWaveIngestRequest

Field	Type	Required
`rows`	array of object, nullable	optional
`experiment_ids`	array of string, nullable	optional
`csv_text`	string, nullable	optional
`economics`	object, nullable	optional
`fit_kwargs`	object, nullable	optional
`period_col`	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

Reports, Decks & Artifacts 23

Every generated document — fit report, pre-fit design readout, interactive results report, client report and slides, project report and slides, model defense, slide decks — plus stored session artifacts.

DELETE/artifacts/{artifact_id}Delete Artifact Endpoint

Parameters

Name	In	Type	Required
`artifact_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/artifacts/{artifact_id}/downloadDownload Artifact Endpoint

Parameters

Name	In	Type	Required
`artifact_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/artifacts/{thread_id}List Artifacts Endpoint deprecated

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/client-reportView Client Report

Serve the client-ready HTML report (no diagnostics, with nav + confidentiality notice).

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/client-report/downloadDownload Client Report

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/client-slidesView Client Slides

Serve the client-ready Reveal.js slideshow (no MCMC stats, with confidentiality footer).

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/client-slides/downloadDownload Client Slides

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/model-defenseView Model Defense

Serve the model-defense (causal-rigor) report.

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/model-defense/downloadDownload Model Defense

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/prefit-reportView Prefit Report

Serve the pre-fit Model Design Readout (priors, assumptions, prior predictive checks, SBC, change record) generated by the agent's generate_model_design_readout tool.

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/prefit-report/downloadDownload Prefit Report

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/project-reportView Project Report

Serve the project findings HTML report.

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/project-report/downloadDownload Project Report

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/project-slidesView Project Slides

Serve the Reveal.js project slideshow.

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/project-slides/downloadDownload Project Slides

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/generate-deckStart Deck Generation

Start a NON-BLOCKING PowerPoint slide-deck build from the project's latest saved model. Poll the returned job_id; download the .pptx when done.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional
`x-api-key`	header	string, nullable	optional
`x-base-url`	header	string, nullable	optional
`x-model-name`	header	string, nullable	optional
`x-provider`	header	string, nullable	optional

Request body

application/json (required) — GenerateDeckRequest

Field	Type	Required
`client`	string, nullable	optional
`kpi_name`	string = "Revenue"	optional
`currency`	string = "$"	optional
`break_even`	number = 1.0	optional
`margin`	number, nullable	optional
`hdi_prob`	number = 0.8	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/generate-deck/{job_id}Get Deck Job

Poll a slide-deck job: {status, stage, result|null, error|null}.

Parameters

Name	In	Type	Required
`job_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/generate-deck/{job_id}/downloadDownload Deck

Download the generated .pptx for a completed deck job.

Parameters

Name	In	Type	Required
`job_id`	path	string	required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/reportView Report

Serve the generated HTML report inline for embedding.

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/report/downloadDownload Report

Download the generated HTML report.

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/results-reportView Results Report

Serve the interactive MMM Results Report (embedded-posterior, recompute-in-browser) generated by the agent's generate_interactive_report tool.

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/results-report/downloadDownload Results Report

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/slide-deck/downloadDownload Slide Deck

Download the PowerPoint deck generated by the chat agent's generate_slide_deck tool for a session (the project-scoped UI button uses /projects/{id}/generate-deck/{job_id}/download).

Parameters

Name	In	Type	Required
`thread_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

Models, Runs & Portfolio 7

Saved fitted models and their dashboards, run history and cross-run comparison, and the portfolio / benchmark views.

GET/modelsList Models Endpoint

Return model_run artifacts from all sessions as lightweight ModelInfo stubs.

Parameters

Name	In	Type	Required
`limit`	query	integer	optional
`project_id`	query	string, nullable	optional
`status`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/models/{model_id}Get Model Endpoint

Parameters

Name	In	Type	Required
`model_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/models/{model_id}/dashboardGet Model Dashboard Endpoint

Return roi_metrics + decomposition + summary from the model's LangGraph thread.

Parameters

Name	In	Type	Required
`model_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/portfolioPortfolio Endpoint

Everything the home page tracks in one call: model-run history, the experiment log, the latest budget/experiment-design recommendations, and computed next actions (calibrate completed experiments / refresh a stale model / run the recommended next experiment).

Parameters

Name	In	Type	Required
`project_id`	query	string, nullable	optional
`stale_after_days`	query	integer	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/portfolio-benchmarkPortfolio Benchmark Endpoint

Cross-brand benchmarking + governance over the org's projects' run metrics (the agency/holding-co view: rank a brand's channel ROIs against the portfolio, see model freshness + calibration coverage).

Parameters

Name	In	Type	Required
`stale_after_days`	query	integer	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/runsList Runs Endpoint

The model-run lineage timeline: every fit with dataset fingerprint, spec diff vs the previous run, and the assumptions added/revised (the versioned data + model + rationale record).

Parameters

Name	In	Type	Required
`project_id`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/runs/compareCompare Runs Endpoint

Per-channel ROI/spend delta between two runs (B vs A) — the structured answer to "why did this channel change since the last refresh?".

Parameters

Name	In	Type	Required
`run_a`	query	string	required
`run_b`	query	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

Model Garden & Atelier 20

The versioned custom-model registry (register, promote, test, fetch source) and the Atelier IDE services: lint, format, copilot, and the per-model notebook.

GET/model-gardenList Garden Models Endpoint

List the org's Model Garden models (latest version per name by default).

Parameters

Name	In	Type	Required
`all_versions`	query	boolean	optional
`name`	query	string, nullable	optional
`status`	query	string, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/model-gardenRegister Garden Model Endpoint

Register a bespoke model (source defining a BayesianMMM subclass) as a DRAFT. Analyst+ role. The source is AST-validated (never executed here) and stored in the org's garden; POST the test endpoint next to fit + grade it.

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — GardenRegisterRequest

Field	Type	Required
`source_code`	string	required
`name`	string	required
`docs`	string = ""	optional
`version`	integer, nullable	optional
`tags`	array of any, nullable	optional
`dataset_schema`	object, nullable	optional
`recommended_fit`	object, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/model-garden/copilotGarden Copilot Endpoint

Stream a Bayesian-modeling copilot answer (SSE) for the Atelier editor.

Stateless: the client sends the running chat + the current editor source each turn; the server grounds a focused expert system prompt (the oracle contract + PyMC/MMM authoring knowledge) on that source and streams the model's tokens using the SAME data: {...}\n\n / [DONE] framing as /chat. Analyst+ role.

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional
`x-api-key`	header	string, nullable	optional
`x-base-url`	header	string, nullable	optional
`x-model-name`	header	string, nullable	optional
`x-provider`	header	string, nullable	optional

Request body

application/json (required) — GardenCopilotRequest

Field	Type	Required
`messages`	array of CopilotTurn = []	optional
`source_code`	string = ""	optional
`notebook`	NotebookCopilotContext, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/model-garden/copilot/chatGet Copilot Chat

The persisted Atelier copilot chat for this (model, version, surface), or an empty chat when none exists yet. Analyst+ role.

Parameters

Name	In	Type	Required
`name`	query	string	required
`surface`	query	string	optional
`version`	query	integer, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

PUT/model-garden/copilot/chatSave Copilot Chat

Upsert the Atelier copilot chat (one artifact per model/version/surface). PUT an empty messages to clear it. Analyst+ role.

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — CopilotChatSaveRequest

Field	Type	Required
`name`	string	required
`version`	integer, nullable	optional
`surface`	string = "editor"	optional
`messages`	array of object = []	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/model-garden/formatGarden Format Endpoint

Format the editor source (ruff, black fallback) for the IDE *Format* button. Returns the formatted source or a one-line error. Analyst+ role.

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — GardenSourceRequest

Field	Type	Required	Notes
`source_code`	string = ""	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/model-garden/lintGarden Lint Endpoint

"Problems" check for the Atelier editor: real Python diagnostics (ruff — undefined names, unused imports, redefinitions, syntax, with line/column spans) merged with the AST-only garden-contract conventions. Neither path executes the source. Analyst+ role.

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — GardenSourceRequest

Field	Type	Required	Notes
`source_code`	string = ""	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/model-garden/notebookGet Notebook

The persisted notebook doc for this (model, source), or a seeded starter when none exists yet. Analyst+ role.

Parameters

Name	In	Type	Required
`name`	query	string	required
`version`	query	integer, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

PUT/model-garden/notebookSave Notebook

Upsert the notebook doc (one atelier_notebook artifact per notebook). Outputs are stored as content-addressed refs, so they survive. Analyst+.

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — NotebookSaveRequest

Field	Type	Required
`name`	string = "untitled"	optional
`version`	integer, nullable	optional
`cells`	array of object = []	optional
`dataset`	object, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/model-garden/notebook/cellStart Notebook Cell

Start a NON-BLOCKING run of one code cell against the model. Returns a job_id to poll. Analyst+ role.

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — NotebookCellRequest

Field	Type	Required
`name`	string = "untitled"	optional
`version`	integer, nullable	optional
`source_code`	string, nullable	optional
`source_rev`	string = ""	optional
`code`	string = ""	optional
`dataset_path`	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/model-garden/notebook/cell/{job_id}Get Notebook Cell

Poll a notebook cell run: {status, result|null, error|null}. result = {stdout, plots:[{id,title}], tables:[{id,title,...}], is_error}.

Parameters

Name	In	Type	Required
`job_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/model-garden/notebook/datasetNotebook Upload Dataset

Stage a dataset into the notebook's workspace (so cells auto-bind it as df). Analyst+ role; org-scoped synthetic thread (not a session, so no _sess_write).

Parameters

Name	In	Type	Required
`name`	query	string	required
`version`	query	integer, nullable	optional
`authorization`	header	string, nullable	optional

Request body

multipart/form-data (required) — Body_notebook_upload_dataset_model_garden_notebook_dataset_post

Field	Type	Required	Notes
`file`	string (binary)	required

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/model-garden/{name}/versionsList Garden Versions Endpoint

Every version of one garden model, newest first.

Parameters

Name	In	Type	Required
`name`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/model-garden/{name}/{version}Get Garden Model Endpoint

One garden model version (incl. its manifest + compatibility report).

Parameters

Name	In	Type	Required
`name`	path	string	required
`version`	path	integer	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

PATCH/model-garden/{name}/{version}Update Garden Docs Endpoint

Edit a garden version's docs (markdown) IN PLACE — no new version. Analyst+ role. Docs are metadata, so this does not touch the source, manifest, or compatibility status. PUBLISHED versions are immutable (the store rejects the edit -> 409); use "Edit as new version" to change a published model's docs.

Parameters

Name	In	Type	Required
`name`	path	string	required
`version`	path	integer	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — GardenDocsRequest

Field	Type	Required	Notes
`docs`	string = ""	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

DELETE/model-garden/{name}/{version}Delete Garden Model Endpoint

Delete a draft/deprecated garden model (org admin/owner only). Published history is immutable — deprecate instead.

Parameters

Name	In	Type	Required
`name`	path	string	required
`version`	path	integer	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/model-garden/{name}/{version}/promotePromote Garden Model

Human publish gate: promote a TESTED model to PUBLISHED so every project in the org can load it. Org admin/owner only; the model must be tested.

Parameters

Name	In	Type	Required
`name`	path	string	required
`version`	path	integer	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — GardenPromoteRequest

Field	Type	Required	Notes
`note`	string = ""	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/model-garden/{name}/{version}/sourceGet Garden Source

The stored model source text (for the Atelier editor).

Parameters

Name	In	Type	Required
`name`	path	string	required
`version`	path	integer	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/model-garden/{name}/{version}/testStart Garden Test

Start a NON-BLOCKING compatibility test; on pass the model is promoted draft→tested. Returns a job_id to poll.

Parameters

Name	In	Type	Required
`name`	path	string	required
`version`	path	integer	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/model-garden/{name}/{version}/test/{job_id}Get Garden Test

Poll a garden test job: {status, result|null, error|null}.

Parameters

Name	In	Type	Required
`job_id`	path	string	required
`name`	path	string	required
`version`	path	integer	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

Preferences & Branding 5

Global operator preferences and per-project client branding, including SSRF-guarded extraction of brand colors from a client website.

GET/preferencesGet Preferences Endpoint

Global (deployment-wide) user preference defaults.

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

PUT/preferencesPut Preferences Endpoint

Set global preference(s). 403 in the hosted multi-tenant profile — there is no per-user identity, so 'global' would leak across tenants (project-scoped branding remains available: project ids are capabilities).

Request body

application/json (required) — PreferenceUpdateRequest

Field	Type	Required
`key`	string, nullable	optional
`value`	any	optional
`preferences`	object, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/projects/{project_id}/brandingGet Branding Endpoint

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

PUT/projects/{project_id}/brandingPut Branding Endpoint

Validate + save project branding. A manual PUT counts as confirmation unless the payload explicitly says otherwise.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required)

Schema: object

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

POST/projects/{project_id}/branding/extractExtract Branding Endpoint

Extract a branding proposal from a client website (SSRF-guarded, server-side). Saved with confirmed=false — the UI/user must confirm before it styles any output.

Parameters

Name	In	Type	Required
`project_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — BrandingExtractRequest

Field	Type	Required	Notes
`url`	string	required
`save`	boolean = true	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

Files, Tables & Plots 6

Content-addressed session resources: uploaded files, streamed dashboard tables, captured plots, and workspace file listings.

DELETE/files/{file_id}Delete File Endpoint

Parameters

Name	In	Type	Required
`file_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/files/{file_id}/downloadDownload File Endpoint

Parameters

Name	In	Type	Required
`file_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/files/{thread_id}List Files Endpoint deprecated

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/plots/{plot_id}Get Plot Endpoint

Serve a content-addressed Plotly figure JSON. Because the id is a content hash, the response is immutable — the browser caches it permanently, so each plot crosses the wire at most once per client (instead of the full plot list being re-streamed every turn).

Parameters

Name	In	Type	Required
`plot_id`	path	string	required

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/tables/{table_id}Get Table Endpoint

Serve a content-addressed structured table payload (same immutable-cache contract as /plots/{id} — refs stream, rows are fetched once).

Parameters

Name	In	Type	Required
`table_id`	path	string	required

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/workspace/{thread_id}/filesWorkspace Files Endpoint

List the session's registered files (uploads + generated), each with a download id.

Parameters

Name	In	Type	Required
`thread_id`	path	string, nullable	required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

Auth, Orgs & Users 23

The built-in organization auth layer (signup, login, JWT refresh, invites, members, password reset, usage, audit export) and the project-team user roster.

POST/auth/accept-inviteAccept Invite

Request body

application/json (required) — AcceptInviteRequest

Field	Type	Required
`token`	string	required
`password`	string	required
`name`	string, nullable	optional

Responses

200 Successful Response — application/json, TokenResponse

Field	Type	Required
`access_token`	string	required
`refresh_token`	string	required
`token_type`	string = "bearer"	optional
`expires_in`	integer	required

Also: 422 (Validation Error).

GET/auth/audit-exportAudit Export

Parameters

Name	In	Type	Required
`limit`	query	integer	optional
`since`	query	number, nullable	optional
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, object

Also: 422 (Validation Error).

POST/auth/change-passwordChange Password

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — ChangePasswordRequest

Field	Type	Required	Notes
`current_password`	string	required
`new_password`	string	required

Responses

200 Successful Response — application/json, TokenResponse

Field	Type	Required
`access_token`	string	required
`refresh_token`	string	required
`token_type`	string = "bearer"	optional
`expires_in`	integer	required

Also: 422 (Validation Error).

POST/auth/inviteInvite

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — InviteRequest

Field	Type	Required	Notes
`email`	string	required
`role`	Role = "analyst"	optional

Responses

200 Successful Response — application/json, InviteOut

Field	Type	Required
`token`	string	required
`email`	string	required
`role`	Role	required
`org_id`	string	required
`expires_at`	number	required

Also: 422 (Validation Error).

GET/auth/invitesList Invites

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, object

Also: 422 (Validation Error).

DELETE/auth/invites/{token}Revoke Invite

Parameters

Name	In	Type	Required
`token`	path	string	required
`authorization`	header	string, nullable	optional

Responses

204 — no content.

Also: 422 (Validation Error).

POST/auth/loginLogin

Request body

application/json (required) — LoginRequest

Field	Type	Required	Notes
`email`	string	required
`password`	string	required

Responses

200 Successful Response — application/json, TokenResponse

Field	Type	Required
`access_token`	string	required
`refresh_token`	string	required
`token_type`	string = "bearer"	optional
`expires_in`	integer	required

Also: 422 (Validation Error).

POST/auth/logoutLogout

Request body

application/json (required) — LogoutRequest

Field	Type	Required	Notes
`refresh_token`	string	required

Responses

204 — no content.

Also: 422 (Validation Error).

POST/auth/logout-allLogout All

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Responses

204 — no content.

Also: 422 (Validation Error).

GET/auth/meMe

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, UserOut

Field	Type	Required
`user_id`	string	required
`email`	string	required
`name`	string, nullable	optional
`org_id`	string	required
`org_role`	Role	required

Also: 422 (Validation Error).

GET/auth/membersList Members

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, object

Also: 422 (Validation Error).

PATCH/auth/members/{user_id}Set Member Role

Parameters

Name	In	Type	Required
`user_id`	path	string	required
`authorization`	header	string, nullable	optional

Request body

application/json (required) — RoleUpdate

Field	Type	Required	Notes
`role`	Role	required

Responses

200 Successful Response — application/json, object

Also: 422 (Validation Error).

DELETE/auth/members/{user_id}Remove Member

Parameters

Name	In	Type	Required
`user_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

204 — no content.

Also: 422 (Validation Error).

POST/auth/password-reset/confirmPassword Reset Confirm

Request body

application/json (required) — PasswordResetConfirm

Field	Type	Required	Notes
`token`	string	required
`new_password`	string	required

Responses

204 — no content.

Also: 422 (Validation Error).

POST/auth/password-reset/requestPassword Reset Request

Request body

application/json (required) — PasswordResetRequest

Field	Type	Required	Notes
`email`	string	required

Responses

202 Successful Response — application/json, object

Also: 422 (Validation Error).

POST/auth/refreshRefresh

Request body

application/json (required) — RefreshRequest

Field	Type	Required	Notes
`refresh_token`	string	required

Responses

200 Successful Response — application/json, TokenResponse

Field	Type	Required
`access_token`	string	required
`refresh_token`	string	required
`token_type`	string = "bearer"	optional
`expires_in`	integer	required

Also: 422 (Validation Error).

POST/auth/signupSignup

Request body

application/json (required) — SignupRequest

Field	Type	Required
`organization`	string	required
`email`	string	required
`password`	string	required
`name`	string, nullable	optional

Responses

200 Successful Response — application/json, TokenResponse

Field	Type	Required
`access_token`	string	required
`refresh_token`	string	required
`token_type`	string = "bearer"	optional
`expires_in`	integer	required

Also: 422 (Validation Error).

GET/auth/usageUsage

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, object

Also: 422 (Validation Error).

POST/auth/users/{user_id}/deactivateDeactivate User

Parameters

Name	In	Type	Required
`user_id`	path	string	required
`authorization`	header	string, nullable	optional

Responses

204 — no content.

Also: 422 (Validation Error).

GET/usersList Users Endpoint

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

POST/usersCreate User Endpoint

Request body

application/json (required) — UserCreateRequest

Field	Type	Required
`name`	string	required
`email`	string, nullable	optional
`role`	string = "analyst"	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

PATCH/users/{user_id}Update User Endpoint

Parameters

Name	In	Type	Required
`user_id`	path	string	required

Request body

application/json (required) — UserUpdateRequest

Field	Type	Required
`name`	string, nullable	optional
`email`	string, nullable	optional
`role`	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

DELETE/users/{user_id}Delete User Endpoint

Parameters

Name	In	Type	Required
`user_id`	path	string	required

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

Health & Platform Meta 7

Liveness and observability probes plus platform discovery: model configuration and the LM Studio / Vertex model lists and the integrations catalog.

GET/healthHealth Check

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

GET/integrations/catalogIntegrations Catalog Endpoint

List available data-source + ad-platform integrations (non-secret).

Powers the Settings "Data connections" section: which connectors exist, whether their optional SDK is installed, the auth story, and (for ad platforms) the recommended ingestion path. No credentials are returned.

Requires an authenticated principal: the installed-SDK flags reveal deployment topology, so the endpoint is gated like its neighbours rather than left open for reconnaissance.

Parameters

Name	In	Type	Required
`authorization`	header	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/lmstudio-modelsLmstudio Models Endpoint

List models currently loaded in LM Studio (its OpenAI-compatible /v1/models). Returns an empty list if LM Studio isn't running, so the frontend can still offer free-text model entry.

Parameters

Name	In	Type	Required
`base_url`	query	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).

GET/metricsMetrics Endpoint

Prometheus metrics (Phase 4d): per-event audit counters, live kernel count, and the active-fit gauge the autoscaler scales on (§5.1). Sourced from the mmm_audit events so the audit log is the single source of truth.

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

GET/model-configModel Config Endpoint

Report the active LLM provider/model (non-secret).

Lets the frontend decide whether to prompt for an API key: when the server authenticates via Vertex AI / ADC (or a server-side env key), requires_api_key is False and the login key prompt can be skipped. Never returns the API key or credentials contents.

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

GET/observabilityObservability Endpoint

Reliability signals for operators: audit-chain integrity, off-host ship backlog, and recent fit activity. No tenant data.

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

GET/vertex-modelsVertex Models Endpoint

List selectable Vertex models for the configured (or given) project/region.

Combines live-discovered Gemini models, a best-effort Claude catalog, and any configured extra_models. Results are cached briefly. The frontend should still offer a free-text field for ids not in the list (e.g. versioned Claude ids pasted from the Vertex console).

Parameters

Name	In	Type	Required
`location`	query	string, nullable	optional
`project`	query	string, nullable	optional

Responses

200 Successful Response — application/json, JSON (shape not declared in the schema)

Also: 422 (Validation Error).