Skip to main content

Quick Start

Get started with dakkio in just a few minutes. This guide will walk you through creating an account, generating an API key, and sending your first data point.

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" in the top right
  3. Enter your email, password, and name
  4. Click "Create Account"

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

Using cURL​

curl -X POST https://api.dakkio.io/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "password": "securepassword123",
    "name": "Your Name"
  }'

Response:

{
  "user": {
    "_id": "507f1f77bcf86cd799439011",
    "email": "your@email.com",
    "name": "Your Name",
    "organizationId": "507f1f77bcf86cd799439012",
    "role": "owner",
    "status": "active"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Step 2: Create Your First Bucket​

Buckets are containers for your time-series data. Each bucket can hold multiple data sources.

Via Dashboard​

  1. Log into app.dakkio.io
  2. Navigate to "Buckets" in the sidebar
  3. Click "Create Bucket"
  4. Enter a name (e.g., "IoT Sensors")
  5. Set retention period (e.g., 365 days)
  6. Click "Create"

Using cURL​

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

Response:

{
  "bucket": {
    "_id": "507f1f77bcf86cd799439013",
    "organizationId": "507f1f77bcf86cd799439012",
    "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 data ingestion!

Step 3: Create a Data Source​

Data sources define the schema and type of data you'll be storing.

Via Dashboard​

  1. Go to your bucket's detail page
  2. Click "Data Sources" tab
  3. Click "Create Data Source"
  4. Enter name (e.g., "Temperature Sensor")
  5. Select type (e.g., "sensor")
  6. Click "Create"

Using cURL​

curl -X POST https://api.dakkio.io/api/datasources \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "507f1f77bcf86cd799439013",
    "name": "Temperature Sensor",
    "description": "Living room temperature sensor",
    "type": "sensor",
    "schema": {
      "temperature": "number",
      "humidity": "number"
    }
  }'

Response:

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

Step 4: Generate an API Key​

API keys are used to send data from your IoT devices and applications.

Via Dashboard​

  1. Go to "API Keys" in the sidebar
  2. Click "Generate API Key"
  3. Enter a label (e.g., "Production Sensors")
  4. Select permissions (data:read, data:write, bucket:read)
  5. Click "Generate"
  6. Copy the key immediately - it won't be shown again!

Using cURL​

curl -X POST https://api.dakkio.io/api/apikeys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Production Sensors",
    "permissions": ["data:read", "data:write", "bucket:read"]
  }'

Response:

{
  "apiKey": {
    "_id": "507f1f77bcf86cd799439015",
    "keyPreview": "dakkio_a1b2c3d4...",
    "label": "Production Sensors",
    "permissions": ["data:read", "data:write", "bucket:read"],
    "status": "active"
  },
  "key": "dakkio_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}
Important

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

Step 5: Send Your First Data Point​

Now you can start sending data using your API key!

Single Data Point​

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

Response:

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

Batch Data Points​

For efficiency, you can send multiple data points at once:

curl -X POST https://api.dakkio.io/api/data/batch \
  -H "X-API-Key: dakkio_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -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 6: Query Your Data​

Retrieve your time-series data with filters and aggregations:

curl -X POST https://api.dakkio.io/api/data/query \
  -H "X-API-Key: dakkio_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -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"]
    },
    "aggregation": "avg",
    "groupBy": "hour"
  }'

Response:

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

Next Steps​

Congratulations! You've successfully:

  • ✅ Created a dakkio account
  • ✅ Set up a bucket and data source
  • ✅ Generated an API key
  • ✅ Sent your first data point
  • ✅ Queried your data

Now you can:

  1. Set Up Alerts - Get notified when values exceed thresholds
  2. Configure Webhooks - Send events to external services
  3. Explore Examples - See real-world use cases
  4. Try the Playground - Test API calls interactively

Troubleshooting​

Invalid API Key​

{
  "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 revoked

Bucket Not Found​

{
  "error": "Not Found",
  "message": "Bucket not found"
}
  • Verify the bucketId is correct
  • Ensure the bucket belongs to your organization
  • Check the bucket status is "active"

Rate Limit Exceeded​

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}
  • You've exceeded your plan's API call limit
  • Upgrade your plan or wait for the next billing cycle
  • Use batch operations to reduce API calls

Getting Help​

Need assistance?