Chart Rendering

The charts.land API provides endpoints for creating and rendering charts as images.

POST /charts

Creates a chart and initiates rendering asynchronously. Returns JSON metadata immediately, while the chart is rendered in the background.

Request

Headers:

  • Content-Type: application/json (required)
  • Authorization: Bearer YOUR_API_KEY (required)

Body:

{
  "library": {
    "name": "chartjs|echarts",
    "version": "string"
  },
  "config": {
    // Chart configuration object (format depends on library)
  },
  "output": {
    "format": "png",
    "width": 800,
    "height": 600
  }
}

Parameters:

  • library.name - Chart library to use (chartjs or echarts)
  • library.version - Version of the chart library
  • config - Chart configuration object (format depends on the library)
  • output.format - Output format (currently only png supported)
  • output.width - Optional output width in pixels (default: 800)
  • output.height - Optional output height in pixels (default: 600)

Response

Returns the created chart with metadata. The rendered field will be null initially as rendering happens asynchronously in the background. Use the GET endpoint to poll for the rendered result.

{
  "id": 123,
  "library": { "name": "chartjs", "version": "4.4.0" },
  "config": { ... },
  "output": { "format": "png", "width": 800, "height": 600 },
  "rendered": null,
  "created_at": "2025-09-21T10:30:00.000Z",
  "updated_at": "2025-09-21T10:30:00.000Z"
}

Rendering status:

  • While rendering: rendered field is null
  • After rendering completes: rendered field contains an object with format and download URL
  • Poll the GET /charts/:id endpoint to check when rendering is complete

Status Codes

  • 201 Created - Chart successfully created (rendering initiated in background)
  • 401 Unauthorized - Invalid or missing API key
  • 422 Unprocessable Entity - Chart creation failed

Example 

curl -X POST https://api.charts.land/charts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "library": {
      "name": "chartjs",
      "version": "4.4.0"
    },
    "config": {
      "type": "bar",
      "data": {
        "labels": ["A", "B", "C"],
        "datasets": [{"data": [1, 2, 3]}]
      }
    },
    "output": {
      "format": "png",
      "width": 800,
      "height": 600
    }
  }'

GET /charts/:id

Retrieves a specific chart by ID. Returns chart metadata and rendered media information as JSON. Use this endpoint to poll for rendering completion after creating a chart.

Request

Headers:

  • Authorization: Bearer YOUR_API_KEY (required)

Parameters:

  • id - The ID of the chart to retrieve

Response

Returns chart details including metadata and rendered media information:

While rendering (rendered field is null):

{
  "id": 123,
  "library": { "name": "echarts", "version": "5.4.3" },
  "config": { ... },
  "output": { "format": "png", "width": 800, "height": 600 },
  "rendered": null,
  "created_at": "2025-09-13T10:30:00.000Z",
  "updated_at": "2025-09-13T10:30:00.000Z"
}

After rendering completes (rendered field contains object):

{
  "id": 123,
  "library": { "name": "echarts", "version": "5.4.3" },
  "config": { ... },
  "output": { "format": "png", "width": 800, "height": 600 },
  "rendered": {
    "format": "image/png",
    "download": "https://example.com/rendered-chart.png"
  },
  "created_at": "2025-09-13T10:30:00.000Z",
  "updated_at": "2025-09-13T10:30:05.000Z"
}

Status Codes

  • 200 OK - Success
  • 401 Unauthorized - Invalid or missing API key
  • 404 Not Found - Chart not found or access denied

Example 

curl -H "Authorization: Bearer your-api-key" \
     https://api.charts.land/charts/123

Polling for Rendering Completion

Since chart rendering is asynchronous, you should poll the GET /charts/:id endpoint after creating a chart to check when rendering is complete:

  1. Create a chart using POST /charts - this returns immediately with rendered: null
  2. Poll GET /charts/:id every 2-3 seconds
  3. When rendered is not null, rendering is complete

Example polling workflow:

# Step 1: Create the chart
RESPONSE=$(curl -X POST https://api.charts.land/charts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "library": {"name": "chartjs", "version": "4.4.0"},
    "config": {"type": "bar", "data": {"labels": ["A", "B", "C"], "datasets": [{"data": [1, 2, 3]}]}},
    "output": {"format": "png"}
  }')

CHART_ID=$(echo $RESPONSE | jq -r '.id')

# Step 2: Poll until rendered
while true; do
  CHART=$(curl -H "Authorization: Bearer your-api-key" \
    https://api.charts.land/charts/$CHART_ID)
  
  RENDERED=$(echo $CHART | jq -r '.rendered')
  
  if [ "$RENDERED" != "null" ]; then
    echo "Chart ready!"
    echo $CHART | jq '.rendered.download'
    break
  fi
  
  sleep 2
done

Chart Configuration

The chart configuration format depends on the library you choose:

For detailed configuration examples and documentation, see Libraries Overview page.

Chart Response Fields

When creating a chart via POST /charts or retrieving a chart via GET /charts/:id, the response includes:

  • id - Unique identifier for the chart
  • library, config, output - Chart configuration details, same as provided during creation
  • rendered - Rendering status and media information:
    • null - Chart is still rendering or hasn’t been rendered yet
    • Object - Rendering complete, contains:
      • format - MIME type of the rendered file (e.g., “image/png”, “image/gif”)
      • download - Direct download URL for the rendered chart image
  • created_at, updated_at - ISO timestamp when the chart was created/updated

Checking render status:

  • If rendered === null: Chart is still rendering
  • If rendered is an object: Rendering complete, use rendered.download to access the image

Error Handling

When an error occurs during chart rendering, the API returns a JSON response with error details:

{
  "error": "Error description"
}

Common error scenarios:

  • 401 Unauthorized: Missing or invalid API key
  • 404 Not Found: Chart not found or access denied
  • 422 Unprocessable Entity: Invalid chart configuration or rendering failures