Skip to main content

Delete Bucket

Permanently delete a bucket and all its data.

Endpoint​

DELETE /api/buckets/:id

Authentication​

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

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

Destructive Action

Deleting a bucket will permanently remove:

  • All data sources in the bucket
  • All time-series data points
  • All API keys scoped to the bucket
  • All alert rules for the bucket

This action cannot be undone.

Request​

Headers​

HeaderTypeRequiredDescription
X-API-Keystring✅ YesYour Admin API key

Path Parameters​

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

Example Request​

curl -X DELETE "https://api.dakkio.io/api/buckets/507f1f77bcf86cd799439011" \
  -H "X-API-Key: dakkio_a_your_admin_key..."

Response​

Success Response (200 OK)​

{
  "message": "Bucket deleted successfully",
  "deletedBucket": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Home Sensors"
  },
  "deletedResources": {
    "dataSources": 3,
    "dataPoints": 15420,
    "apiKeys": 2,
    "alertRules": 1
  }
}

Error Responses​

400 Bad Request - Invalid ID​

{
  "error": "Validation Error",
  "message": "Invalid bucket ID format"
}

401 Unauthorized​

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

403 Forbidden​

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

404 Not Found​

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

Code Examples​

JavaScript/Node.js​

const axios = require('axios');

async function deleteBucket(bucketId) {
  const response = await axios.delete(
    `https://api.dakkio.io/api/buckets/${bucketId}`,
    {
      headers: {
        'X-API-Key': process.env.DAKKIO_ADMIN_KEY
      }
    }
  );

  return response.data;
}

// Delete a bucket (with confirmation)
const bucketId = '507f1f77bcf86cd799439011';

// First, get bucket details to confirm
const bucket = await getBucket(bucketId);
console.log(`About to delete: ${bucket.name}`);
console.log(`This will remove ${bucket.stats.dataPointCount} data points`);

// Confirm before deleting
if (confirm) {
  const result = await deleteBucket(bucketId);
  console.log('Deleted:', result.deletedResources);
}

Python​

import requests
import os

def delete_bucket(bucket_id):
    response = requests.delete(
        f'https://api.dakkio.io/api/buckets/{bucket_id}',
        headers={
            'X-API-Key': os.environ['DAKKIO_ADMIN_KEY']
        }
    )

    if response.status_code == 200:
        return response.json()
    else:
        print('Error:', response.json())
        return None

# Delete a bucket
bucket_id = '507f1f77bcf86cd799439011'
result = delete_bucket(bucket_id)

if result:
    print(f"Deleted bucket: {result['deletedBucket']['name']}")
    print(f"Removed {result['deletedResources']['dataPoints']} data points")

Best Practices​

1. Export Data First​

Before deleting, consider exporting your data:

// Export data before deletion
const data = await queryData(bucketId, {
  startTime: '2020-01-01T00:00:00Z',
  endTime: new Date().toISOString(),
  limit: 10000
});

// Save to file
fs.writeFileSync('backup.json', JSON.stringify(data));

// Then delete
await deleteBucket(bucketId);

2. Verify Bucket ID​

Always double-check you're deleting the correct bucket:

const bucket = await getBucket(bucketId);
console.log(`Deleting: ${bucket.name}`);
console.log(`Contains: ${bucket.stats.dataPointCount} data points`);

// Require explicit confirmation
const readline = require('readline');
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });

rl.question('Type the bucket name to confirm deletion: ', async (answer) => {
  if (answer === bucket.name) {
    await deleteBucket(bucketId);
    console.log('Bucket deleted');
  } else {
    console.log('Deletion cancelled');
  }
  rl.close();
});

3. Revoke API Keys After Deletion​

Any Write or Read keys for the deleted bucket will no longer work, but you should update your applications to remove the stale keys.