Chartlink Try API

openapi: 3.2.0
info:
  title: chartlink Try API
  version: 0.1.0
  description: 'chartlink — a platform for charts and maps, made in your brand, with live-updating embed links. NOT CONNECTED YET? In an AI app that takes MCP connectors (Claude and others): your human adds https://chartlink.app/mcp as a

    connector, signs in and picks a workspace — no key, nothing pasted into the chat. In Claude Code or a script:

    an API key from their studio (Workspace → API keys for Claude Code and scripts), sent as Authorization: Bearer. Either way you work in their workspace — their brands and charts. Every chart carries urls.studio, where they

    fine-tune it. A share URL is one published chart. Credits are GET

    /api/billing-info and a checkout link from POST /api/checkout-link, which you hand to your human. WHAT AN ASSET IS

    CHART TYPES: line, bar, area, scatter, dumbbell, slope, heatmap, choropleth, symbol-map, pie, treemap, waterfall, candlestick

    (GET /api/asset-types describes each; GET /api/asset-types/{type}/schema is the contract — read it before the first create.)

    An asset = type + data + config (+ brand). data holds typed columns and row-arrays; config holds

    everything about presentation (title and the other text elements, encoding, chart options). They are updated independently:

    PUT /assets/{id}/data replaces the numbers; PATCH /assets/{id} deep-merges config. Never resend

    what you are not changing. There is no table type (removed): a ranking is a sorted "bar" chart with

    value labels, a row-by-row comparison a "dumbbell" (one point per row = a dot plot) with row labels. KICKER AND TITLE MARKER: kicker {text, font, align, box} is a short line above the title (a section or topic

    that ties charts together; default a small bold line in the emphasis colour). title.marker {position: "top" |

    "left" | "end" | "none", shape: "bar" | "dot" | "square", hang, color, length, thickness, gap} draws one mark

    above the title, beside it (a bar spans the title, a dot or square sits at its first line; hang: true puts it

    in the margin instead of pushing the text right) or after the last word ("end"; skipped when the title already

    ends in . ? ! … : ; so never type a mark into the title). gap is the space to the text everywhere. Both are

    brand-settable (kicker''s style, the marker); the kicker''s words are per chart. kicker.show: false (usually on

    a brand) hides kickers whatever their text; description.show: false does the same for descriptions. POINTS (line, area): chart.points is the one way to put dots on series — a list of rules {series?, at, label?,

    labelPosition?, align?, font?, fill?, ring?, radius?}. A label uses the brand''s data-label style; font overrides it

    key by key, and font.color "series" (here or in the brand''s data-label colour) takes the series'' colour. A note in

    words with the annotation look is an annotation, not a point label. at: "all" | "first" | "last" | "max" | "min" | [x values]. label fills in

    {value}, {series}, {x}: [{at: "max", label: "Peak {value}"}], [{at: [2008, 2020], label: "{x}"}]. markers

    ("none" | "end" | "all") is the end dot, the brand''s house style (default "end"): a chart''s own points are added to it,

    so set markers "none" to drop it; points: [] draws no points at all. LINE BREAKS: "

    " breaks a line in the words you write — title, kicker, description, source, annotations,

    reference-line and highlight labels, point labels, and series names in line/area end labels (which then take

    the room of their lines). A multi-line point label aligns by its side (centred above/below) unless

    points[].align says "left" | "center" | "right"; annotations and free text have align too. Legends and

    tooltips show a series name on one line. AXES: a value axis takes min/max, ticks {count | values: [0, 50, 100] — ticks and gridlines exactly there}, ticks.format,

    ticks.labels.text: the words at those values, one per value (["", "50", "100%"]; "" leaves a tick unlabelled, its

    gridline stays) — omit it for each value formatted.'
servers:
- url: https://chartlink.app
tags:
- name: Try
paths:
  /api/try/fonts:
    get:
      operationId: loadFont
      summary: Load a Google Fonts family+weight (fetched and cached server-side) and get its…
      description: Any Google Fonts family by its exact name. If the family does not ship the exact weight, the nearest one it does ship is loaded and returned as `weight` (requestedWeight says what you asked for). Bundled families (Inter, Source Serif 4, IBM Plex Mono) return their face CSS only — their metrics ship in the client. A family Google does not have is a 404 that says so.
      parameters:
      - schema:
          type: string
          minLength: 1
        required: true
        name: family
        in: query
      - schema:
          type: integer
          minimum: 100
          maximum: 900
          default: 400
        required: false
        name: weight
        in: query
      responses:
        '200':
          description: Face CSS and metrics
        '404':
          description: Font unavailable
      tags:
      - Try
  /api/try/fonts/catalog:
    get:
      operationId: listFonts
      summary: 'Every Google Fonts family usable in a chart: name, category, the upright…'
      description: About 1,800 families with a Latin subset, most used first. Any of them works as font.family on any text element; use a weight from its weights list (GET /fonts loads the nearest one otherwise). source says whether the list is Google's live catalogue or a short fallback while Google could not be reached.
      responses:
        '200':
          description: Font catalogue
      tags:
      - Try
  /api/try/read:
    post:
      operationId: tryReadData
      summary: 'Without an account: read pasted data into one table with AI (as POST…'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  minLength: 1
                  maxLength: 20000
              required:
              - text
      responses:
        '200':
          description: The table
        '422':
          description: No table in the text
        '429':
          description: Limit reached
        '503':
          description: AI not set up
      tags:
      - Try
  /api/try/look:
    post:
      operationId: tryBrandFromScreenshot
      summary: 'Without an account: set up a brand from screenshots for one line chart — the…'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                images:
                  type: array
                  items:
                    type: string
                    maxLength: 3000000
                  minItems: 1
                  maxItems: 2
                  description: 'Screenshots as data: URLs'
                text:
                  type: string
                  maxLength: 500
                measured:
                  type: string
                  maxLength: 1500
                  description: Colours measured from the screenshots' pixels
              required:
              - images
      responses:
        '200':
          description: 'The brand: tokens, templates'
        '429':
          description: Limit reached
        '502':
          description: AI failed
        '503':
          description: AI not set up
      tags:
      - Try
  /api/try/event:
    post:
      operationId: tryEvent
      summary: Something a visitor did on the landing page, counted (anonymously, with the…
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  enum:
                  - load
                  - chart
                  - style
                  - shape
                  - data.open
                  - data.read
                  - screenshot
                  - start
                  - link
                  - leave
                detail:
                  type: string
                  maxLength: 60
              required:
              - action
      responses:
        '204':
          description: Counted
      tags:
      - Try
  /api/try/keep:
    post:
      operationId: tryKeep
      summary: A visitor kept a chart made in Try it and went on to sign up (counted, nothing…
      responses:
        '204':
          description: Counted
      tags:
      - Try
  /api/try/looks:
    get:
      operationId: tryLooks
      summary: The starter looks a new brand can begin from, each with its settings (tokens…
      responses:
        '200':
          description: Looks
      tags:
      - Try
  /api/try/starter:
    get:
      operationId: tryStarter
      summary: The starter look every new brand begins with (tokens, templates)
      responses:
        '200':
          description: Settings
      tags:
      - Try
  /api/try/detect:
    post:
      operationId: tryDetectGeography
      summary: Which geography a column of region names or codes belongs to (as POST…
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                values:
                  type: array
                  items:
                    anyOf:
                    - type: string
                    - type: number
                  maxItems: 2000
              required:
              - values
      responses:
        '200':
          description: Matches, best first
      tags:
      - Try
  /api/try/geographies/{id}/data:
    get:
      operationId: tryGeographyData
      summary: A geography's boundaries, to draw a map (as GET /geographies/{id}/data)
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: GeographyData
        '404':
          description: Not a stored geography
      tags:
      - Try