Get Bucket

Retrieve details of a specific bucket.

Endpoint

GET /api/buckets/:id

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 retrieve bucket details.

Request

Headers

Header	Type	Required	Description
X-API-Key	string	✅ Yes	Your Admin API key

Path Parameters

Parameter	Type	Required	Description
id	string	✅ Yes	The bucket ID (24-character hex string)

Example Request

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

Response

Success Response (200 OK)

{
  "bucket": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Home Sensors",
    "description": "Temperature and humidity sensors for my home",
    "organizationId": "507f1f77bcf86cd799439000",
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "stats": {
      "dataSourceCount": 3,
      "dataPointCount": 15420,
      "apiKeyCount": 2
    }
  }
}

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 access bucket details"
}

404 Not Found

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

Code Examples

JavaScript/Node.js

const axios = require('axios');

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

  return response.data.bucket;
}

// Get bucket details
const bucket = await getBucket('507f1f77bcf86cd799439011');
console.log(`Bucket: ${bucket.name}`);
console.log(`Data points: ${bucket.stats.dataPointCount}`);

Python

import requests
import os

def get_bucket(bucket_id):
    response = requests.get(
        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()['bucket']
    else:
        print('Error:', response.json())
        return None

# Get bucket details
bucket = get_bucket('507f1f77bcf86cd799439011')
if bucket:
    print(f"Bucket: {bucket['name']}")
    print(f"Data points: {bucket['stats']['dataPointCount']}")

Response Fields

Field	Type	Description
_id	string	Unique bucket identifier
name	string	Bucket name
description	string	Bucket description
organizationId	string	Organization that owns the bucket
createdAt	string	Creation timestamp (ISO 8601)
updatedAt	string	Last update timestamp (ISO 8601)
stats.dataSourceCount	number	Number of data sources in bucket
stats.dataPointCount	number	Total data points stored
stats.apiKeyCount	number	Number of API keys for this bucket

Related Endpoints

• List Buckets - List all buckets
• Create Bucket - Create a new bucket
• Delete Bucket - Delete a bucket