Builder API

Overview

The Builder API powers the Mythic Analytics visual workspace. Use it to create insights (saved analytics queries with visualization settings), assemble dashboards from those insights, build canvas funnel maps with tracked nodes and edges, and run SQL against a client's data through server-held credentials.

Every resource is scoped to a single client location. You authenticate with a Builder key — an agency key (ak_) for full read/write across all linked locations, or a viewer key (sk_) for read-only access to one.

Base URL

The Builder API is mounted under /builder.

https://mythic-analytics.gulp.workers.dev/builder

Authentication

Pass a Builder key as a bearer token. See Authentication for the full model, roles, and the location_id scoping rule.

Response envelope

The Builder does not use a single fixed envelope. The shape depends on the operation:

• Reads return { "data": ... } — an array for list endpoints, an object for single-resource endpoints. There is no top-level success or count.
• Writes that return a row (create/update, including the metadata PATCH /dashboards/{id} and PATCH /canvases/{id}) return { "data": { ... } }.
• Writes that return no row (delete, layout patch, toggle) return { "success": true }. Some lifecycle writes add a field, e.g. { "success": true, "version": 4 }.
• Query endpoints return { "success": true, "data": [...], "rows": <n>, ... }.
• Errors return { "error": "<message>" } with the matching HTTP status. Query failures may also include "success": false.

Key concepts

Embedding

GET /builder?ak=ak_... (or ?sk=sk_...) returns an HTML page that loads the admin workspace inside a sandboxed iframe, rather than JSON. This is the one place a key travels in the query string: a document request cannot carry an Authorization header, and the page is what the iframe loads. It accepts theming parameters (theme, transparent, hideHeader, branding, theme_primary, theme_secondary, theme_heading_font, theme_body_font, style) and an optional page (default insights). This endpoint is for embedding the UI, not for programmatic API access.

Canvas versioning

Saving a canvas (POST /canvases/{id}/save) bumps its version and records an immutable snapshot. Publishing marks the current version as live (published_version). You can list versions and roll back by replaying a version's snapshot.

Error handling