Create organization-scoped reports from standard JSON, render declarative chart configurations, and retrieve saved report data and notes.
API base URLhttps://api.madfishelements.com/api/v1/visualizations
AuthenticationAuthorization: Bearer <MCP API key or OAuth access token>
Structured reports from standard JSON
Applications, pipelines, and AI agents can create organization-scoped reports with application/json. The active portal-issued bearer credential supplies organization and parent-account ownership. An optional user_id assigns the primary user; when omitted, the report is assigned to the user who owns the credential.
Create is idempotent when external_id is reused. Charts use safe declarative option objects, while table, KPI, and dataset widgets cover common non-chart output. Every response is JSON.
Send the full active MCP API key or native OAuth access token as Authorization: Bearer <credential>. Session cookies, Basic authentication, and X-API-Key are not accepted. Missing, expired, or revoked credentials return 401; license, add-on, connector, and user-access failures return an actionable 403.
JSON bodies and limits
Write operations require a valid JSON object and Content-Type: application/json. Bodies may not exceed 5 MB; reports may contain at most 100 widgets and widget notes may not exceed 20,000 bytes.
Errors
Expect 400 for empty or malformed JSON, 401 for invalid credentials, 403 when one of the live access gates is disabled, 404 for an invalid or out-of-scope report ID, 405 for unsupported methods, 413 for oversized bodies, 422 for schema validation, 429 for rate limits, and 500 when persistence fails.
POST/api/v1/visualizations/reports
Create or upsert a report
Creates a report and returns 201. If the organization already has a report with the same external_id, that report is replaced and keeps its report ID.
Available request fieldsPOST /api/v1/visualizations/reports
Field
Type
Requirement
Description
title
String
Required
Non-empty report title, maximum 255 characters.
widgets
Array
Required
Non-empty list containing 1-100 widget objects. Widget IDs must be unique within the report.
user_id
Integer
Optional; API key user
Primary active user within the report's parent account. When omitted on create, the API key owner is used; updates retain the existing user.
external_id
String
Optional; generated
Stable producer ID, maximum 128 characters. Reusing it on POST replaces that organization's existing report.
description
String
Optional; empty
Report description, maximum 65,535 bytes.
status
String
Optional; draft
One of draft, published, scheduled, shared, or archived.
date_range
String
Optional; empty
Human-readable reporting-period label, maximum 128 characters.
schedule
String
Optional; Manual
Human-readable refresh or delivery label, maximum 64 characters.
layout
Object
Optional; 12 columns
JSON layout configuration. The portal uses columns and gap; default is {"columns":12,"gap":16}.
Install the client with python -m pip install requests.
GET/api/v1/visualizations/reports
List reports
Returns every report summary in the API key organization, including archived reports, ordered by most recently updated. The collection endpoint currently has no pagination or filter parameters.
Available request fieldsGET /api/v1/visualizations/reports
Field
Type
Requirement
Description
(none)
None
Not applicable
This endpoint has no path, query-string, or JSON body fields. Send only the authorization header.
JSON request bodyNo body
{}
This operation has no JSON body. The empty object is shown only to make that absence explicit; do not send it.
Install the client with python -m pip install requests.
PUT/api/v1/visualizations/reports/{report_id}
Replace a report
Sends a complete report representation. PATCH is accepted by the route but follows the same complete-payload validation: title and a non-empty widgets array are still required. Widgets omitted from the body are removed.
Available request fieldsPUT /api/v1/visualizations/reports/{report_id}
Field
Type
Requirement
Description
report_id
String
Required path field
The 24-character lowercase report ID returned by create or list. Reports outside the API key organization return 404.
title
String
Required
Non-empty report title, maximum 255 characters.
widgets
Array
Required
Non-empty list containing 1-100 widget objects. Widget IDs must be unique within the report.
user_id
Integer
Optional; API key user
Primary active user within the report's parent account. When omitted on create, the API key owner is used; updates retain the existing user.
external_id
String
Optional; generated
Stable producer ID, maximum 128 characters. Reusing it on POST replaces that organization's existing report.
description
String
Optional; empty
Report description, maximum 65,535 bytes.
status
String
Optional; draft
One of draft, published, scheduled, shared, or archived.
date_range
String
Optional; empty
Human-readable reporting-period label, maximum 128 characters.
schedule
String
Optional; Manual
Human-readable refresh or delivery label, maximum 64 characters.
layout
Object
Optional; 12 columns
JSON layout configuration. The portal uses columns and gap; default is {"columns":12,"gap":16}.
