Skip to main content

List Buckets

Retrieve all buckets in your organization.

Endpoint​

GET /api/buckets

Authentication​

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

Required: Admin key (dakkio_a_). Only Admin keys can manage buckets at the organization level.

Why Admin key only?

Bucket management is an organization-level operation. Write and Read keys are scoped to specific buckets and cannot see or manage other buckets.

Request​

Headers​

HeaderTypeRequiredDescription
X-API-Keystring✅ YesYour Admin API key

Query Parameters​

ParameterTypeRequiredDescription
limitnumber❌ NoMax results (default: 100, max: 1000)
offsetnumber❌ NoSkip results for pagination

Example Request​

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

Example Request with Pagination​

curl -X GET "https://api.dakkio.io/api/buckets?limit=10&offset=0" \
  -H "X-API-Key: dakkio_a_your_admin_key..."

Response​

Success Response (200 OK)​

{
  "buckets": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Home Sensors",
      "description": "Temperature and humidity sensors for my home",
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    {
      "_id": "507f1f77bcf86cd799439022",
      "name": "Office Monitoring",
      "description": "Environmental monitoring for the office",
      "createdAt": "2024-01-12T14:00:00Z",
      "updatedAt": "2024-01-12T14:00:00Z"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 2,
    "hasMore": false
  }
}

Empty Response (200 OK)​

{
  "buckets": [],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 0,
    "hasMore": false
  }
}

Error Responses​

401 Unauthorized​

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

403 Forbidden​

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

Code Examples​

JavaScript/Node.js​

const axios = require('axios');

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

  return response.data.buckets;
}

// List all buckets
const buckets = await listBuckets();
console.log(`Found ${buckets.length} buckets`);
buckets.forEach(b => console.log(`- ${b.name} (${b._id})`));

Python​

import requests
import os

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

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

# List all buckets
buckets = list_buckets()
for bucket in buckets:
    print(f"- {bucket['name']} ({bucket['_id']})")

cURL with Pagination​

# Get first page
curl -X GET "https://api.dakkio.io/api/buckets?limit=10&offset=0" \
  -H "X-API-Key: $DAKKIO_ADMIN_KEY"

# Get second page
curl -X GET "https://api.dakkio.io/api/buckets?limit=10&offset=10" \
  -H "X-API-Key: $DAKKIO_ADMIN_KEY"