REST API Reference

Our REST API provides programmatic access to all Luminal Analytics features. The API is RESTful, uses JSON for data exchange, and follows standard HTTP conventions.

Base URL

https://api.luminalanalytics.com/v1

Authentication

All API requests require authentication. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Rate Limiting

API requests are rate limited to:

Free Plan: 1,000 requests per hour
Professional Plan: 10,000 requests per hour
Enterprise Plan: Custom limits

Rate limit headers are included in all responses:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9999
X-RateLimit-Reset: 1625097600

Datasets

List Datasets

Get a list of all datasets in your account.

GET /datasets

Parameters:

page (optional): Page number for pagination (default: 1)
limit (optional): Number of results per page (default: 50, max: 100)
search (optional): Search term to filter datasets

Response:

{
  "data": [
    {
      "id": "ds_1234567890",
      "name": "Sales Data Q4",
      "description": "Quarterly sales figures",
      "size": 1048576,
      "rows": 10000,
      "columns": 15,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "pages": 1
  }
}

Create Dataset

Upload a new dataset to your account.

POST /datasets

Request Body:

{
  "name": "My Dataset",
  "description": "Dataset description",
  "data": "csv,data,here\n1,2,3\n4,5,6",
  "format": "csv"
}

Response:

{
  "id": "ds_1234567890",
  "name": "My Dataset",
  "description": "Dataset description",
  "size": 1024,
  "rows": 2,
  "columns": 3,
  "status": "processing",
  "created_at": "2024-01-15T10:30:00Z"
}

Get Dataset

Retrieve details about a specific dataset.

GET /datasets/{dataset_id}

Update Dataset

Update dataset metadata.

PUT /datasets/{dataset_id}

Delete Dataset

Delete a dataset and all associated analyses.

DELETE /datasets/{dataset_id}

Analyses

Create Analysis

Create a new data analysis.

POST /analyses

Request Body:

{
  "dataset_id": "ds_1234567890",
  "name": "Monthly Sales Analysis",
  "query": {
    "select": ["month", "region", "sales"],
    "where": {
      "date": {
        "gte": "2024-01-01",
        "lt": "2024-12-31"
      }
    },
    "group_by": ["month", "region"],
    "aggregates": {
      "total_sales": {
        "field": "sales",
        "function": "sum"
      },
      "avg_sales": {
        "field": "sales",
        "function": "avg"
      }
    },
    "order_by": [
      {
        "field": "month",
        "direction": "asc"
      }
    ],
    "limit": 1000
  }
}

Response:

{
  "id": "an_0987654321",
  "dataset_id": "ds_1234567890",
  "name": "Monthly Sales Analysis",
  "status": "completed",
  "results": {
    "data": [
      {
        "month": "2024-01",
        "region": "North",
        "total_sales": 150000,
        "avg_sales": 5000
      }
    ],
    "meta": {
      "rows": 12,
      "execution_time": 0.045
    }
  },
  "created_at": "2024-01-15T10:35:00Z"
}

List Analyses

GET /analyses

Get Analysis

GET /analyses/{analysis_id}

Delete Analysis

DELETE /analyses/{analysis_id}

Charts

Create Chart

Generate a visualization from analysis results.

POST /charts

Request Body:

{
  "analysis_id": "an_0987654321",
  "type": "line",
  "options": {
    "title": "Monthly Sales Trend",
    "x_axis": {
      "field": "month",
      "label": "Month"
    },
    "y_axis": {
      "field": "total_sales",
      "label": "Total Sales ($)"
    },
    "color_scheme": "blue",
    "width": 800,
    "height": 400
  }
}

Response:

{
  "id": "ch_1122334455",
  "analysis_id": "an_0987654321",
  "type": "line",
  "url": "https://charts.luminalanalytics.com/ch_1122334455",
  "embed_code": "<iframe src='...'></iframe>",
  "created_at": "2024-01-15T10:40:00Z"
}

Chart Types

line - Line chart
bar - Bar chart
pie - Pie chart
scatter - Scatter plot
heatmap - Heat map
histogram - Histogram
box - Box plot

Error Handling

The API uses standard HTTP status codes:

200 - Success
201 - Created
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
429 - Too Many Requests
500 - Internal Server Error

Error responses include details:

{
  "error": {
    "code": "INVALID_DATASET",
    "message": "Dataset not found or access denied",
    "details": {
      "dataset_id": "ds_invalid"
    }
  }
}

SDKs and Libraries

We provide official SDKs for popular programming languages: