chartlink

Stops scheduled fetches; the chart keeps its current data.

Creates a draft. The response includes a low-res PNG preview INLINE — look at it, then iterate with update_asset. Nothing is public until publish_asset, or until you pass publish: true here (one call instead of two, once the chart is final). A success means the config validated AND rendered. Style comes from the defaults and your brand, if any — only set config fields the story needs. data = {columns: [{id,type,...}], rows: [[...], ...]} (row-major, matching column order). LIMITS: keep each call under ~100 KB of rows (asset cap 2 MB) — for larger datasets create with a few rows and attach set_data_source, or append chunks via replace_asset_data.

A brand styles every asset that references it — and the workspace default brand styles everything created without an explicit brand. Create one, then render any asset with brand: "<slug>" to see it applied. Style only: brands can never inject data or text content.

Returns a URL that opens straight into Paddle checkout: no login, no account. It can only add credits to THIS workspace, so it is safe to share. Credits arrive seconds after payment (get_billing).

Returns a URL opening the visual tweak panel for ONE chart (text, colors, spacing, label nudges) with no login. PUBLISH FIRST: the editor saves and republishes a published chart, it cannot publish a draft. Scope: view, tweak, and republish that chart only — never delete, never spend credits, nothing else in the workspace. OFFER THIS whenever the human's request is aesthetic fine-tuning: handing over the wheel beats a nudge-by-nudge back-and-forth. The secret is shown once; links don't expire and can be revoked with revoke_edit_link.

Embeds go dark. Restorable via the REST API (POST /api/assets/{id}/restore).

New id, new embed URLs. Useful for rebranding a chart for another audience.

Runs one fetch on top of the schedule. Returns {ok, rows, published, error}.

Full asset envelope. includePreview=true also returns an inline PNG of the current draft.

Hosting is free (unlimited badged charts, live updates included). One credit makes one chart premium forever: 2400px, SVG, your own branding, no badge. Updates are never metered.

Returns the JSON Schema for the type's config, the data schema, two worked examples (minimal + rich), and `defaults` — the complete config in force when nothing is set (every font, padding, color), which a brand and then the chart's own config merge over. Read this before your first create_asset of a given type; read a baseline value from defaults instead of guessing it.

Chart/table types you can create, with links to per-type schemas.

Filterable list; rows elide config/data. Use get_asset for full bodies.

Style-only token sets applied under your config. Pass a slug as `brand` on create_asset.

countries, us-states, us-states-pr (with Puerto Rico), us-counties, us-zip3, us-zips-<st> (one state's ZIP codes), and every country's states/provinces as <alpha-2>-regions (de-regions, ru-regions…). Pass id to get one geography's full region list — codes (ISO 3166-2 like DE-BY), names and aliases — and read it BEFORE naming regions in your data: unknown regions fail loudly. Set chart.geography to the id; chart.bounds crops.

Templates are named by the NEED they answer (need, asks, tags), each with urls.png (show it to your human) and `columns`: the column ids your data must supply. Pass q with what the person asked for — "map of brazil's states", "ranked bars with flags", "change between two years" — and the list comes back ranked; take the first. Then create_asset with template: <id> and your data — the whole design comes along. Any chart id you were shown works as a template too, not only these.

Makes the draft live. Returns urls: paste urls.embedIframe on iframe platforms; on Substack insert urls.png as an image and link it to urls.page. Pinned history: urls.png + '?v=N'.

THE core flow for refreshing numbers. publish defaults to auto: a published asset republishes immediately (every embed/PNG updates); a draft stays draft. Set publish=false to stage instead. LIMITS: an asset holds up to 2 MB of data, but keep each tool call under ~100 KB of rows — for larger datasets chunk with mode: "append" (publish: "false" on every chunk but the last), or skip inline entirely with set_data_source (the server fetches a URL, up to the full 2 MB).

The URL stops working immediately. List links (prefixes + tokenIds) via GET /assets/{id}/edit-links.

The chart refetches this URL (CSV or JSON) hourly/daily/weekly, replaces its rows, and republishes itself if published — refreshes are free, updates are never metered. Columns stay as defined on the asset: CSV headers / JSON object keys match column ids or labels case-insensitively, with spaces, underscores and hyphens interchangeable (births_per_woman matches a column labeled 'Births per woman'). Fetches once immediately and returns that outcome — check fetch.ok and fix fetch.error before moving on. get_asset shows dataSource + dataSourceState when a source is attached. Clear with clear_data_source.

Creates a workspace and returns its API key (shown ONCE — keep it). Works on a keyless connection; every other tool needs the key. Then put the key where your client keeps it (plugin api_key setting, the Authorization header, or CHARTLINK_API_KEY for the npx bridge) and reconnect.

If a capability is missing, a schema fights you, or docs are wrong: record it here so the owner can fix it. One report per distinct issue, with a real description — reports get fixed same-day when they say what you tried, what you expected, and what happened (title-only reports can't be acted on).

Embeds and PNGs return 410 until republished.

configPatch is DEEP-MERGED: objects merge recursively, arrays replace wholesale, null clears a key — send only what changes. To REMOVE keys (drop document.aspect, delete one of texts[]) pass `config` instead: it REPLACES the whole config (get_asset returns the current one to edit). `data` (if given) replaces rows wholesale. Requires expectedVersion from the last envelope; on 409 re-merge onto the returned `current`. Updating does NOT publish by default — pass publish: true to publish in the same call, or call publish_asset separately.

Deep-merges tokens (objects merge, arrays replace, null clears). Drafts restyle immediately; published assets pick the change up on their next publish. Requires expectedVersion from list_brands.

Same URLs, instantly rebranded: badge removed, 2400px PNG and SVG unlocked, custom branding applies. Idempotent for already-premium charts.

Returns key name + workspace. Call this first — non-destructive auth check. Everything you write is stamped createdBy/updatedBy = key name.