# Output Charts

> Dashboards from JSON with a stable public link that a script, a cron job or an AI agent keeps updating. An agent with nothing but this file can open an account for the person, build a dashboard in one call, publish it for anyone with the link or share it with named people by email, hand back the link and keep the page fresh.

The API is https://api.outputcharts.com; every call sends and returns JSON with the key as a bearer token, except sign-up and the two public reads, which need no key. Every new account starts a seven-day Solo trial with no card; after it, a push answers 403 requires_solo with an upgrade link and the fix that gets the person a Stripe Checkout link. Dashboards, visuals and keys made in the trial are kept. The trial is once per person: a second account of the same mailbox starts on Free, with a fix.

## Start here

- [Sign up for the person](https://api.outputcharts.com/v1/signup): `POST` with `{"email": "...", "agentName": "...", "useCase": "..."}` and no key. Answers 201 with a Manage key (shown once), its MCP URL, and a claim link to give the person: they must open it within 24 hours of sign-up, or pushes answer 403 claim_required until they do; the account is deleted after 30 days if nobody claims or pays. The same address again is 409 email_taken; a mailbox that already had a trial gets the account on Free, with a fix. Sign-up needs the person's email: when they asked for a link and you can call the web, sign them up, asking for the address in one line if you do not have it. The page is live the moment it is made; the claim link is how the person takes the account over.
- **When you cannot sign up or call**: a person who already has an account (Free has no keys), or an assistant that reads pages but cannot send a request, hands back the whole dashboard as one JSON block in the reply, the body under Shapes below. The person imports it signed in, Workspace → Import JSON, on any plan. On Solo they can instead make a key under Account → API keys and give it to you. Never one chart at a time, never a file.
- [The skill file](https://outputcharts.com/skill/SKILL.md): the whole flow, from sign-up to a live link to the upgrade moment, with four worked examples that are valid as written (a pull request queue, AI coding spend, a client's page speed report, a coding team's flow metrics).
- [Agent API docs](https://outputcharts.com/docs/agent-api): one call to a live dashboard (`POST /v1/dashboards` with `visuals` and `publish: true` answers `dashboard.url`), sharing with named people by email (`shareWith` on that call, or `POST /v1/dashboards/{id}/shares`), pushes, appends, CSV bodies, the batch, keys for CI, every error with its fix.
- [MCP server](https://api.outputcharts.com/mcp): the same API as tools. With no key it serves `signup` and `describe_visual_types`; with the key as a bearer token (or the per-key URL the sign-up returns) it serves them all.

```bash
curl -X POST https://api.outputcharts.com/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com","agentName":"Claude Code"}'
```

## Shapes

The body `POST /v1/dashboards` takes, and the same block a person imports by hand. `size` is `{ "w", "h" }`, `w` in columns of 12 and `h` in rows of 50 pixels; leave it out for the type's default. Every visual needs `type` and `document`; `ref` (a-z, 0-9, -) lets a later run update the same visual.

```json
{
  "title": "Support, Q4",
  "ref": "support-q4",
  "scheme": "slate",
  "publish": true,
  "visuals": [
    {
      "type": "kpi",
      "title": "MRR",
      "ref": "mrr",
      "size": { "w": 6, "h": 3 },
      "document": {"label":"MRR","value":12840,"format":"number","prefix":"$","suffix":"","delta":0.12,"deltaFormat":"percent","deltaLabel":"vs last month"}
    },
    {
      "type": "bar",
      "title": "Revenue and cost",
      "ref": "revenue",
      "document": {"orientation":"vertical","mode":"grouped","xKey":"month","series":[{"key":"revenue","label":"Revenue"},{"key":"cost","label":"Cost"}],"data":[{"month":"Jan","revenue":120,"cost":80},{"month":"Feb","revenue":140,"cost":90}]}
    }
  ]
}
```

One example document per type, each valid as written; `GET /v1/schema` has every rule:

- `bar`: `{"orientation":"vertical","mode":"grouped","xKey":"month","series":[{"key":"revenue","label":"Revenue"},{"key":"cost","label":"Cost"}],"data":[{"month":"Jan","revenue":120,"cost":80},{"month":"Feb","revenue":140,"cost":90}]}`
- `bar-horizontal`: `{"orientation":"horizontal","mode":"grouped","xKey":"month","series":[{"key":"revenue","label":"Revenue"},{"key":"cost","label":"Cost"}],"data":[{"month":"Jan","revenue":120,"cost":80},{"month":"Feb","revenue":140,"cost":90}]}`
- `line`: `{"xKey":"date","curve":"monotone","series":[{"key":"users","label":"Users"}],"data":[{"date":"2026-01","users":10}]}`
- `area`: `{"xKey":"date","curve":"monotone","stacked":false,"series":[{"key":"users","label":"Users"}],"data":[{"date":"2026-01","users":10}]}`
- `pie`: `{"nameKey":"category","valueKey":"amount","donut":true,"data":[{"category":"New","amount":40},{"category":"Returning","amount":60}]}`
- `kpi`: `{"label":"MRR","value":12840,"format":"number","prefix":"$","suffix":"","delta":0.12,"deltaFormat":"percent","deltaLabel":"vs last month"}`
- `table`: `{"columns":[{"key":"name","label":"Name","align":"left","format":"text"},{"key":"amount","label":"Amount","align":"right","format":"number"}],"data":[{"name":"Acme","amount":10}]}`
- `markdown`: `{"source":"## Notes\n\n- Pipeline is up\n- See [status](https://example.com)"}`
- `scatter`: `{"xKey":"price","yKey":"units","labelKey":"label","data":[{"price":10,"units":3,"label":"A"}]}`
- `funnel`: `{"nameKey":"stage","valueKey":"count","data":[{"stage":"Visit","count":1000},{"stage":"Signup","count":400},{"stage":"Paid","count":80}]}`
- `gauge`: `{"label":"Utilization","value":72,"min":0,"max":100,"suffix":"%"}`
- `map`: `{"region":"world","idKey":"country","valueKey":"signups","format":"number","data":[{"country":"US","signups":412},{"country":"GB","signups":138},{"country":"DE","signups":96},{"country":"IN","signups":87},{"country":"CA","signups":64},{"country":"BR","signups":41},{"country":"AU","signups":33},{"country":"JP","signups":19}]}`

A `map` row's `idKey` value is a region code: `world` takes ISO 3166-1 alpha-2 codes (`DE`; alpha-3 accepted), `us-states` USPS codes (`CA`; two-digit FIPS accepted), `us-counties` five-digit county FIPS codes (`06037`; the county lines of 2017), one row per region; a code with no shape on the map is refused by name.

## Reference

- [OpenAPI 3.1 document](https://api.outputcharts.com/v1/openapi.json): every `/v1` operation with its request and response shapes, no key needed.
- [Visual types and their rules](https://api.outputcharts.com/v1/schema): each type's document rules, an example document and its size limits, no key needed.
- [Push API](https://outputcharts.com/docs/push-api): replace one visual's document with one `PUT`, for scripts that hold a key.
- [Bar](https://outputcharts.com/docs/visuals/bar), [horizontal bar](https://outputcharts.com/docs/visuals/bar-horizontal), [line](https://outputcharts.com/docs/visuals/line), [area](https://outputcharts.com/docs/visuals/area), [pie](https://outputcharts.com/docs/visuals/pie), [KPI](https://outputcharts.com/docs/visuals/kpi), [table](https://outputcharts.com/docs/visuals/table), [markdown](https://outputcharts.com/docs/visuals/markdown), [scatter](https://outputcharts.com/docs/visuals/scatter), [funnel](https://outputcharts.com/docs/visuals/funnel), [gauge](https://outputcharts.com/docs/visuals/gauge), [map](https://outputcharts.com/docs/visuals/map): the JSON document each visual type takes, with a live example.

## Product

- [Pricing](https://outputcharts.com/pricing): Free is one dashboard by paste; Solo ($10 a month or $96 a year) is 20 dashboards, API keys, push, Format with AI and public pages without the bar. The seven-day trial is Solo.
- [Gallery](https://outputcharts.com/gallery): public dashboards their owners chose to list.
- [Blog](https://outputcharts.com/blog): tutorials, one per use case.