Skip to main content

Resources

Shared files and assets available across the platform.

What is a Resource?​

A Resource is a shared file or document available across the Beacon Tower platform. Resources enable you to store and manage reusable assets such as themes, logos, configuration files, firmware binaries, documentation, and images.

Each resource has:

  • displayName — Human-readable name
  • description — Optional description of the resource
  • tags — Key-value pairs for categorization and filtering
  • document — JSON data (for JSON-based resources)
  • file — Binary file content (for file-based resources)
  • metadata — Additional system-generated metadata
  • history — Audit trail of changes

All resources have a resource type of user-resource, distinguishing them from system-managed resources.

Common Use Cases​

  • Themes — Custom branding and styling configurations
  • Logos — Company logos and icons referenced by themes
  • Configuration files — Reusable settings for devices or flows
  • Firmware binaries — Device firmware files for OTA updates
  • Documentation — User guides, PDFs, or reference materials
  • Images — Photos, diagrams, or other visual assets

Resources are shared across organizations via the standard permission system, making them available to authorized users and services throughout the platform.

Resource Types and Tags​

Resources use tag-based categorization to drive editor selection and filtering in the web UI. Tags are key-value pairs that provide flexible metadata for organizing and discovering resources.

Common Tag Categories​

Tags determine which editor opens in the web UI when editing a resource:

  • theme — Theme configuration files (opens theme editor)
  • logo — Logo images and icons (opens image viewer)
  • config — Configuration files (opens config editor)
  • json — JSON documents (opens JSON editor)
  • blob — Binary files (firmware, PDFs, etc.)
  • document — Text documents and PDFs
  • image — Image files (PNG, JPG, SVG)

Tag Filtering​

The API supports filtering resources by tags using logical operators:

  • AND operator (&) — Resources must match all specified tags
  • OR operator (|) — Resources must match at least one specified tag

Managing Tags​

Retrieve available tags:

GET /resources/tags

Update tags for a resource:

PUT /resources/{resourceId}/tags

Tags determine which editor is used in the web UI. For example, resources tagged with theme open in the theme editor, while those tagged with json open in a JSON editor.

Uploading Resources​

Resources can be created in two ways: uploading binary files or creating JSON documents.

Upload Binary File​

Use multipart form data to upload a file as a resource:

curl -X POST https://api.beacontower.ai/resources/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@/path/to/firmware.bin" \
  -F "displayName=Firmware v2.1.0" \
  -F "description=Production firmware release" \
  -F "tags={\"type\":\"firmware\",\"version\":\"2.1.0\"}"

Re-upload File​

Update an existing resource with a new file:

curl -X PUT https://api.beacontower.ai/resources/upload/{resourceId} \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@/path/to/firmware-v2.1.1.bin"

Create JSON Resource​

Create a resource with JSON data:

curl -X POST https://api.beacontower.ai/resources \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Device Configuration Template",
    "description": "Default configuration for temperature sensors",
    "tags": {
      "type": "config",
      "device": "temperature-sensor"
    },
    "document": {
      "samplingRate": 60,
      "units": "celsius",
      "threshold": {
        "min": -20,
        "max": 80
      }
    }
  }'

Binary files are limited by the platform's upload size limits. Check the API response for specific constraints.

Managing Resources​

List Resources​

Retrieve all resources with optional filtering:

# List all user resources
curl -X GET "https://api.beacontower.ai/resources?resource_type=user-resource" \
  -H "X-API-Key: YOUR_API_KEY"

# Filter by single tag (firmware resources)
curl -X GET "https://api.beacontower.ai/resources?tag=type:firmware" \
  -H "X-API-Key: YOUR_API_KEY"

# Filter with AND operator (firmware AND version 2.1.0)
curl -X GET "https://api.beacontower.ai/resources?tag=type:firmware&tag=version:2.1.0" \
  -H "X-API-Key: YOUR_API_KEY"

# Filter with OR operator (theme OR logo resources)
curl -X GET "https://api.beacontower.ai/resources?tag=type:theme|type:logo" \
  -H "X-API-Key: YOUR_API_KEY"

Get Resource Details​

Retrieve a specific resource's metadata:

GET /resources/{resourceId}

Update Resource​

Update displayName, description, tags, or document content:

curl -X PATCH https://api.beacontower.ai/resources/{resourceId} \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Updated Firmware v2.1.1",
    "tags": {
      "type": "firmware",
      "version": "2.1.1",
      "status": "stable"
    }
  }'

Delete Resource​

Remove a resource from the platform:

DELETE /resources/{resourceId}

Deleting a resource that is referenced by themes, firmware releases, or other platform objects may break those dependencies. Ensure resources are no longer in use before deletion.

Downloading Resources​

Download the binary file content of a resource:

curl -X GET https://api.beacontower.ai/resources/download/{resourceId} \
  -H "X-API-Key: YOUR_API_KEY" \
  -o downloaded-file.bin

The response includes the file content with appropriate Content-Type and Content-Disposition headers.

Using Resources​

Resources are referenced throughout the platform by their resource ID:

Themes​

Themes reference resource IDs for logos and other visual assets. When creating or updating a theme, specify the resource ID for logo images:

{
  "logo": "resource-id-123",
  "favicon": "resource-id-456"
}

Firmware Releases​

Firmware releases reference resource IDs for binary files. Upload a firmware file as a resource, then reference its ID when creating a firmware release.

Flows and Dashboards​

Resources can be referenced in flow configurations or dashboard widgets to provide reusable data, templates, or assets.

Permissions​

Resources inherit the standard Beacon Tower permission system. Access to resources is controlled by organization membership and role assignments. A resource shared within an organization is available to all authorized users and services in that organization.

Next Steps​

  • Explore Themes for branding customization
  • Review the full API Reference for detailed endpoint documentation
  • Learn about permissions and access control in the platform documentation