Filestore#

Filestore service provides file storage for things and groups. Files are stored on the local filesystem organised by thing or group ID, with metadata (name, content type, size) persisted to a PostgreSQL database. Both things and users can upload, retrieve, update, and delete files within their authorised scope.

Two scopes are supported:

• Thing-scoped files — authenticated with a Thing key (Authorization: Thing <key>). A thing can manage its own files and read group files.
• Group-scoped files — authenticated with a Bearer token. Users with appropriate group access can manage files shared across the group.

Thing-scoped files#

A thing authenticates using its key to upload and retrieve files scoped to itself.

# Upload a file
curl -s -S -i -X POST \
  -H "Authorization: Thing <thing_key>" \
  -F "file=@sensor-data.csv" \
  -F 'metadata={"type":"readings","sensor":"temperature"}' \
  https://localhost/filestore/files

{
  "name": "sensor-data.csv",
  "content_type": "text/csv",
  "size": 1024,
  "thing_id": "111e4567-e89b-12d3-a456-426614174000"
}

# List files
curl -s -S -i \
  -H "Authorization: Thing <thing_key>" \
  https://localhost/filestore/files

{
  "total": 2,
  "files": [
    {"name": "sensor-data.csv", "content_type": "text/csv", "size": 1024},
    {"name": "calibration.json", "content_type": "application/json", "size": 256}
  ]
}

# Download a file
curl -s -S -i \
  -H "Authorization: Thing <thing_key>" \
  https://localhost/filestore/files/<name>

# Update a file
curl -s -S -i -X PUT \
  -H "Authorization: Thing <thing_key>" \
  -F "file=@sensor-data-v2.csv" \
  https://localhost/filestore/files/<name>

# Delete a file
curl -s -S -i -X DELETE \
  -H "Authorization: Thing <thing_key>" \
  https://localhost/filestore/files/<name>

Group-scoped files#

Users with group access can manage files shared across the group using a Bearer token. Group files are accessible to all things and users within the group.

# Upload a group file
curl -s -S -i -X POST \
  -H "Authorization: Bearer <user_token>" \
  -F "file=@config.json" \
  https://localhost/filestore/groups/<group_id>/files

# List group files
curl -s -S -i \
  -H "Authorization: Bearer <user_token>" \
  https://localhost/filestore/groups/<group_id>/files

# Download a group file
curl -s -S -i \
  -H "Authorization: Bearer <user_token>" \
  https://localhost/filestore/groups/<group_id>/files/<name>

A thing can also retrieve a group file directly using its Thing key:

curl -s -S -i \
  -H "Authorization: Thing <thing_key>" \
  https://localhost/filestore/groupfiles/<name>

This is useful for things that need to fetch shared configuration or firmware files published by the group without requiring a user token.

For the full API reference, see the API documentation.