Data Buckets

For the base URL, authentication and errors, see the REST API overview.

`GET /v1/users/{user}/buckets`

Request: GET /v1/users/{user}/buckets
Operation: ListBuckets
Operation ID: Bucket_List
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes

Example request

bash

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/buckets' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

Response example (200)

json

[
  {
    "bucket": "api_write",
    "config": {
      "source": "api"
    },
    "created": 1792263090784,
    "description": "Bucket for API write",
    "enabled": true,
    "modified": 1792263090784,
    "name": "API Write"
  },
  {
    "bucket": "mqtt_bucket",
    "config": {
      "source": "mqtt",
      "topic": "house/+/temperature"
    },
    "created": 1792263090784,
    "description": "Bucket for MQTT topic",
    "enabled": true,
    "modified": 1792263090784,
    "name": "MQTT Bucket"
  },
  {
    "bucket": "device_bucket",
    "config": {
      "device": "macbook",
      "interval": 300,
      "resource": "data",
      "source": "device",
      "update": "interval"
    },
    "created": 1792263090784,
    "description": "Bucket for Thinger.io device",
    "enabled": true,
    "modified": 1792263090784,
    "name": "Device Bucket"
  },
  {
    "bucket": "device_write",
    "config": {
      "source": "write"
    },
    "created": 1792263090784,
    "description": "Bucket dor device write",
    "enabled": true,
    "modified": 1792263090784,
    "name": "Device Write"
  },
  {
    "backend": "influxdb",
    "bucket": "vibration",
    "config": {
      "device": "vibration_01",
      "interval": 10,
      "resource": "accel",
      "source": "device",
      "update": "interval"
    },
    "created": 1792263090784,
    "description": "Accelerometer read every 10 seconds",
    "enabled": true,
    "modified": 1792263090784,
    "name": "Vibration"
  },
  {
    "bucket": "meter_readings",
    "config": {
      "source": "write",
      "tags": [
        "device",
        "site"
      ]
    },
    "created": 1792263090784,
    "description": "Readings written by every meter, tagged by device and site",
    "enabled": true,
    "modified": 1792263090784,
    "name": "Meter readings"
  }
]

`POST /v1/users/{user}/buckets`

Request: POST /v1/users/{user}/buckets
Operation: CreateBucket
Operation ID: Bucket_Create
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes

Request body (application/json, required)

Field	Type	Required	Constraints	Description
`asset_group`	string	no	Pattern: `^[a-zA-Z0-9_-]{1,32}$`	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
`asset_type`	string	no	Pattern: `^[a-zA-Z0-9_-]{1,32}$`	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
`backend`	string	no	One of: ``, `mongodb`, `influxdb`, `dynamodb`	Specifies the database backend to use for storage, with an option for default (represented by an empty string), 'mongodb', or 'influxdb'.
`bucket`	string	yes	Pattern: `^[a-zA-Z0-9_-]{1,32}$`	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
`config`	object	yes		Configuration schema for a data bucket specifying how data is sourced and updated. This schema supports multiple source types including devices and MQTT topics, each with its own set of required properties.
`config`	object	no		Variant 1: Configuration for data sourced from a device. This requires specifying the device, user, resource, update interval, and optional tags.
`config.device`	string	yes	Pattern: `^[a-zA-Z0-9_-]{1,32}$`	Variant 1: The unique identifier for the device.
`config.interval`	number	yes		Variant 1: The time between updates, in seconds.
`config.resource`	string	yes	Maximum length: 255	Variant 1: The specific resource from the device being tracked.
`config.source`	string	yes	One of: `device`	Variant 1: Indicates the data source is a device.
`config.tags`	array of string	no	Maximum items: 5	Variant 1: A collection of tags for categorization, limited to 5.
`config.update`	string	yes	One of: `interval`	Variant 1: Specifies that the bucket is updated at regular intervals.
`config.user`	string	no	Pattern: `^[a-zA-Z0-9_-]{1,32}$`	Variant 1: The unique identifier for the user associated with this bucket.
`config`	object	no		Variant 2: Configuration for data sourced from a device with event-based or no updates. This variation does not require an interval.
`config.device`	string	yes	Pattern: `^[a-zA-Z0-9_-]{1,32}$`	Variant 2: The unique identifier for the device.
`config.resource`	string	yes	Maximum length: 255	Variant 2: The specific resource from the device being tracked.
`config.source`	string	yes	One of: `device`	Variant 2: Indicates the data source is a device.
`config.tags`	array of string	no	Maximum items: 5	Variant 2: A collection of tags for categorization, limited to 5.
`config.update`	string	yes	One of: `events`, `none`	Variant 2: Specifies how the bucket is updated: either by specific events or not updated automatically.
`config.user`	string	no	Pattern: `^[a-zA-Z0-9_-]{1,32}$`	Variant 2: The unique identifier for the user associated with this bucket.
`config`	object	no		Variant 3: Configuration for data sourced from an MQTT topic. This requires specifying the topic and allows optional tags.
`config.source`	string	yes	One of: `mqtt`	Variant 3: Indicates the data source is an MQTT topic.
`config.tags`	array of string	no	Maximum items: 5	Variant 3: A collection of tags for categorization, limited to 5.
`config.topic`	string	yes	Maximum length: 512	Variant 3: The MQTT topic from which data is sourced.
`config`	object	no		Variant 4: Configuration for data manually written or provided via an API. This variation only requires source specification and allows optional tags.
`config.source`	string	yes	One of: `write`, `api`	Variant 4: Indicates the data source is either manually written ('write') or sourced via an API ('api').
`config.tags`	array of string	no	Maximum items: 5	Variant 4: A collection of tags for categorization, limited to 5.
`description`	string	no	Maximum length: 255	A brief description of the resource, providing context or additional information, limited to 255 characters.
`enabled`	boolean	yes
`name`	string	yes	Maximum length: 255	The name of the resource, limited to 255 characters. It can include any character.
`product`	string	no	Pattern: `^[a-zA-Z0-9_-]{1,32}$`	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
`retention`	object	no		Configuration schema for data bucket retention policy.
`retention.period`	integer	no	Minimum: 0	The duration of the retention period. 0 for unlimited retention.
`retention.unit`	string	no	One of: `hours`, `days`, `weeks`, `months`, `years`	The unit of measurement for the retention period.

Example request: From API Call

bash

curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/buckets' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "bucket": "api_write",
  "config": {
    "source": "api"
  },
  "description": "Bucket for API write",
  "enabled": true,
  "name": "API Write"
}'

Example body: From MQTT Topic

json

{
  "bucket": "mqtt_bucket",
  "config": {
    "source": "mqtt",
    "topic": "house/+/temperature"
  },
  "description": "Bucket for MQTT topic",
  "enabled": true,
  "name": "MQTT Bucket"
}

Example body: From Thinger Device

json

{
  "bucket": "device_bucket",
  "config": {
    "device": "macbook",
    "interval": 300,
    "resource": "data",
    "source": "device",
    "update": "interval"
  },
  "description": "Bucket for Thinger.io device",
  "enabled": true,
  "name": "Device Bucket"
}

Example body: From Thinger Device Write

json

{
  "bucket": "device_write",
  "config": {
    "source": "write"
  },
  "description": "Bucket dor device write",
  "enabled": true,
  "name": "Device Write"
}

Example body: High rate on InfluxDB

json

{
  "backend": "influxdb",
  "bucket": "vibration",
  "config": {
    "device": "vibration_01",
    "interval": 10,
    "resource": "accel",
    "source": "device",
    "update": "interval"
  },
  "description": "Accelerometer read every 10 seconds",
  "enabled": true,
  "name": "Vibration",
  "retention": {
    "period": 30,
    "unit": "days"
  }
}

Example body: Tagged writes, kept 2 years

json

{
  "bucket": "meter_readings",
  "config": {
    "source": "write",
    "tags": [
      "device",
      "site"
    ]
  },
  "description": "Readings written by every meter, tagged by device and site",
  "enabled": true,
  "name": "Meter readings",
  "retention": {
    "period": 2,
    "unit": "years"
  }
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`GET /v1/users/{user}/buckets/{bucket}`

Request: GET /v1/users/{user}/buckets/
Operation: ReadBucketConfig
Operation ID: Bucket_ReadConfig
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`bucket`	path	string	yes

Example request

bash

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/buckets/YOUR_BUCKET' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

Response example (200, From API Call)

json

{
  "bucket": "api_write",
  "config": {
    "source": "api"
  },
  "created": 1792263090784,
  "description": "Bucket for API write",
  "enabled": true,
  "modified": 1792263090784,
  "name": "API Write"
}

Response example (200, From MQTT Topic)

json

{
  "bucket": "mqtt_bucket",
  "config": {
    "source": "mqtt",
    "topic": "house/+/temperature"
  },
  "created": 1792263090784,
  "description": "Bucket for MQTT topic",
  "enabled": true,
  "modified": 1792263090784,
  "name": "MQTT Bucket"
}

Response example (200, From Thinger Device)

json

{
  "bucket": "device_bucket",
  "config": {
    "device": "macbook",
    "interval": 300,
    "resource": "data",
    "source": "device",
    "update": "interval"
  },
  "created": 1792263090784,
  "description": "Bucket for Thinger.io device",
  "enabled": true,
  "modified": 1792263090784,
  "name": "Device Bucket"
}

Response example (200, From Thinger Device Write)

json

{
  "bucket": "device_write",
  "config": {
    "source": "write"
  },
  "created": 1792263090784,
  "description": "Bucket dor device write",
  "enabled": true,
  "modified": 1792263090784,
  "name": "Device Write"
}

Response example (200, High rate on InfluxDB)

json

{
  "backend": "influxdb",
  "bucket": "vibration",
  "config": {
    "device": "vibration_01",
    "interval": 10,
    "resource": "accel",
    "source": "device",
    "update": "interval"
  },
  "created": 1792263090784,
  "description": "Accelerometer read every 10 seconds",
  "enabled": true,
  "modified": 1792263090784,
  "name": "Vibration",
  "retention": {
    "period": 30,
    "unit": "days"
  }
}

Response example (200, Tagged writes, kept 2 years)

json

{
  "bucket": "meter_readings",
  "config": {
    "source": "write",
    "tags": [
      "device",
      "site"
    ]
  },
  "created": 1792263090784,
  "description": "Readings written by every meter, tagged by device and site",
  "enabled": true,
  "modified": 1792263090784,
  "name": "Meter readings",
  "retention": {
    "period": 2,
    "unit": "years"
  }
}

`PUT /v1/users/{user}/buckets/{bucket}`

Request: PUT /v1/users/{user}/buckets/
Operation: UpdateBucket
Operation ID: Bucket_Update
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`bucket`	path	string	yes

Request body (application/json, required)

Field	Type	Required	Constraints	Description
`asset_group`	string	no	Variant 1: Pattern: `^[a-zA-Z0-9_-]{1,32}$` Variant 2: Maximum length: 0	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
`asset_type`	string	no	Variant 1: Pattern: `^[a-zA-Z0-9_-]{1,32}$` Variant 2: Maximum length: 0	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
`backend`	string	no	One of: ``, `mongodb`, `influxdb`, `dynamodb`	Specifies the database backend to use for storage, with an option for default (represented by an empty string), 'mongodb', or 'influxdb'.
`config`	object	no		Configuration schema for a data bucket specifying how data is sourced and updated. This schema supports multiple source types including devices and MQTT topics, each with its own set of required properties.
`config`	object	no		Variant 1: Configuration for data sourced from a device. This requires specifying the device, user, resource, update interval, and optional tags.
`config.device`	string	yes	Pattern: `^[a-zA-Z0-9_-]{1,32}$`	Variant 1: The unique identifier for the device.
`config.interval`	number	yes		Variant 1: The time between updates, in seconds.
`config.resource`	string	yes	Maximum length: 255	Variant 1: The specific resource from the device being tracked.
`config.source`	string	yes	One of: `device`	Variant 1: Indicates the data source is a device.
`config.tags`	array of string	no	Maximum items: 5	Variant 1: A collection of tags for categorization, limited to 5.
`config.update`	string	yes	One of: `interval`	Variant 1: Specifies that the bucket is updated at regular intervals.
`config.user`	string	no	Pattern: `^[a-zA-Z0-9_-]{1,32}$`	Variant 1: The unique identifier for the user associated with this bucket.
`config`	object	no		Variant 2: Configuration for data sourced from a device with event-based or no updates. This variation does not require an interval.
`config.device`	string	yes	Pattern: `^[a-zA-Z0-9_-]{1,32}$`	Variant 2: The unique identifier for the device.
`config.resource`	string	yes	Maximum length: 255	Variant 2: The specific resource from the device being tracked.
`config.source`	string	yes	One of: `device`	Variant 2: Indicates the data source is a device.
`config.tags`	array of string	no	Maximum items: 5	Variant 2: A collection of tags for categorization, limited to 5.
`config.update`	string	yes	One of: `events`, `none`	Variant 2: Specifies how the bucket is updated: either by specific events or not updated automatically.
`config.user`	string	no	Pattern: `^[a-zA-Z0-9_-]{1,32}$`	Variant 2: The unique identifier for the user associated with this bucket.
`config`	object	no		Variant 3: Configuration for data sourced from an MQTT topic. This requires specifying the topic and allows optional tags.
`config.source`	string	yes	One of: `mqtt`	Variant 3: Indicates the data source is an MQTT topic.
`config.tags`	array of string	no	Maximum items: 5	Variant 3: A collection of tags for categorization, limited to 5.
`config.topic`	string	yes	Maximum length: 512	Variant 3: The MQTT topic from which data is sourced.
`config`	object	no		Variant 4: Configuration for data manually written or provided via an API. This variation only requires source specification and allows optional tags.
`config.source`	string	yes	One of: `write`, `api`	Variant 4: Indicates the data source is either manually written ('write') or sourced via an API ('api').
`config.tags`	array of string	no	Maximum items: 5	Variant 4: A collection of tags for categorization, limited to 5.
`description`	string	no	Maximum length: 255	A brief description of the resource, providing context or additional information, limited to 255 characters.
`enabled`	boolean	no
`name`	string	no	Maximum length: 255	The name of the resource, limited to 255 characters. It can include any character.
`product`	string	no	Variant 1: Pattern: `^[a-zA-Z0-9_-]{1,32}$` Variant 2: Maximum length: 0	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
`retention`	object	no		Configuration schema for data bucket retention policy.
`retention.period`	integer	no	Minimum: 0	The duration of the retention period. 0 for unlimited retention.
`retention.unit`	string	no	One of: `hours`, `days`, `weeks`, `months`, `years`	The unit of measurement for the retention period.

Example request: Full Update

bash

curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/buckets/YOUR_BUCKET' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "bucket": "api_write",
  "config": {
    "source": "api"
  },
  "description": "Bucket for API write",
  "enabled": true,
  "name": "API Write"
}'

Example body: Update 'config'

json

{
  "config": {
    "source": "api"
  }
}

Example body: Update 'description'

json

{
  "description": "Bucket for API write"
}

Example body: Update 'enabled'

json

{
  "enabled": true
}

Example body: Update 'name'

json

{
  "name": "API Write"
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`DELETE /v1/users/{user}/buckets/{bucket}`

Request: DELETE /v1/users/{user}/buckets/
Operation: DeleteBucket
Operation ID: Bucket_Delete
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`bucket`	path	string	yes

Example request

bash

curl -X DELETE 'https://YOUR_SERVER/v1/users/YOUR_USER/buckets/YOUR_BUCKET' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`GET /v1/users/{user}/buckets/{bucket}/clone`

Request: GET /v1/users/{user}/buckets/{bucket}/clone
Operation: CloneBucketConfig
Operation ID: Bucket_CloneConfig
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`bucket`	path	string	yes

Example request

bash

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/buckets/YOUR_BUCKET/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`POST /v1/users/{user}/buckets/{bucket}/clone`

Request: POST /v1/users/{user}/buckets/{bucket}/clone
Operation: CloneBucket
Operation ID: Bucket_Clone
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`bucket`	path	string	yes

Request body (application/json, required)

Field	Type	Required	Constraints	Description
`bucket`	string	yes	Pattern: `^[a-zA-Z0-9_-]{1,32}$`	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
`description`	string	no	Maximum length: 255	A brief description of the resource, providing context or additional information, limited to 255 characters.
`enabled`	boolean	no
`name`	string	no	Maximum length: 255	The name of the resource, limited to 255 characters. It can include any character.

Example request: Copy with a new id

bash

curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/buckets/YOUR_BUCKET/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "bucket": "copy_of_bucket"
}'

Example body: Copy with name and description

json

{
  "bucket": "line_2_bucket",
  "description": "Same configuration as the original, for production line 2",
  "name": "Line 2 copy"
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`POST /v1/users/{user}/buckets/{bucket}/data`

Request: POST /v1/users/{user}/buckets/{bucket}/data
Operation: WriteBucket
Operation ID: Bucket_WriteData
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`bucket`	path	string	yes

Request body (application/json, required)

The JSON object becomes one record. ?ts=<epoch ms> sets its timestamp (MongoDB buckets also take a numeric 'ts' field). Fields listed in the bucket tags are indexed for filtering. The bucket must be enabled.

Example request: One record

bash

curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/buckets/YOUR_BUCKET/data' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "device": "greenhouse_01",
  "humidity": 51,
  "temperature": 23.4
}'

Example body: With its own timestamp

json

{
  "energy": 1532.8,
  "power": 2.1,
  "ts": 1791650000000
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`GET /v1/users/{user}/buckets/{bucket}/exports`

Request: GET /v1/users/{user}/buckets/{bucket}/exports
Operation: ListBucketExports
Operation ID: Bucket_ListExports
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`bucket`	path	string	yes

Example request

bash

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/buckets/YOUR_BUCKET/exports' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`POST /v1/users/{user}/buckets/{bucket}/exports`

Request: POST /v1/users/{user}/buckets/{bucket}/exports
Operation: CreateBucketExport
Operation ID: Bucket_CreateExport
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`bucket`	path	string	yes

Request body (application/json, required)

Generates a file with the bucket data between min_ts and max_ts (epoch ms; all data when missing), listed in GET .../exports when ready. callback: notify by email to the owner or call an endpoint when it finishes.

Field	Type	Required	Constraints	Description
`callback`	string	no	One of: `email`, `endpoint`
`data_type`	string	no	One of: `csv`, `arff`, `json`
`endpoint`	string	no	Pattern: `^[a-zA-Z0-9_-]{1,32}$`	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
`max_ts`	number	no	Minimum: 0
`min_ts`	number	no	Minimum: 0
`timestamp_format`	string	no	One of: `iso`, `seconds`, `milliseconds`

Example request: Everything as JSON, call an endpoint

bash

curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/buckets/YOUR_BUCKET/exports' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "callback": "endpoint",
  "data_type": "json",
  "endpoint": "export_ready",
  "timestamp_format": "milliseconds"
}'

Example body: Last month as CSV, email when ready

json

{
  "callback": "email",
  "data_type": "csv",
  "max_ts": 1791590400000,
  "min_ts": 1788998400000,
  "timestamp_format": "iso"
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`GET /v1/users/{user}/buckets/{bucket}/exports/{file}`

Request: GET /v1/users/{user}/buckets/{bucket}/exports/
Operation: ReadBucketExport
Operation ID: Bucket_ReadExport
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required
`user`	path	string	yes
`bucket`	path	string	yes
`file`	path	string	yes

Example request

bash

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/buckets/YOUR_BUCKET/exports/YOUR_FILE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`DELETE /v1/users/{user}/buckets/{bucket}/exports/{file}`

Request: DELETE /v1/users/{user}/buckets/{bucket}/exports/
Operation: DeleteBucketExport
Operation ID: Bucket_DeleteExport
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required
`user`	path	string	yes
`bucket`	path	string	yes
`file`	path	string	yes

Example request

bash

curl -X DELETE 'https://YOUR_SERVER/v1/users/YOUR_USER/buckets/YOUR_BUCKET/exports/YOUR_FILE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`POST /v1/users/{user}/buckets/{bucket}/imports`

Request: POST /v1/users/{user}/buckets/{bucket}/imports
Operation: CreateBucketImport
Operation ID: Bucket_CreateImport
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`bucket`	path	string	yes

Request body (application/json, required)

Loads records into the bucket from a file already uploaded to a file storage (CSV with a header row, as produced by an export).

Field	Type	Required	Constraints	Description
`file`	string	yes
`source`	string	yes	One of: `storage`
`storage`	string	yes	Pattern: `^[a-zA-Z0-9_-]{1,32}$`	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.

Example request: CSV from a storage

bash

curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/buckets/YOUR_BUCKET/imports' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "file": "meter_readings_2025.csv",
  "source": "storage",
  "storage": "imports"
}'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`PUT /v1/users/{user}/buckets/{bucket}/projects`

Request: PUT /v1/users/{user}/buckets/{bucket}/projects
Operation: UpdateBucketProjects
Operation ID: Bucket_UpdateProjects
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`bucket`	path	string	yes

Request body (application/json, required)

Field	Type	Required	Constraints	Description
`(body)`	array of string	no		Projects the resource belongs to, as <owner>@<project> ids. Replaces the whole list: read the current one first to add or remove a single project; [] removes it from every project.

Example request: No projects

bash

curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/buckets/YOUR_BUCKET/projects' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[]'

Example body: One project

json

[
  "YOUR_USER@greenhouse"
]

Example body: Two projects

json

[
  "YOUR_USER@greenhouse",
  "YOUR_USER@maintenance"
]

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`GET /v1/users/{user}/buckets/{bucket}/tags`

Request: GET /v1/users/{user}/buckets/{bucket}/tags
Operation: ListBucketTags
Operation ID: Bucket_ListTags
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`bucket`	path	string	yes

Example request

bash

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/buckets/YOUR_BUCKET/tags' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`GET /v1/users/{user}/buckets/{bucket}/tags/{tag}`

Request: GET /v1/users/{user}/buckets/{bucket}/tags/
Operation: ReadBucketTag
Operation ID: Bucket_ReadTag
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required
`user`	path	string	yes
`bucket`	path	string	yes
`tag`	path	string	yes

Example request

bash

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/buckets/YOUR_BUCKET/tags/YOUR_TAG' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`GET /{version}/users/{user}/buckets/{bucket}/data`

Request: GET /{version}/users/{user}/buckets/{bucket}/data
Operation: ReadBucket
Operation ID: Bucket_ReadData
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required
`version`	path	string	yes
`user`	path	string	yes
`bucket`	path	string	yes

Example request

bash

curl 'https://YOUR_SERVER/YOUR_VERSION/users/YOUR_USER/buckets/YOUR_BUCKET/data' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

REST API

Arduino library

CLI

Dashboard SDK

VS Code extension

Data Buckets

`GET /v1/users/{user}/buckets`

`POST /v1/users/{user}/buckets`

`GET /v1/users/{user}/buckets/{bucket}`

`PUT /v1/users/{user}/buckets/{bucket}`

`DELETE /v1/users/{user}/buckets/{bucket}`

`GET /v1/users/{user}/buckets/{bucket}/clone`

`POST /v1/users/{user}/buckets/{bucket}/clone`

`POST /v1/users/{user}/buckets/{bucket}/data`

`GET /v1/users/{user}/buckets/{bucket}/exports`

`POST /v1/users/{user}/buckets/{bucket}/exports`

`GET /v1/users/{user}/buckets/{bucket}/exports/{file}`

`DELETE /v1/users/{user}/buckets/{bucket}/exports/{file}`

`POST /v1/users/{user}/buckets/{bucket}/imports`

`PUT /v1/users/{user}/buckets/{bucket}/projects`

`GET /v1/users/{user}/buckets/{bucket}/tags/{tag}`

`GET /{version}/users/{user}/buckets/{bucket}/data`

REST API

Arduino library

CLI

Dashboard SDK

VS Code extension

GET /v1/users/{user}/buckets ​

POST /v1/users/{user}/buckets ​

GET /v1/users/{user}/buckets/{bucket} ​

PUT /v1/users/{user}/buckets/{bucket} ​

DELETE /v1/users/{user}/buckets/{bucket} ​

GET /v1/users/{user}/buckets/{bucket}/clone ​

POST /v1/users/{user}/buckets/{bucket}/clone ​

POST /v1/users/{user}/buckets/{bucket}/data ​

GET /v1/users/{user}/buckets/{bucket}/exports ​

POST /v1/users/{user}/buckets/{bucket}/exports ​

GET /v1/users/{user}/buckets/{bucket}/exports/{file} ​

DELETE /v1/users/{user}/buckets/{bucket}/exports/{file} ​

POST /v1/users/{user}/buckets/{bucket}/imports ​

PUT /v1/users/{user}/buckets/{bucket}/projects ​

GET /v1/users/{user}/buckets/{bucket}/tags ​

GET /v1/users/{user}/buckets/{bucket}/tags/{tag} ​

GET /{version}/users/{user}/buckets/{bucket}/data ​

`GET /v1/users/{user}/buckets`

`POST /v1/users/{user}/buckets`

`GET /v1/users/{user}/buckets/{bucket}`

`PUT /v1/users/{user}/buckets/{bucket}`

`DELETE /v1/users/{user}/buckets/{bucket}`

`GET /v1/users/{user}/buckets/{bucket}/clone`

`POST /v1/users/{user}/buckets/{bucket}/clone`

`POST /v1/users/{user}/buckets/{bucket}/data`

`GET /v1/users/{user}/buckets/{bucket}/exports`

`POST /v1/users/{user}/buckets/{bucket}/exports`

`GET /v1/users/{user}/buckets/{bucket}/exports/{file}`

`DELETE /v1/users/{user}/buckets/{bucket}/exports/{file}`

`POST /v1/users/{user}/buckets/{bucket}/imports`

`PUT /v1/users/{user}/buckets/{bucket}/projects`

`GET /v1/users/{user}/buckets/{bucket}/tags`

`GET /v1/users/{user}/buckets/{bucket}/tags/{tag}`

`GET /{version}/users/{user}/buckets/{bucket}/data`