API Documentation

Welcome to the DataPulse Analytics API. This RESTful interface provides programmatic access to our analytics engine, predictive models, and data ingestion pipelines. All endpoints return JSON responses and follow standard HTTP conventions.

Base URL & Rate Limits

All API requests should be made to the following base URL:

https://api.datapulse.io/v1

Rate Limits:

• Free Tier: 100 requests/minute, 1,000 requests/day
• Pro Tier: 1,000 requests/minute, 100,000 requests/day
• Enterprise: Custom limits based on contract

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 842
X-RateLimit-Reset: 1698765432

Authentication

Authenticate your requests using Bearer tokens. Include your API key in the Authorization header.

Authorization: Bearer dp_live_7x9k2m4p8q1w3e5r

GET /reports

Retrieve analytics reports for a specified time range and dataset.

curl -X GET "https://api.datapulse.io/v1/reports?start_date=2024-01-01&end_date=2024-01-31&metric=revenue,ltv" \
  -H "Authorization: Bearer dp_live_7x9k2m4p8q1w3e5r"

import requests

headers = {"Authorization": "Bearer dp_live_7x9k2m4p8q1w3e5r"}
params = {"start_date": "2024-01-01", "end_date": "2024-01-31"}
response = requests.get("https://api.datapulse.io/v1/reports", headers=headers, params=params)
print(response.json())

const response = await fetch('https://api.datapulse.io/v1/reports', {
  method: 'GET',
  headers: { 'Authorization': `Bearer ${API_KEY}` },
  params: { start_date: '2024-01-01', end_date: '2024-01-31' }
});
const data = await response.json();

{
  "report_id": "rpt_8x7k9m2p",
  "status": "completed",
  "metrics": {
    "revenue": { "value": 142500.50, "change_pct": 12.4 },
    "ltv": { "value": 845.20, "change_pct": 5.7 }
  },
  "generated_at": "2024-02-01T10:15:30Z"
}

POST /predict

Submit data to our ML engine for real-time forecasting, churn prediction, or anomaly detection.

curl -X POST "https://api.datapulse.io/v1/predict" \
  -H "Authorization: Bearer dp_live_7x9k2m4p8q1w3e5r" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "churn_v2.4",
    "features": { "tenure_months": 14, "support_tickets": 3, "usage_score": 0.62 }
  }'

import requests

payload = {
    "model_id": "churn_v2.4",
    "features": { "tenure_months": 14, "support_tickets": 3 }
}
response = requests.post("https://api.datapulse.io/v1/predict", headers=headers, json=payload)

{
  "prediction_id": "prdc_92x8k4m",
  "outcome": "high_risk",
  "confidence": 0.91,
  "factors": [ "low_engagement", "recent_price_change" ],
  "inference_time_ms": 42
}

POST /data/ingest

Upload structured datasets for processing, transformation, and model training. Supports CSV, JSON, and Parquet formats up to 500MB per request.

Multipart/form-data
file: binary (csv, json, parquet)
dataset_name: "q4_customer_events"
schema_version: "v2"

{
  "ingestion_id": "ing_4k9m2x7p",
  "status": "processing",
  "rows_detected": 148203,
  "estimated_completion": "2024-02-15T09:45:00Z",
  "webhook_url": "https://api.datapulse.io/v1/jobs/ing_4k9m2x7p/status"
}

Error Codes

DataPulse uses standard HTTP status codes and returns detailed error objects in the response body.

{
  "error": {
    "code": "INVALID_SCHEMA",
    "message": "Missing required field: timestamp",
    "details": [ { "field": "timestamp", "action": "add_iso_format" } ]
  }
}

Pagination & Filters

List endpoints support cursor-based pagination and dynamic filtering.

# Query Parameters
limit=50  (default: 50, max: 100)
cursor=eyJpZCI6MTIzfQ==  (base64 encoded)
sort=created_at:desc
filter[status]=completed