File Storages

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

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

Request: GET /v1/users/{user}/storages
Operation: ListStorages
Operation ID: Storage_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/storages' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

Response example (200)

json

[
  {
    "created": 1792263090742,
    "description": "Storages",
    "index": "index.html",
    "modified": 1792263090742,
    "name": "File Storage",
    "public": true,
    "storage": "file_storage"
  },
  {
    "created": 1792263090742,
    "description": "Manuals and reports; only readable with a token",
    "modified": 1792263090742,
    "name": "Documents",
    "public": false,
    "storage": "documents"
  }
]

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

Request: POST /v1/users/{user}/storages
Operation: CreateStorage
Operation ID: Storage_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
`description`	string	no	Maximum length: 255	A brief description of the resource, providing context or additional information, limited to 255 characters.
`index`	string	no	Maximum length: 255
`name`	string	yes	Maximum length: 255	The name of the resource, limited to 255 characters. It can include any character.
`public`	boolean	no
`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.
`terminal_image`	string	no	Maximum length: 255 Pattern: `^[a-zA-Z0-9][a-zA-Z0-9._/-]*:[a-zA-Z0-9._-]+$`

Example request: Create Storage

bash

curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/storages' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Storages",
  "index": "index.html",
  "name": "File Storage",
  "public": true,
  "storage": "file_storage"
}'

Example body: Private storage

json

{
  "description": "Manuals and reports; only readable with a token",
  "name": "Documents",
  "public": false,
  "storage": "documents"
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`GET /v1/users/{user}/storages/{storage}`

Request: GET /v1/users/{user}/storages/
Operation: ReadStorageConfig
Operation ID: Storage_ReadConfig
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

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

Example request

bash

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

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

Response example (200, Create Storage)

json

{
  "created": 1792263090742,
  "description": "Storages",
  "index": "index.html",
  "modified": 1792263090742,
  "name": "File Storage",
  "public": true,
  "storage": "file_storage"
}

Response example (200, Private storage)

json

{
  "created": 1792263090742,
  "description": "Manuals and reports; only readable with a token",
  "modified": 1792263090742,
  "name": "Documents",
  "public": false,
  "storage": "documents"
}

`PUT /v1/users/{user}/storages/{storage}`

Request: PUT /v1/users/{user}/storages/
Operation: UpdateStorage
Operation ID: Storage_Update
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

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

Request body (application/json, required)

Field	Type	Required	Constraints	Description
`description`	string	no	Maximum length: 255	A brief description of the resource, providing context or additional information, limited to 255 characters.
`index`	string	no	Maximum length: 255
`name`	string	no	Maximum length: 255	The name of the resource, limited to 255 characters. It can include any character.
`public`	boolean	no
`terminal_image`	string	no	Maximum length: 255 Pattern: `^[a-zA-Z0-9][a-zA-Z0-9._/-]*:[a-zA-Z0-9._-]+$`

Example request: Full Update

bash

curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/storages/YOUR_STORAGE' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Storages",
  "index": "index.html",
  "name": "File Storage",
  "public": true,
  "storage": "file_storage"
}'

Example body: Update 'description'

json

{
  "description": "Storages"
}

Example body: Update 'index'

json

{
  "index": "index.html"
}

Example body: Update 'name'

json

{
  "name": "File Storage"
}

Example body: Update 'public'

json

{
  "public": true
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`DELETE /v1/users/{user}/storages/{storage}`

Request: DELETE /v1/users/{user}/storages/
Operation: DeleteStorage
Operation ID: Storage_Delete
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

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

Example request

bash

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

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`GET /v1/users/{user}/storages/{storage}/clone`

Request: GET /v1/users/{user}/storages/{storage}/clone
Operation: CloneStorageConfig
Operation ID: Storage_CloneConfig
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

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

Example request

bash

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

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`POST /v1/users/{user}/storages/{storage}/clone`

Request: POST /v1/users/{user}/storages/{storage}/clone
Operation: CloneStorage
Operation ID: Storage_Clone
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

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

Request body (application/json, required)

Field	Type	Required	Constraints	Description
`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.
`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: Copy with a new id

bash

curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/storages/YOUR_STORAGE/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "storage": "copy_of_storage"
}'

Example body: Copy with name and description

json

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

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`GET /v1/users/{user}/storages/{storage}/files`

Request: GET /v1/users/{user}/storages/{storage}/files
Operation: ListStorageFiles
Operation ID: Storage_ListFiles
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

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

Example request

bash

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/storages/YOUR_STORAGE/files' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`GET /v1/users/{user}/storages/{storage}/files/{file}`

Request: GET /v1/users/{user}/storages/{storage}/files/
Operation: ReadStorageFiles
Operation ID: Storage_ReadFiles
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

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

Example request

bash

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/storages/YOUR_STORAGE/files/YOUR_FILE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`PUT /v1/users/{user}/storages/{storage}/files/{file}`

Request: PUT /v1/users/{user}/storages/{storage}/files/
Operation: UpdateStorageFiles
Operation ID: Storage_UpdateFiles
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Creates or overwrites the file with the raw request body (any content type); folders on the path are created. For large or binary files prefer PUT /v2/users/{user}/storages/{storage}/files/{path}, which streams the upload.

Parameters

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

Request body (application/json, required)

A JSON object.

Example request (skeleton generated from the schema: required fields only, neutral values)

bash

curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/storages/YOUR_STORAGE/files/YOUR_FILE' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`DELETE /v1/users/{user}/storages/{storage}/files/{file}`

Request: DELETE /v1/users/{user}/storages/{storage}/files/
Operation: DeleteStorageFiles
Operation ID: Storage_DeleteFiles
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

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

Example request

bash

curl -X DELETE 'https://YOUR_SERVER/v1/users/YOUR_USER/storages/YOUR_STORAGE/files/YOUR_FILE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`POST /v1/users/{user}/storages/{storage}/files{path}`

Request: POST /v1/users/{user}/storages/{storage}/files
Operation: CreateStorageFiles
Operation ID: Storage_CreateFiles.+)?)
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Uploads files into the folder of the path: multipart/form-data with one or more files, or JSON {"files": [names], "folders": [names]} to create empty files and folders.

Parameters

Name	In	Type	Required
`user`	path	string	yes
`storage`	path	string	yes
`path`	path	string	yes

Request body (application/json, required)

A JSON object.

Example request (skeleton generated from the schema: required fields only, neutral values)

bash

curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/storages/YOUR_STORAGE/filesYOUR_PATH' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`PATCH /v1/users/{user}/storages/{storage}/files{path}`

Request: PATCH /v1/users/{user}/storages/{storage}/files
Operation: RenameStorageFiles
Operation ID: Storage_RenameFiles.+)?)
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required
`user`	path	string	yes
`storage`	path	string	yes
`path`	path	string	yes

Request body (application/json, required)

Moves or renames the file or folder of the URL to 'path', inside the same storage.

Field	Type	Required	Constraints	Description
`path`	string	yes	Maximum length: 255

Example request: Move into a folder

bash

curl -X PATCH 'https://YOUR_SERVER/v1/users/YOUR_USER/storages/YOUR_STORAGE/filesYOUR_PATH' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "path": "archive/2025/report.csv"
}'

Example body: Rename a file

json

{
  "path": "docs/manual-v2.pdf"
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`PUT /v1/users/{user}/storages/{storage}/projects`

Request: PUT /v1/users/{user}/storages/{storage}/projects
Operation: UpdateStorageProjects
Operation ID: Storage_UpdateProjects
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
`user`	path	string	yes
`storage`	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/storages/YOUR_STORAGE/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 /v2/users/{user}/storages/{storage}/files{file}`

Request: GET /v2/users/{user}/storages/{storage}/files
Operation: ReadStorageFiles
Operation ID: Storage_ReadFilesFiles(?<file>.*$)
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

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

Example request

bash

curl 'https://YOUR_SERVER/v2/users/YOUR_USER/storages/YOUR_STORAGE/filesYOUR_FILE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`PUT /v2/users/{user}/storages/{storage}/files{file}`

Request: PUT /v2/users/{user}/storages/{storage}/files
Operation: UpdateStorageFiles
Operation ID: Storage_UpdateFilesFiles(?<file>.*$)
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Streams the raw request body (any content type, e.g. application/octet-stream) into the file; folders are created. A path ending in / creates a folder (empty body). ?overwrite=false fails if it exists.

Parameters

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

Request body (application/json, required)

A JSON object.

Example request (skeleton generated from the schema: required fields only, neutral values)

bash

curl -X PUT 'https://YOUR_SERVER/v2/users/YOUR_USER/storages/YOUR_STORAGE/filesYOUR_FILE' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`PATCH /v2/users/{user}/storages/{storage}/files{file}`

Request: PATCH /v2/users/{user}/storages/{storage}/files
Operation: RenameStorageFiles
Operation ID: Storage_RenameFilesFiles(?<file>.*$)
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

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

Request body (application/json, required)

Moves or renames the file or folder of the URL to 'path', inside the same storage.

Field	Type	Required	Constraints	Description
`path`	string	yes

Example request: Rename a file

bash

curl -X PATCH 'https://YOUR_SERVER/v2/users/YOUR_USER/storages/YOUR_STORAGE/filesYOUR_FILE' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "path": "/docs/manual-v2.pdf"
}'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`DELETE /v2/users/{user}/storages/{storage}/files{file}`

Request: DELETE /v2/users/{user}/storages/{storage}/files
Operation: DeleteStorageFiles
Operation ID: Storage_DeleteFilesFiles(?<file>.*$)
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

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

Example request

bash

curl -X DELETE 'https://YOUR_SERVER/v2/users/YOUR_USER/storages/YOUR_STORAGE/filesYOUR_FILE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

`GET /v2/users/{user}/storages/{storage}/terminal`

Request: GET /v2/users/{user}/storages/{storage}/terminal
Operation: AccessStorageTerminal
Operation ID: Storage_AccessTerminal
Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

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

Example request

bash

curl 'https://YOUR_SERVER/v2/users/YOUR_USER/storages/YOUR_STORAGE/terminal' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

REST API

Arduino library

CLI

Dashboard SDK

VS Code extension

File Storages

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

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

`GET /v1/users/{user}/storages/{storage}`

`PUT /v1/users/{user}/storages/{storage}`

`DELETE /v1/users/{user}/storages/{storage}`

`GET /v1/users/{user}/storages/{storage}/clone`

`POST /v1/users/{user}/storages/{storage}/clone`

`GET /v1/users/{user}/storages/{storage}/files`

`GET /v1/users/{user}/storages/{storage}/files/{file}`

`PUT /v1/users/{user}/storages/{storage}/files/{file}`

`DELETE /v1/users/{user}/storages/{storage}/files/{file}`

`POST /v1/users/{user}/storages/{storage}/files{path}`

`PATCH /v1/users/{user}/storages/{storage}/files{path}`

`PUT /v1/users/{user}/storages/{storage}/projects`

`GET /v2/users/{user}/storages/{storage}/files{file}`

`PUT /v2/users/{user}/storages/{storage}/files{file}`

`PATCH /v2/users/{user}/storages/{storage}/files{file}`

`DELETE /v2/users/{user}/storages/{storage}/files{file}`

`GET /v2/users/{user}/storages/{storage}/terminal`

REST API

Arduino library

CLI

Dashboard SDK

VS Code extension

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

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

GET /v1/users/{user}/storages/{storage} ​

PUT /v1/users/{user}/storages/{storage} ​

DELETE /v1/users/{user}/storages/{storage} ​

GET /v1/users/{user}/storages/{storage}/clone ​

POST /v1/users/{user}/storages/{storage}/clone ​

GET /v1/users/{user}/storages/{storage}/files ​

GET /v1/users/{user}/storages/{storage}/files/{file} ​

PUT /v1/users/{user}/storages/{storage}/files/{file} ​

DELETE /v1/users/{user}/storages/{storage}/files/{file} ​

POST /v1/users/{user}/storages/{storage}/files{path} ​

PATCH /v1/users/{user}/storages/{storage}/files{path} ​

PUT /v1/users/{user}/storages/{storage}/projects ​

GET /v2/users/{user}/storages/{storage}/files{file} ​

PUT /v2/users/{user}/storages/{storage}/files{file} ​

PATCH /v2/users/{user}/storages/{storage}/files{file} ​

DELETE /v2/users/{user}/storages/{storage}/files{file} ​

GET /v2/users/{user}/storages/{storage}/terminal ​

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

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

`GET /v1/users/{user}/storages/{storage}`

`PUT /v1/users/{user}/storages/{storage}`

`DELETE /v1/users/{user}/storages/{storage}`

`GET /v1/users/{user}/storages/{storage}/clone`

`POST /v1/users/{user}/storages/{storage}/clone`

`GET /v1/users/{user}/storages/{storage}/files`

`GET /v1/users/{user}/storages/{storage}/files/{file}`

`PUT /v1/users/{user}/storages/{storage}/files/{file}`

`DELETE /v1/users/{user}/storages/{storage}/files/{file}`

`POST /v1/users/{user}/storages/{storage}/files{path}`

`PATCH /v1/users/{user}/storages/{storage}/files{path}`

`PUT /v1/users/{user}/storages/{storage}/projects`

`GET /v2/users/{user}/storages/{storage}/files{file}`

`PUT /v2/users/{user}/storages/{storage}/files{file}`

`PATCH /v2/users/{user}/storages/{storage}/files{file}`

`DELETE /v2/users/{user}/storages/{storage}/files{file}`

`GET /v2/users/{user}/storages/{storage}/terminal`