API Reference

ChartBear provides a simple REST API that accepts application/json request bodies and returns JSON-encoded responses.

Authentication

The ChartBear API uses API keys to authenticate requests. You can view and manage your API key in the Settings section.
All API requests must be made over HTTPS. Be sure to keep your API key secure and do not share it in publicly accessible service such as GitHub or client-side code.

Example


fetch('https://chartbear.app/api/v1/charts', {
  method: 'GET',
  headers: {
    'Content-Type' : 'application/json',
    'Authorization' : 'Bearer your-api-key'
  }
})
.then(response => response.json())
.then(data => console.log(data));

Errors

The ChartBear API uses conventional HTTP status codes.
The API rate limit is 60 requests per minute.

Status codes

200	Ok	All good
201	Created	A new resource has been created
401	Unauthorized	No valid API key provided
402	Payment Required	You have run out of credits
404	Not found	The requested resource doesn’t exist
422	Unprocessable Content	The request was unprocessable due to validation errors
429	Too many requests	Too many requests hit the API too quickly
50x	Server error	Something went wrong on ChartBear's end

Attributes

message string

A human-readable message providing more details about the error

Error object


{
  "message": "Unauthenticated"
}

Charts

Charts are the primary resource on ChartBear.
You can generate charts by sending a POST request with all the necessary parameters.
ChartBear will respond with the URL of the generated chart, along with some additional information.

Endpoints

`POST`	`/api/v1/charts`
`GET`	`/api/v1/charts`

Attributes

uuid string

The chart's unique identifier

url string

The public full url of the chart

type enum

The chart's type. One of bar, line, area and scatter

format enum

The chart's format. One of svg, png@1x, png@2x, jpg@1x, jpg@2x, webp@1x and webp@2x

created_at datetime

The time at which the chart was created, formatted as y-m-d h:m:s

Chart object


{
  "uuid": "y42LW46J9",
  "url": "https://chartbear.s3.eu-west-2.amazonaws.com/charts/y42LW46J9.png",
  "type": "bar",
  "format": "png@2x",
  "created_at": "2024-01-21 14:48:02"
}

Create a chart

Parameters

type enum required

The chart's type. One of bar, line, area and scatter

format enum

The chart's format. One of svg png@1x, png@2x, jpg@1x, jpg@2x, webp@1x and webp@2x
Default: svg

title string

The chart's title

subtitle string

The chart's subtitle

size object

The chart's size

Child Parameters

width integer

The chart's width
Min: 600, Max:1200, Default: 960

height integer

The chart's width
Min: 300, Max:900, Default: 600

margins object

The chart's margins

Child Parameters

top integer

The chart's top margin
Min: 0, Max:80, Default: 40

right integer

The chart's right margin
Min: 0, Max:80, Default: 40

bottom integer

The chart's bottom margin
Min: 0, Max:80, Default: 40

left integer

The chart's left margin
Min: 0, Max:80, Default: 40

series array required

The chart's series array, where your data live. You can add up to four series.
Min size: 1 Max size: 4

Series object

name string required

The name of the series that will appear in the legend

color hex

A valid hex color code
Default: A random color

data array required

The array of data for the series

Datum object

x string|number required

The x value
For scatter charts, it cannot be a string

y number required

The y value

Returns

A chart object

POST /api/v1/chart


const data = {
    "format": "svg",
    "type": "bar",
    "title": "Title",
    "subtitle": "Subtitle",
    "size": {
        "width": 960,
        "height": 600
    },
    "margins": {
        "top": 40,
        "right": 40,
        "bottom": 40,
        "left": 40
    },
    "series": [
        {
            "color": "#FF6C40",
            "name": "2021",
            "data": [
                {
                    "x": "Jan",
                    "y": 12
                },
                {
                    "x": "Feb",
                    "y": 17
                },
                {
                    "x": "Mar",
                    "y": 34
                },
                {
                    "x": "Apr",
                    "y": 43
                },
                {
                    "x": "May",
                    "y": 43
                },
                {
                    "x": "Jun",
                    "y": 58
                },
                {
                    "x": "Jul",
                    "y": 70
                },
                {
                    "x": "Aug",
                    "y": 102
                },
                {
                    "x": "Sep",
                    "y": 98
                },
                {
                    "x": "Oct",
                    "y": 140
                },
                {
                    "x": "Nov",
                    "y": 144
                },
                {
                    "x": "Dec",
                    "y": 173
                }
            ]
        },
        {
            "color": "#2D99FF",
            "name": "2022",
            "data": [
                {
                    "x": "Jan",
                    "y": 24
                },
                {
                    "x": "Feb",
                    "y": 37
                },
                {
                    "x": "Mar",
                    "y": 44
                },
                {
                    "x": "Apr",
                    "y": 63
                },
                {
                    "x": "May",
                    "y": 58
                },
                {
                    "x": "Jun",
                    "y": 98
                },
                {
                    "x": "Jul",
                    "y": 100
                },
                {
                    "x": "Aug",
                    "y": 132
                },
                {
                    "x": "Sep",
                    "y": 124
                },
                {
                    "x": "Oct",
                    "y": 190
                },
                {
                    "x": "Nov",
                    "y": 205
                },
                {
                    "x": "Dec",
                    "y": 299
                }
            ]
        }
    ]
};

fetch('https://chartbear.app/api/v1/charts', {
  method: 'POST',
  body: JSON.stringify(data),
  headers: {
    'Content-Type' : 'application/json',
    'Authorization' : 'Bearer your-api-key'
  }
})
.then(response => response.json())
.then(data => console.log(data));

Response


{
  "uuid": "y42LW46J9",
  "url": "https://chartbear.s3.eu-west-2.amazonaws.com/charts/y42LW46J9.png",
  "type": "bar",
  "format": "svg",
  "created_at": "2024-01-21 14:48:02"
}

List all charts

Returns a list of Chart objects

Returns

A dictionary with a data property that contains an array of Charts. Each entry in the array is a separate Chart object. If no Charts are available, the resulting array is empty.

GET /api/v1/charts


fetch('https://chartbear.app/api/v1/charts', {
  method: 'GET',
  headers: {
    'Content-Type' : 'application/json',
    'Authorization' : 'Bearer your-api-key'
  }
})
.then(response => response.json())
.then(data => console.log(data));

Response


{
  "data": [
    {
      "uuid": "y42LW46J9",
      "url": "https://chartbear.s3.eu-west-2.amazonaws.com/charts/y42LW46J9.png",
      "type": "bar",
      "format": "svg",
      "created_at": "2024-01-21 14:48:02"
    },
    {
      "uuid": "VolejRejN",
      "url": "https://chartbear.s3.eu-west-2.amazonaws.com/charts/VolejRejN.png",
      "type": "bar",
      "format": "svg",
      "created_at": "2024-01-21 14:30:15"
    }
  ]
}