Skip to main content

Create Data Source

Create a new data source to define the structure of your time-series data.

Endpoint​

POST /api/buckets/:bucketId/sources

Authentication​

Key TypeAllowed
Admin (dakkio_a_)✅ Yes
Write (dakkio_w_)✅ Yes
Read (dakkio_r_)❌ No

Recommended: Use a Write key (dakkio_w_) for creating data sources.

What is a data source?

A data source defines the structure (schema) of your data. It tells dakkio:

  • What fields your data will have (e.g., temperature, humidity)
  • What type each field is (e.g., number, string, boolean)
  • What units each field uses (e.g., celsius, percent)

Different sensors or data types should have different data sources.

Request​

Headers​

HeaderTypeRequiredDescription
X-API-Keystring✅ YesYour Write or Admin API key
Content-Typestring✅ YesMust be application/json

Path Parameters​

ParameterTypeRequiredDescription
bucketIdstring✅ YesThe bucket ID (24-character hex string)

Body Parameters​

ParameterTypeRequiredDefaultDescription
namestring✅ Yes-Data source name
typestring❌ NosensorType: sensor, application, service, etc.
descriptionstring❌ No-Description of the data source
schemaobject✅ Yes-Schema defining data fields
downsamplingboolean❌ NotrueEnable automatic downsampling for queries
Automatic Downsampling

When downsampling is enabled (default), queries without explicit aggregation will automatically aggregate data based on the time range to return ~500 data points instead of potentially millions. This optimizes query performance for high-frequency data sources.

The system tracks the average interval between data points and uses this to calculate the appropriate grouping interval (minute, hour, day, week, or month) when auto-downsampling is applied. The default aggregation is avg (average).

Set downsampling: false if you always need raw data points.

Schema Object​

Each field in the schema:

PropertyTypeRequiredDescription
typestring✅ YesField type: number, string, boolean
unitstring❌ NoUnit of measurement (e.g., celsius, percent)
descriptionstring❌ NoDescription of the field

Example Request - Temperature Sensor​

curl -X POST "https://api.dakkio.io/api/buckets/507f1f77bcf86cd799439011/sources" \
  -H "X-API-Key: dakkio_w_your_write_key..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Temperature Sensor",
    "type": "sensor",
    "description": "DHT22 temperature and humidity sensor",
    "schema": {
      "temperature": {
        "type": "number",
        "unit": "celsius",
        "description": "Temperature reading"
      },
      "humidity": {
        "type": "number",
        "unit": "percent",
        "description": "Relative humidity"
      }
    },
    "downsampling": true
  }'

Example Request - Application Metrics​

curl -X POST "https://api.dakkio.io/api/buckets/507f1f77bcf86cd799439011/sources" \
  -H "X-API-Key: dakkio_w_your_write_key..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Metrics",
    "type": "application",
    "description": "Backend API performance metrics",
    "schema": {
      "responseTime": {
        "type": "number",
        "unit": "milliseconds",
        "description": "API response time"
      },
      "requestCount": {
        "type": "number",
        "description": "Number of requests"
      },
      "errorRate": {
        "type": "number",
        "unit": "percent",
        "description": "Error rate percentage"
      },
      "endpoint": {
        "type": "string",
        "description": "API endpoint path"
      }
    }
  }'

Response​

Success Response (201 Created)​

{
  "message": "Data source created successfully",
  "dataSource": {
    "_id": "507f1f77bcf86cd799439015",
    "name": "Temperature Sensor",
    "type": "sensor",
    "description": "DHT22 temperature and humidity sensor",
    "bucketId": "507f1f77bcf86cd799439011",
    "schema": {
      "temperature": {
        "type": "number",
        "unit": "celsius",
        "description": "Temperature reading"
      },
      "humidity": {
        "type": "number",
        "unit": "percent",
        "description": "Relative humidity"
      }
    },
    "downsampling": true,
    "status": "active",
    "stats": {
      "totalDataPoints": 0
    },
    "createdAt": "2024-01-15T10:10:00Z"
  }
}

Error Responses​

400 Bad Request - Missing Schema​

{
  "error": "Validation Error",
  "message": "Schema is required"
}

400 Bad Request - Invalid Field Type​

{
  "error": "Validation Error",
  "message": "Invalid field type. Must be 'number', 'string', or 'boolean'"
}

401 Unauthorized​

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden​

{
  "error": "Forbidden",
  "message": "Read keys cannot create data sources"
}

409 Conflict - Duplicate Name​

{
  "error": "Conflict",
  "message": "A data source with this name already exists in this bucket"
}

Code Examples​

JavaScript/Node.js​

const axios = require('axios');

async function createDataSource(bucketId, name, type, schema, description) {
  const response = await axios.post(
    `https://api.dakkio.io/api/buckets/${bucketId}/sources`,
    { name, type, description, schema },
    {
      headers: {
        'X-API-Key': process.env.DAKKIO_WRITE_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  return response.data.dataSource;
}

// Create a temperature sensor data source
const dataSource = await createDataSource(
  '507f1f77bcf86cd799439011',
  'Temperature Sensor',
  'sensor',
  {
    temperature: {
      type: 'number',
      unit: 'celsius',
      description: 'Temperature reading'
    },
    humidity: {
      type: 'number',
      unit: 'percent',
      description: 'Relative humidity'
    }
  },
  'DHT22 temperature and humidity sensor'
);

console.log(`Created data source: ${dataSource._id}`);

Python​

import requests
import os

def create_data_source(bucket_id, name, source_type, schema, description=None):
    response = requests.post(
        f'https://api.dakkio.io/api/buckets/{bucket_id}/sources',
        headers={
            'X-API-Key': os.environ['DAKKIO_WRITE_KEY'],
            'Content-Type': 'application/json'
        },
        json={
            'name': name,
            'type': source_type,
            'description': description,
            'schema': schema
        }
    )

    if response.status_code == 201:
        return response.json()['dataSource']
    else:
        print('Error:', response.json())
        return None

# Create a temperature sensor data source
data_source = create_data_source(
    '507f1f77bcf86cd799439011',
    'Temperature Sensor',
    'sensor',
    {
        'temperature': {
            'type': 'number',
            'unit': 'celsius',
            'description': 'Temperature reading'
        },
        'humidity': {
            'type': 'number',
            'unit': 'percent',
            'description': 'Relative humidity'
        }
    },
    'DHT22 temperature and humidity sensor'
)

if data_source:
    print(f"Created data source: {data_source['_id']}")

Schema Examples​

Environmental Sensor​

{
  "temperature": { "type": "number", "unit": "celsius" },
  "humidity": { "type": "number", "unit": "percent" },
  "pressure": { "type": "number", "unit": "hPa" },
  "co2": { "type": "number", "unit": "ppm" }
}

Industrial Machine​

{
  "rpm": { "type": "number", "unit": "rpm" },
  "vibration": { "type": "number", "unit": "mm/s" },
  "oilLevel": { "type": "number", "unit": "percent" },
  "status": { "type": "string" },
  "isRunning": { "type": "boolean" }
}

Application Metrics​

{
  "responseTime": { "type": "number", "unit": "ms" },
  "requestCount": { "type": "number" },
  "errorRate": { "type": "number", "unit": "percent" },
  "memoryUsage": { "type": "number", "unit": "MB" },
  "cpuUsage": { "type": "number", "unit": "percent" }
}

GPS Tracker​

{
  "latitude": { "type": "number", "unit": "degrees" },
  "longitude": { "type": "number", "unit": "degrees" },
  "altitude": { "type": "number", "unit": "meters" },
  "speed": { "type": "number", "unit": "km/h" },
  "heading": { "type": "number", "unit": "degrees" }
}

Best Practices​

1. Use Descriptive Names​

// ✅ Good
"name": "Living Room Temperature Sensor"
"name": "Production Line A Motor"

// ❌ Bad
"name": "Sensor1"
"name": "Data"

2. Define Units​

Always include units for numeric values to avoid confusion:

// ✅ Good - clear units
"temperature": { "type": "number", "unit": "celsius" }

// ❌ Bad - ambiguous
"temperature": { "type": "number" }  // Celsius? Fahrenheit?

3. One Schema Per Sensor Type​

Create separate data sources for different sensor types:

// ✅ Good - separate data sources
await createDataSource(bucketId, 'Temperature Sensor', 'sensor', tempSchema);
await createDataSource(bucketId, 'Motion Sensor', 'sensor', motionSchema);

// ❌ Bad - mixing different sensor types
await createDataSource(bucketId, 'All Sensors', 'sensor', {
  temperature: { type: 'number' },
  motion: { type: 'boolean' }  // Different sensor type!
});