Create Bucket

Create a new bucket to organize your time-series data.

Endpoint

POST /api/buckets

Authentication

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

Required: Admin key (dakkio_a_). Only Admin keys can create buckets.

What is a bucket?

A bucket is a container for your time-series data. Think of it as a project or application:

• Home Sensors - Temperature, humidity from your smart home
• Factory Floor - Industrial equipment monitoring
• Weather Station - Environmental data collection

Each bucket has its own data sources, API keys, and retention policy.

Request

Headers

Header	Type	Required	Description
X-API-Key	string	✅ Yes	Your Admin API key
Content-Type	string	✅ Yes	Must be application/json

Body Parameters

Parameter	Type	Required	Description
name	string	✅ Yes	Bucket name (1-100 characters)
description	string	❌ No	Description of the bucket

Example Request

curl -X POST "https://api.dakkio.io/api/buckets" \
  -H "X-API-Key: dakkio_a_your_admin_key..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Home Sensors",
    "description": "Temperature and humidity sensors for my home"
  }'

Response

Success Response (201 Created)

{
  "message": "Bucket created successfully",
  "bucket": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Home Sensors",
    "description": "Temperature and humidity sensors for my home",
    "organizationId": "507f1f77bcf86cd799439000",
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:00:00Z"
  }
}

Error Responses

400 Bad Request - Validation Error

{
  "error": "Validation Error",
  "message": "Invalid request parameters",
  "details": [
    {
      "path": ["body", "name"],
      "message": "String must contain at least 1 character(s)"
    }
  ]
}

400 Bad Request - Name Too Long

{
  "error": "Validation Error",
  "message": "Bucket name must be 100 characters or less"
}

401 Unauthorized

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

403 Forbidden

{
  "error": "Forbidden",
  "message": "Only Admin keys can create buckets"
}

409 Conflict - Duplicate Name

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

Code Examples

JavaScript/Node.js

const axios = require('axios');

async function createBucket(name, description) {
  const response = await axios.post(
    'https://api.dakkio.io/api/buckets',
    { name, description },
    {
      headers: {
        'X-API-Key': process.env.DAKKIO_ADMIN_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  return response.data.bucket;
}

// Create a new bucket
const bucket = await createBucket(
  'Home Sensors',
  'Temperature and humidity sensors for my home'
);

console.log(`Created bucket: ${bucket._id}`);

Python

import requests
import os

def create_bucket(name, description=None):
    response = requests.post(
        'https://api.dakkio.io/api/buckets',
        headers={
            'X-API-Key': os.environ['DAKKIO_ADMIN_KEY'],
            'Content-Type': 'application/json'
        },
        json={
            'name': name,
            'description': description
        }
    )

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

# Create a new bucket
bucket = create_bucket(
    'Home Sensors',
    'Temperature and humidity sensors for my home'
)

if bucket:
    print(f"Created bucket: {bucket['_id']}")

Next Steps

After creating a bucket, you'll typically:

1. Create API keys for the bucket

   • Create Write key for data ingestion
   • Create Read key for queries

2. Create a data source to define your data schema

   • Create Data Source

3. Start sending data

   • Ingest Data

Related Endpoints

• List Buckets - List all buckets
• Get Bucket - Get bucket details
• Delete Bucket - Delete a bucket
• Create API Key - Create bucket API keys