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.

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:

1. Visit chartly.dev
2. Click "Get Trial API Key"
3. 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:

1. Sign up: Visit chartly.dev to create your account
2. Access Dashboard: Log in to manage your API keys and view analytics
3. Generate API Keys: Create production API keys for different environments
4. 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:

1. API Reference - Complete documentation of all endpoints
2. Chart Types - Examples for every supported chart type
3. Authentication - Advanced authentication methods
4. Integrations - HTTP-based integration guides
5. 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.