API Requests & Responses

This document covers the details of making requests to the Dashboard.PT API and handling responses, including request formats, response structures, and error handling.

Request Format

All requests to the Dashboard.PT API should:

  • Use HTTPS
  • Include an authorization header with your API key
  • Send data in JSON format for POST and PUT requests
  • Use appropriate HTTP methods for different operations

Headers

Header Value Description
Authorization Bearer YOUR_API_KEY Required for authentication
Content-Type application/json Required for POST and PUT requests
Accept application/json Optional, indicates desired response format

Example POST Request

POST /api/data-points HTTP/1.1
Host: dashboard.pt
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "graph_id": 123,
  "data": [
    {
      "timestamp": "2023-06-15 14:30:00",
      "value": 42,
      "label": "Example"
    }
  ]
}

Example GET Request with Parameters

GET /api/graphs?limit=10&offset=0 HTTP/1.1
Host: dashboard.pt
Authorization: Bearer your-api-key
Accept: application/json

Common Request Parameters

Many API endpoints support these common parameters for filtering and pagination:

Parameter Description Example
limit Maximum number of results to return (default: 100, max: 1000) ?limit=50
offset Number of records to skip (for pagination) ?offset=100
sort Field to sort by ?sort=created_at
order Sort order (asc or desc) ?order=desc
filter[field] Filter results by field value ?filter[type]=line
search Search term to find in name or description fields ?search=sales

Filtering Examples

Combine multiple parameters to filter and paginate results:

# Get all line graphs, sorted by creation date (newest first), 10 per page GET /api/graphs?filter[type]=line&sort=created_at&order=desc&limit=10&offset=0 # Search for dashboards with "sales" in the name, 20 per page, page 2 GET /api/dashboards?search=sales&limit=20&offset=20

Request Body Formats

For POST and PUT requests, data must be sent in JSON format. Here are examples for different endpoints:

Creating a Dashboard

POST /api/dashboards HTTP/1.1 Host: dashboard.pt Authorization: Bearer your-api-key Content-Type: application/json { "name": "Sales Dashboard", "description": "Monthly sales performance tracking", "is_public": false }

Creating a Graph

POST /api/graphs HTTP/1.1 Host: dashboard.pt Authorization: Bearer your-api-key Content-Type: application/json { "dashboard_id": 123, "name": "Monthly Sales", "type": "line", "config": { "theme": "light", "title": "Monthly Sales Trends", "xAxis": { "title": "Month" }, "yAxis": { "title": "Revenue (€)", "min": 0 }, "legend": true, "animation": true, "updateFrequency": "daily" }, "is_public": false }

Adding Data Points

POST /api/data-points HTTP/1.1 Host: dashboard.pt Authorization: Bearer your-api-key Content-Type: application/json { "graph_id": 123, "data": [ { "timestamp": "2023-06-15 14:30:00", "value": 42.5, "label": "June Sales" }, { "timestamp": "2023-07-15 14:30:00", "value": 47.8, "label": "July Sales" } ] }

Code Examples

You do not need to install anything: an HTTP client, which your language already has, is enough. These examples send one point to graph 123, so replace the number with your graph's and the key with yours.

cURL

curl -X POST https://dashboard.pt/api/data-points \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"graph_id": 123, "data": [{"timestamp": "2026-06-15 14:30:00", "value": 42.5, "label": "June Sales"}]}'

JavaScript (Node.js 18 or later)

fetch('https://dashboard.pt/api/data-points', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.DASHBOARD_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    graph_id: 123,
    data: [{ timestamp: '2026-06-15 14:30:00', value: 42.5, label: 'June Sales' }]
  })
}).then(async (response) => {
  console.log(response.status, await response.json());
});

Python

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://dashboard.pt/api/data-points",
    data=json.dumps({
        "graph_id": 123,
        "data": [{"timestamp": "2026-06-15 14:30:00", "value": 42.5, "label": "June Sales"}],
    }).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["DASHBOARD_API_KEY"],
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request, timeout=30) as response:
    print(response.status, response.read().decode())

PHP

<?php
$ch = curl_init('https://dashboard.pt/api/data-points');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('DASHBOARD_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'graph_id' => 123,
        'data' => [['timestamp' => '2026-06-15 14:30:00', 'value' => 42.5, 'label' => 'June Sales']],
    ]),
]);
echo curl_exec($ch);

If it works, you get HTTP status 200 and {"status":"success","message":"1 data points added"}.

Warning: Dashboard.PT has no official libraries on npm, PyPI or Packagist. If you find a package with this name, it is not ours: do not give it your key.

Next Steps

Now that you understand how to make API requests, check out these related documents:

Want to try it? The free plan has no time limit.

Create a free account