Quick Start

Get started with dakkio in just a few minutes. This guide walks you through the complete flow from account creation to querying your data.

Prerequisites

• A modern web browser
• Basic knowledge of REST APIs
• cURL or any HTTP client (Postman, Insomnia, etc.)

Step 1: Create an Account

1. Visit app.dakkio.io
2. Click "Sign Up"
3. Enter your email, password, and name
4. Click "Create Account"

An organization will be automatically created for you with a Free plan.

Step 2: Get Your Admin API Key

You need an Admin API key to manage buckets and create other API keys.

1. Log into app.dakkio.io
2. Go to "API Keys" in the sidebar
3. Click "Create API Key"
4. Select Admin as the key type
5. Enter a label (e.g., "My Admin Key")
6. Click "Create"
7. Copy the key immediately - it won't be shown again!

Your admin key will look like: dakkio_a_xY7z8A9bC1dE2fG3hI4jK5lM6nO7pQ8r

Important

The full API key is only shown once. Store it securely!

Step 3: Create Your First Bucket

Buckets are containers for your time-series data. Use your Admin API key to create one.

curl -X POST https://api.dakkio.io/api/buckets \
  -H "X-API-Key: YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "IoT Sensors",
    "description": "Temperature and humidity sensors",
    "retentionDays": 365
  }'

Response:

{
  "bucket": {
    "_id": "507f1f77bcf86cd799439013",
    "name": "IoT Sensors",
    "description": "Temperature and humidity sensors",
    "retentionDays": 365,
    "status": "active",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Save the _id - you'll need it for the next steps!

Step 4: Create Bucket API Keys

For security, create bucket-specific keys instead of using your admin key for data operations.

Create a Write Key

Write keys can ingest data and manage data sources:

curl -X POST https://api.dakkio.io/api/buckets/507f1f77bcf86cd799439013/keys \
  -H "X-API-Key: YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "write",
    "label": "IoT Devices"
  }'

Response:

{
  "message": "Bucket API key created successfully",
  "apiKey": {
    "id": "507f1f77bcf86cd799439015",
    "type": "write",
    "bucketId": "507f1f77bcf86cd799439013",
    "bucketName": "IoT Sensors",
    "key": "dakkio_w_aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV",
    "keyPreview": "...T2uV",
    "permissions": ["data:read", "data:write", "notifications:read", "notifications:write"]
  },
  "warning": "Save this key now - you will not be able to see it again."
}

Create a Read Key

Read keys can only query data (use for dashboards and reporting):

curl -X POST https://api.dakkio.io/api/buckets/507f1f77bcf86cd799439013/keys \
  -H "X-API-Key: YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "read",
    "label": "Dashboard"
  }'

Response:

{
  "message": "Bucket API key created successfully",
  "apiKey": {
    "id": "507f1f77bcf86cd799439016",
    "type": "read",
    "bucketId": "507f1f77bcf86cd799439013",
    "bucketName": "IoT Sensors",
    "key": "dakkio_r_wX3yZ4aB5cD6eF7gH8iJ9kL0mN1oP2qR",
    "keyPreview": "...P2qR",
    "permissions": ["data:read", "notifications:read"]
  },
  "warning": "Save this key now - you will not be able to see it again."
}

Security Best Practice

Use bucket-specific keys for IoT devices and applications. If a key is compromised, only one bucket is affected.

Step 5: Create a Data Source

Data sources define the schema and type of data you'll be storing. Use your Write API key.

curl -X POST https://api.dakkio.io/api/buckets/507f1f77bcf86cd799439013/sources \
  -H "X-API-Key: YOUR_WRITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Temperature Sensor",
    "type": "sensor",
    "schema": {
      "temperature": { "type": "number", "unit": "°C" },
      "humidity": { "type": "number", "unit": "%" }
    },
    "metadata": {
      "location": "Living Room"
    }
  }'

Response:

{
  "dataSource": {
    "_id": "507f1f77bcf86cd799439014",
    "bucketId": "507f1f77bcf86cd799439013",
    "name": "Temperature Sensor",
    "type": "sensor",
    "schema": {
      "temperature": { "type": "number", "unit": "°C" },
      "humidity": { "type": "number", "unit": "%" }
    },
    "status": "active"
  }
}

Save the _id - you'll need it for data ingestion!

Step 6: Send Your First Data Point

Now you can start sending data using your Write API key!

Single Data Point

curl -X POST https://api.dakkio.io/api/data \
  -H "X-API-Key: YOUR_WRITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "507f1f77bcf86cd799439013",
    "dataSourceId": "507f1f77bcf86cd799439014",
    "timestamp": "2024-01-15T10:30:00Z",
    "values": {
      "temperature": 22.5,
      "humidity": 65
    },
    "metadata": {
      "deviceId": "ESP32-001"
    }
  }'

Response:

{
  "message": "Data point ingested successfully",
  "dataPoint": {
    "_id": "507f1f77bcf86cd799439017",
    "timestamp": "2024-01-15T10:30:00Z",
    "values": {
      "temperature": 22.5,
      "humidity": 65
    }
  }
}

Batch Data Points

For efficiency, send multiple data points at once:

curl -X POST https://api.dakkio.io/api/data/batch \
  -H "X-API-Key: YOUR_WRITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "507f1f77bcf86cd799439013",
    "dataPoints": [
      {
        "dataSourceId": "507f1f77bcf86cd799439014",
        "timestamp": "2024-01-15T10:30:00Z",
        "values": { "temperature": 22.5, "humidity": 65 }
      },
      {
        "dataSourceId": "507f1f77bcf86cd799439014",
        "timestamp": "2024-01-15T10:31:00Z",
        "values": { "temperature": 22.6, "humidity": 64 }
      },
      {
        "dataSourceId": "507f1f77bcf86cd799439014",
        "timestamp": "2024-01-15T10:32:00Z",
        "values": { "temperature": 22.7, "humidity": 63 }
      }
    ]
  }'

Response:

{
  "message": "Batch data ingested successfully",
  "insertedCount": 3
}

Step 7: Query Your Data

Retrieve your time-series data using your Read API key (or Write key):

curl -X POST https://api.dakkio.io/api/data/query \
  -H "X-API-Key: YOUR_READ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "507f1f77bcf86cd799439013",
    "filters": {
      "dataSourceIds": ["507f1f77bcf86cd799439014"],
      "startTime": "2024-01-15T10:00:00Z",
      "endTime": "2024-01-15T11:00:00Z",
      "fields": ["temperature", "humidity"]
    },
    "aggregation": "avg",
    "groupBy": "hour"
  }'

Response:

{
  "data": [
    {
      "timestamp": "2024-01-15T10:00:00Z",
      "temperature": 22.6,
      "humidity": 64
    }
  ],
  "metadata": {
    "count": 3,
    "aggregation": "avg",
    "groupBy": "hour"
  }
}

Step 8: Set Up an Alert

Create an alert to get notified when values exceed thresholds. Use your Write API key:

curl -X POST https://api.dakkio.io/api/alerts \
  -H "X-API-Key: YOUR_WRITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "507f1f77bcf86cd799439013",
    "dataSourceId": "507f1f77bcf86cd799439014",
    "name": "High Temperature Alert",
    "naturalLanguageQuery": "Temperature exceeds 30°C for 5 minutes",
    "cooldownMinutes": 15
  }'

Response:

{
  "alert": {
    "_id": "507f1f77bcf86cd799439018",
    "name": "High Temperature Alert",
    "status": "active",
    "createdAt": "2024-01-15T10:35:00Z"
  }
}

Summary

Congratulations! You've successfully:

Step	Action	API Key Used
1	Created an account	Dashboard
2	Got your Admin API key	Dashboard
3	Created a bucket	Admin
4	Created Write and Read keys	Admin
5	Created a data source	Write
6	Sent data points	Write
7	Queried your data	Read
8	Set up an alert	Write

Next Steps

Now you can:

1. Try the API Playground - Test all endpoints interactively
2. View Analytics - See aggregated statistics
3. Explore Code Examples - JavaScript, Python, Arduino examples

Troubleshooting

401 Unauthorized

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

• Verify your API key is correct
• Check the X-API-Key header is included
• Ensure the API key hasn't been deleted

403 Forbidden

{
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

• Check you're using the right key type for the operation
• Admin key for bucket/key management
• Write key for data ingestion and alerts
• Read key for queries

404 Not Found

{
  "error": "Not Found",
  "message": "Bucket not found"
}

• Verify the bucketId is correct
• For bucket-scoped keys, ensure the bucket matches the key's assigned bucket

Getting Help

• Full API Reference
• Authentication Guide
• API Playground