Getting Started

This guide will walk you through creating your first chart with Chartly, from getting an API key to integrating charts into your application.

Paste this URL into your browser and you'll get a chart back immediately:

https://api.chartly.dev/v1/open/chart?type=bar&labels=Jan,Feb,Mar&data=12,19,15

That's the open chart endpoint — a public, no-auth GET that's perfect for READMEs, Slack messages, blog posts, and email previews. Every render carries a small chartly.dev watermark and is rate-limited per IP. See the open chart reference for the full parameter list and limits.

When you're ready to use Chartly in production — without the watermark, with higher quotas, and with PNGs that live forever in cache — pick up an API key and use POST /v1/chart below.

Step 1: Choose Your Authentication Method

Chartly offers two ways to get started:

Option A: Trial API Key (Recommended for Testing)

Perfect for testing and evaluation. Get your trial key instantly.

Get your trial API key:

Visit chartly.dev
Click "Get Trial API Key"
Your trial key will be displayed instantly

Trial API Key Format:

{
  "api_key": "trial_abc123def456xyz789"
}

Trial Limitations:

100 total chart renders
30-day expiration
No account management features

Option B: Full Account (Recommended for Production)

Create a full account for production use with higher limits and additional features.

Get started with a full account:

Sign up: Visit chartly.dev to create your account
Access Dashboard: Log in to manage your API keys and view analytics
Generate API Keys: Create production API keys for different environments
Monitor Usage: Track your usage and billing in real-time

Production API Key Format:

{
  "api_key": "live_abc123def456xyz789"
}

Step 2: Your First Chart

Let's create a simple bar chart showing monthly revenue data.

Method 1: POST Request (Recommended)

This method handles large configurations and complex charts:

curl -X POST "https://api.chartly.dev/v1/chart" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  --output my-first-chart.png \
  -d '{
    "chart": {
      "type": "bar",
      "data": {
        "labels": ["January", "February", "March", "April", "May"],
        "datasets": [{
          "label": "Revenue ($k)",
          "data": [12, 19, 15, 25, 22],
          "backgroundColor": [
            "rgba(255, 99, 132, 0.8)",
            "rgba(54, 162, 235, 0.8)", 
            "rgba(255, 205, 86, 0.8)",
            "rgba(75, 192, 192, 0.8)",
            "rgba(153, 102, 255, 0.8)"
          ],
          "borderColor": [
            "rgba(255, 99, 132, 1)",
            "rgba(54, 162, 235, 1)",
            "rgba(255, 205, 86, 1)", 
            "rgba(75, 192, 192, 1)",
            "rgba(153, 102, 255, 1)"
          ],
          "borderWidth": 1
        }]
      },
      "options": {
        "responsive": false,
        "plugins": {
          "title": {
            "display": true,
            "text": "Monthly Revenue - 2024"
          },
          "legend": {
            "display": false
          }
        },
        "scales": {
          "y": {
            "beginAtZero": true,
            "title": {
              "display": true,
              "text": "Revenue ($k)"
            }
          }
        }
      }
    },
    "format": "png",
    "width": 600,
    "height": 400,
    "backgroundColor": "white"
  }'

Method 2: GET Request with URL Parameters

Perfect for emails, Slack integrations, and quick embeds:

curl "https://api.chartly.dev/v1/chart?chart=%7B%22type%22%3A%22bar%22%2C%22data%22%3A%7B%22labels%22%3A%5B%22Jan%22%2C%22Feb%22%2C%22Mar%22%5D%2C%22datasets%22%3A%5B%7B%22data%22%3A%5B12%2C19%2C15%5D%7D%5D%7D%7D&width=400&height=200&format=png" \
  -H "X-Api-Key: YOUR_API_KEY" \
  --output simple-chart.png

Step 3: Understanding the Response

Successful Response

When successful, Chartly returns the image directly as binary data:

Status Code: 200
Content-Type: image/png or image/svg+xml
Body: Binary image data

Error Response

When there's an error, you'll get a JSON response:

{
  "error": "invalid_input",
  "detail": "Chart configuration is required"
}

Common error codes:

400: Bad input (invalid config, missing parameters)
401: Unauthorized (invalid API key)
429: Rate limit exceeded
500: Internal server error

Step 4: Chart Configuration

Chartly accepts any valid Chart.js 4.4 configuration. Here are the key parameters:

Required Parameters

chart: Complete Chart.js configuration object
width: Image width in pixels (1-2000)
height: Image height in pixels (1-2000)

Optional Parameters

format: "png" (default) or "svg"
backgroundColor: CSS color string or "transparent"

Chart.js Configuration Tips

{
  "chart": {
    "type": "bar",           // Chart type
    "data": {                // Your data
      "labels": [...],
      "datasets": [...]
    },
    "options": {
      "responsive": false,   // Important: Set to false for image generation
      "plugins": {           // Customize appearance
        "title": { ... },
        "legend": { ... }
      },
      "scales": {            // Customize axes
        "x": { ... },
        "y": { ... }
      }
    }
  }
}

Important: Always set responsive: false in your chart options for image generation.

Step 5: Integration Examples

HTML Email

<img src="https://api.chartly.dev/v1/chart/your-chart-id" 
     alt="Monthly Revenue Chart" 
     width="600" 
     height="400">

Slack Bot

// Using Slack Web API
await slack.chat.postMessage({
  channel: '#reports',
  text: 'Monthly revenue report:',
  attachments: [{
    image_url: `https://api.chartly.dev/v1/chart/${chartId}`
  }]
});

React Component

import { useState, useEffect } from 'react';

function ChartImage({ chartConfig, width, height }) {
  const [imageUrl, setImageUrl] = useState(null);
  
  useEffect(() => {
    const generateChart = async () => {
      const response = await fetch('https://api.chartly.dev/v1/chart', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-Api-Key': process.env.CHARTLY_API_KEY
        },
        body: JSON.stringify({
          chart: chartConfig,
          width,
          height,
          format: 'png'
        })
      });
      
      if (response.ok) {
        const blob = await response.blob();
        setImageUrl(URL.createObjectURL(blob));
      }
    };
    
    generateChart();
  }, [chartConfig, width, height]);
  
  return imageUrl ? (
    <img src={imageUrl} alt="Generated chart" />
  ) : (
    <div>Loading chart...</div>
  );
}

Python Script

import requests
import json

# Your chart configuration
chart_config = {
    "chart": {
        "type": "line",
        "data": {
            "labels": ["Mon", "Tue", "Wed", "Thu", "Fri"],
            "datasets": [{
                "label": "Sales",
                "data": [12, 19, 3, 5, 2],
                "borderColor": "rgb(75, 192, 192)",
                "tension": 0.1
            }]
        },
        "options": {
            "responsive": False
        }
    },
    "width": 600,
    "height": 400,
    "format": "png"
}

# Make the request
response = requests.post(
    "https://api.chartly.dev/v1/chart",
    headers={
        "Content-Type": "application/json",
        "X-Api-Key": "YOUR_API_KEY"
    },
    json=chart_config
)

# Save the image
if response.status_code == 200:
    with open("chart.png", "wb") as f:
        f.write(response.content)
    print("Chart saved as chart.png")
else:
    print(f"Error: {response.status_code} - {response.text}")

Step 6: Advanced Features

Permanent Chart URLs

Create shareable URLs that don't expose your API key:

curl -X POST "https://api.chartly.dev/v1/chart/create" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "chart": { ... },
    "width": 600,
    "height": 400
  }'

Response:

{
  "url": "https://api.chartly.dev/v1/chart/abc123def456"
}

Signed URLs

Generate time-limited URLs without exposing your API key:

const crypto = require('crypto');

function createSignedUrl(chartConfig, secret, expirationMinutes = 60) {
  const params = new URLSearchParams({
    chart: JSON.stringify(chartConfig.chart),
    width: chartConfig.width,
    height: chartConfig.height,
    format: chartConfig.format || 'png'
  });
  
  const exp = Math.floor(Date.now() / 1000) + (expirationMinutes * 60);
  params.append('exp', exp);
  
  const message = params.toString();
  const sig = crypto.createHmac('sha256', secret).update(message).digest('hex');
  params.append('sig', sig);
  
  return `https://api.chartly.dev/v1/chart?${params.toString()}`;
}

Next Steps

Now that you've created your first chart, explore these resources:

API Reference - Complete documentation of all endpoints
Chart Types - Examples for every supported chart type
Authentication - Advanced authentication methods
Integrations - HTTP-based integration guides
Troubleshooting - Common issues and solutions

Need Help?

Documentation: You're reading it!
Support: contact@chartly.dev

Ready to integrate? Head to the API Reference for complete endpoint documentation.

Try it in 5 seconds — no signup, no key​

Step 1: Choose Your Authentication Method​

Option A: Trial API Key (Recommended for Testing)​

Option B: Full Account (Recommended for Production)​

Step 2: Your First Chart​

Method 1: POST Request (Recommended)​

Method 2: GET Request with URL Parameters​

Step 3: Understanding the Response​

Successful Response​

Error Response​

Step 4: Chart Configuration​

Required Parameters​

Optional Parameters​

Chart.js Configuration Tips​

Step 5: Integration Examples​

HTML Email​

Slack Bot​

React Component​

Python Script​

Step 6: Advanced Features​

Permanent Chart URLs​

Signed URLs​

Next Steps​

Need Help?​

Try it in 5 seconds — no signup, no key