API Reference

Complete API documentation for Dashtray Scale tier

Overview

The Dashtray API provides programmatic access to your project data. Available exclusively on the Scale tier ($299/month).

API Access Requirements:

• Scale tier subscription
• Valid API key
• Rate limit: 1,000 requests/hour per project

Authentication

All API requests require Bearer token authentication using your API key.

Creating an API Key

1. Navigate to Settings → API Keys
2. Click Create API Key
3. Give it a descriptive name
4. Copy the key immediately (shown only once)

Using Your API Key

Include your API key in the Authorization header:

curl https://api.dashtray.com/api/v1/projects \
  -H "Authorization: Bearer dk_abc123_your_api_key_here"

Security Best Practices:

• Never commit API keys to version control
• Rotate keys regularly
• Use environment variables
• Revoke unused keys immediately

Base URL

https://api.dashtray.com

All endpoints are prefixed with /api/v1/.

Rate Limiting

• Limit: 1,000 requests per hour per project
• Headers: Rate limit info included in every response

{
  "X-RateLimit-Limit": "1000",
  "X-RateLimit-Remaining": "995",
  "X-RateLimit-Reset": "1678901234"
}

When rate limit is exceeded, you’ll receive a 429 Too Many Requests response.

Endpoints

Projects

Get Project

Retrieve information about your project.

GET /api/v1/projects

Response:

{
  "data": {
    "id": "j57abc123",
    "name": "My SaaS App",
    "slug": "my-saas-app",
    "createdAt": 1678901234000
  }
}

Metrics

List Metrics

Retrieve metrics for your project with optional filtering.

GET /api/v1/metrics

Query Parameters:

Parameter	Type	Description
limit	integer	Number of results (max 1000, default 100)
offset	integer	Pagination offset (default 0)
metric_id	string	Filter by specific metric ID
start_date	string	ISO 8601 date (e.g., “2024-01-01”)
end_date	string	ISO 8601 date (e.g., “2024-12-31”)

Example Request:

curl "https://api.dashtray.com/api/v1/metrics?limit=10&metric_id=stripe_mrr" \
  -H "Authorization: Bearer dk_abc123_your_api_key_here"

Response:

{
  "data": [
    {
      "id": "m_abc123",
      "metric_id": "stripe_mrr",
      "value": 15000,
      "unit": "USD",
      "timestamp": 1678901234000,
      "metadata": {
        "currency": "usd",
        "interval": "month"
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Integrations

List Integrations

Get all connected integrations for your project.

GET /api/v1/integrations

Response:

{
  "data": [
    {
      "id": "int_abc123",
      "type": "stripe",
      "status": "active",
      "connected_at": 1678901234000,
      "last_sync": 1678905678000,
      "sync_status": "active"
    }
  ]
}

Dashboards

List Dashboards

Retrieve all dashboards in your project.

GET /api/v1/dashboards

Response:

{
  "data": [
    {
      "id": "dash_abc123",
      "name": "Revenue Dashboard",
      "description": "Track all revenue metrics",
      "type": "custom",
      "created_at": 1678901234000,
      "updated_at": 1678905678000
    }
  ]
}

Health Check

Check API Status

Verify API availability (no authentication required).

GET /api/v1/health

Response:

{
  "status": "healthy",
  "timestamp": 1678901234000,
  "version": "1.0.0"
}

Error Handling

The API uses standard HTTP status codes:

Status Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn’t exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Response Format:

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked"
}

Code Examples

Node.js

const DASHTRAY_API_KEY = process.env.DASHTRAY_API_KEY;
const BASE_URL = 'https://api.dashtray.com/api/v1';

async function getMetrics() {
  const response = await fetch(`${BASE_URL}/metrics?limit=100`, {
    headers: {
      'Authorization': `Bearer ${DASHTRAY_API_KEY}`,
      'Content-Type': 'application/json'
    }
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  const data = await response.json();
  return data;
}

// Usage
getMetrics()
  .then(data => console.log('Metrics:', data))
  .catch(error => console.error('Error:', error));

Python

import os
import requests

DASHTRAY_API_KEY = os.environ.get('DASHTRAY_API_KEY')
BASE_URL = 'https://api.dashtray.com/api/v1'

def get_metrics(limit=100):
    headers = {
        'Authorization': f'Bearer {DASHTRAY_API_KEY}',
        'Content-Type': 'application/json'
    }

    response = requests.get(
        f'{BASE_URL}/metrics',
        headers=headers,
        params={'limit': limit}
    )

    response.raise_for_status()
    return response.json()

# Usage
try:
    data = get_metrics()
    print('Metrics:', data)
except requests.exceptions.RequestException as e:
    print('Error:', e)

cURL

#!/bin/bash

DASHTRAY_API_KEY="dk_abc123_your_api_key_here"
BASE_URL="https://api.dashtray.com/api/v1"

# Get metrics
curl "${BASE_URL}/metrics?limit=100" \
  -H "Authorization: Bearer ${DASHTRAY_API_KEY}" \
  -H "Content-Type: application/json"

# Get integrations
curl "${BASE_URL}/integrations" \
  -H "Authorization: Bearer ${DASHTRAY_API_KEY}" \
  -H "Content-Type: application/json"

# Get dashboards
curl "${BASE_URL}/dashboards" \
  -H "Authorization: Bearer ${DASHTRAY_API_KEY}" \
  -H "Content-Type: application/json"

Best Practices

1. Handle Rate Limits

Monitor rate limit headers and implement exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset');
      const waitTime = (resetTime * 1000) - Date.now();
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}

2. Cache Responses

Cache API responses to reduce request count:

const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getCachedMetrics() {
  const cacheKey = 'metrics';
  const cached = cache.get(cacheKey);

  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const data = await getMetrics();
  cache.set(cacheKey, { data, timestamp: Date.now() });
  return data;
}

3. Secure Your Keys

Use environment variables and secret management:

# .env file (never commit this!)
DASHTRAY_API_KEY=dk_abc123_your_api_key_here

# Load in your application
require('dotenv').config();
const apiKey = process.env.DASHTRAY_API_KEY;

4. Monitor Usage

Track your API usage to avoid hitting rate limits:

function logRateLimitInfo(response) {
  const limit = response.headers.get('X-RateLimit-Limit');
  const remaining = response.headers.get('X-RateLimit-Remaining');
  const reset = response.headers.get('X-RateLimit-Reset');

  console.log(`Rate Limit: ${remaining}/${limit} remaining`);
  console.log(`Resets at: ${new Date(reset * 1000).toISOString()}`);
}

Webhooks

For real-time updates, consider using webhooks instead of polling the API. See Webhook Documentation for details.

Support

Need help with the API?

• Email: [e-mail]
• Documentation: Integration Guides
• Status: status.dashtray.com

Changelog

v1.0.0 (Current)

• Initial API release
• Read-only access to projects, metrics, integrations, and dashboards
• Rate limiting: 1,000 requests/hour
• Bearer token authentication

---

Ready to start building? Create your first API key in the Settings page.