25 Storage
9 operations.
25.0.1 createStorageContainer
POST /api/storage/create-container
Creates a new container in the customer’s storage account for a dataset that needs somewhere to put its files.
Why it exists. † Create a container in the customer’s storage account for a dataset that needs somewhere to put its files.
Creates a new container in the dataset’s own storage account (Azure Blob today; SharePoint-backed datasets are refused with 400). The account and credentials come from the dataset row, read under RLS — a dataset outside the caller’s scope is a 404, and the caller never supplies a credential of their own.
Authentication: SupabaseAuth
Returns — success · message · containerName
Field names as the handler returns them; the source states no types for them.
Effect — reads datasets
Request body
| Field | Type | Required |
|---|---|---|
datasetId |
string | yes |
containerName |
string | yes |
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
Container created. | |
400 |
datasetId and containerName are required, or the dataset’s storage configuration is invalid. | Error |
401 |
Not authenticated. | Error |
404 |
Dataset not found. | Error |
500 |
Server error. | Error |
25.0.2 deleteStorageObject
POST /api/storage/delete
Deletes one file from a customer’s storage container.
Why it exists. † Delete one file from a customer’s storage container.
Deletes a blob from the dataset’s own storage container. The account and credentials come from the dataset row, read under RLS — a dataset outside the caller’s scope is a 404.
Authentication: SupabaseAuth
Returns — success · message · blobName · containerName
Field names as the handler returns them; the source states no types for them.
Effect — reads datasets
Request body
| Field | Type | Required |
|---|---|---|
datasetId |
string | yes |
containerName |
string | yes |
blobName |
string | yes |
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
Deleted. | |
400 |
datasetId, containerName, and blobName are required, or the dataset’s storage configuration is invalid. | Error |
401 |
Not authenticated. | Error |
404 |
Dataset not found. | Error |
500 |
Server error. | Error |
25.0.3 downloadStorageFile
POST /api/storage/download
Streams one file out of a customer’s storage container to a caller entitled to the dataset it belongs to.
Why it exists. † Stream one file out of a customer’s storage container to a caller who is entitled to the dataset it belongs to.
Downloads a blob (or, with headerOnly, just its first part) from the dataset’s own storage container. The account and credentials come from the dataset row, read under RLS — a dataset outside the caller’s scope is a 404.
Authentication: SupabaseAuth
Returns — not readable from the source: the handler returns a value assembled at run time rather than a literal.
Effect — reads datasets
Request body
| Field | Type | Required |
|---|---|---|
datasetId |
string | yes |
containerName |
string | yes |
blobName |
string | yes |
headerOnly |
boolean | no |
headerSize |
integer | no |
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
The file’s bytes. | |
400 |
datasetId, containerName, and blobName are required, or the dataset’s storage configuration is invalid. | Error |
401 |
Not authenticated. | Error |
404 |
Dataset not found. | Error |
500 |
Server error. | Error |
25.0.4 listStorageFiles
POST /api/storage/list-files
Lists one page of the files in a customer’s storage container.
Why it exists. List the files in a customer’s storage container, so the interface can browse the source of a dataset without the platform holding a copy.
Called by — components/workspaces/storage-client.tsx
Reached from — /w/data-explorer/storage · /w/integrity/storage
Lists one page of files in the dataset’s own storage container, optionally filtering to images/videos only. Pass the previous response’s nextContinuationToken back in to resume; null means there are no more. Only azure and sharepoint datasets are implemented (others get a labeled 501, not a raw 500).
Authentication: SupabaseAuth
Returns — success · containers · message · files · containerName · totalFiles · imagesOnly · nextContinuationToken
Field names as the handler returns them; the source states no types for them.
Effect — reads datasets
Request body
| Field | Type | Required |
|---|---|---|
datasetId |
string | yes |
containerName |
string | no |
imagesOnly |
boolean | no |
continuationToken |
string, nullable | no |
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
One page of files, or the account’s containers when none was specified and more than one exists. | |
400 |
datasetId is required, imagesOnly must be a boolean, or the dataset’s storage configuration is invalid. | Error |
401 |
Not authenticated. | Error |
404 |
Dataset not found. | Error |
500 |
Server error. | Error |
501 |
The dataset’s storage provider is not implemented (only azure and sharepoint are). | Error |
25.0.5 getStorageFileMetadata
POST /api/storage/metadata
Reads one stored file’s size, type and last-modified time, without transferring the file.
Why it exists. † Read one stored file’s size, type and last-modified time, without transferring the file.
Reads a blob’s metadata from the dataset’s own storage container. The account and credentials come from the dataset row, read under RLS — a dataset outside the caller’s scope is a 404.
Authentication: SupabaseAuth
Returns — success · metadata · blobName · containerName
Field names as the handler returns them; the source states no types for them.
Effect — reads datasets
Request body
| Field | Type | Required |
|---|---|---|
datasetId |
string | yes |
containerName |
string | yes |
blobName |
string | yes |
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
The file’s metadata. | |
400 |
datasetId, containerName, and blobName are required, or the dataset’s storage configuration is invalid. | Error |
401 |
Not authenticated. | Error |
404 |
Dataset not found. | Error |
500 |
Server error. | Error |
25.0.6 listReferenceFiles
GET /api/storage/reference-files
Lists one folder level of a dataset’s linked Google Cloud Storage reference bucket, if it has one.
Why it exists. List one folder level of the Google Cloud Storage bucket a dataset’s CAD model was uploaded from, so reference material the platform did not otherwise surface — property tables, drawings, standards conversions — has one place to be browsed from, for the one dataset it’s linked to today.
Called by — components/workspaces/storage-client.tsx
Reached from — /w/data-explorer/storage · /w/integrity/storage
A dataset’s CAD model can carry a gs:// storage_path recording which Google Cloud Storage bucket it was uploaded from — that bucket often holds far more than the model itself (property tables, drawings, standards conversions). GCS has no real folders, only ‘/’-delimited name prefixes, so this lists one level (direct subfolders and files under prefix) rather than the whole bucket flattened. Reports hasReferenceBucket: false when the dataset has none linked.
Authentication: SupabaseAuth
Returns — hasReferenceBucket · configured · bucket · details · prefix · folders · files · nextContinuationToken
Field names as the handler returns them; the source states no types for them.
Effect — reads datasets
Parameters
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
datasetId |
query | yes | string | |
prefix |
query | no | string | |
pageSize |
query | no | integer | |
pageToken |
query | no | string |
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
The bucket’s link status, and one folder level’s contents if linked and reachable. | |
400 |
datasetId is required. | Error |
401 |
Not authenticated. | Error |
404 |
Dataset not found. | Error |
500 |
Server error. | Error |
501 |
The bucket is linked but this identity is not yet granted to read it. | Error |
25.0.7 getReferenceFileContent
GET /api/storage/reference-files/content
Reads one text, markdown, PDF or image file’s content from a dataset’s linked Google Cloud Storage reference bucket.
Why it exists. Read one file’s content from a dataset’s linked Google Cloud Storage reference bucket, capped and text-only, so a wiki page or a property table can be read in place rather than only listed.
Reads one file for inline preview. Text/markdown come back as JSON ({content, truncated}, capped at 512KB — truncated, not refused, past that). PDFs and images stream back as their own bytes with the real Content-Type. Restricted to a fixed allowlist of previewable extensions; anything else is refused with 415, checked server-side so a hand-built request cannot pull a mesh file or the CAD model through this route.
Authentication: SupabaseAuth
Returns — details · content · truncated
Field names as the handler returns them; the source states no types for them.
Effect — reads datasets
Parameters
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
datasetId |
query | yes | string | |
path |
query | yes | string |
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
The file’s content — JSON for text/markdown, raw bytes (with the real Content-Type) for PDFs/images. | |
400 |
datasetId and path are required. | Error |
401 |
Not authenticated. | Error |
404 |
Dataset not found, or no reference bucket linked. | Error |
415 |
This file type cannot be previewed. | Error |
500 |
Server error. | Error |
501 |
The bucket is linked but this identity is not yet granted to read it. | Error |
25.0.8 createStorageUploadUrl
POST /api/storage/upload-url
Mints a short-lived link that lets the browser upload a file straight into the customer’s container.
Why it exists. † Mint a short-lived URL that lets the browser upload a file straight into the customer’s container, so image data never passes through the platform.
Generates a short-lived Azure SAS URL for uploading a file into the dataset’s own storage container, so the file’s bytes never pass through the platform. The account and credentials come from the dataset row, read under RLS — a dataset outside the caller’s scope is a 404.
Authentication: SupabaseAuth
Returns — success · sasUrl · blobName · containerName · expiryMinutes
Field names as the handler returns them; the source states no types for them.
Effect — reads datasets
Request body
| Field | Type | Required |
|---|---|---|
datasetId |
string | yes |
containerName |
string | yes |
blobName |
string | yes |
contentType |
string | yes |
expiryMinutes |
number | no |
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
Upload URL generated. | |
400 |
datasetId, containerName, blobName, and contentType are required, expiryMinutes must be a positive number, or the dataset’s storage configuration is invalid. | Error |
401 |
Not authenticated. | Error |
404 |
Dataset not found. | Error |
500 |
Server error. | Error |
25.0.9 validateAzureStorage
POST /api/storage/validate-azure
Checks that a set of Azure storage credentials work, by using them, and reports precisely what failed.
Why it exists. ‡ Check a set of Azure storage credentials by using them, and report precisely what failed, so an operator entering them gets a diagnosis rather than a rejection.
Called by — app/datasets/create/page.tsx
Reached from — /datasets/create
Opens a live connection to Azure Blob Storage with the given account name and key, confirms the container exists, and lists a few blobs to verify read permission — so an operator entering credentials gets a diagnosis (bad key, wrong account, container missing, no list permission) rather than a bare rejection. Authenticated (requireUser): this operation uses an Azure credential the caller supplies directly, not one read from a dataset row, so an unauthenticated caller would otherwise get a live oracle for testing a stolen Azure key.
Authentication: SupabaseAuth
Returns — success · message · containerExists · blobCount · sampleBlobs
Field names as the handler returns them; the source states no types for them.
Request body
| Field | Type | Required |
|---|---|---|
accountName |
string | yes |
accountKey |
string | yes |
containerName |
string | yes |
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
The connection, container, and list-permission checks all succeeded. | |
400 |
Account name, account key, and container name are required, or the credential could not be initialized. | Error |
401 |
Not authenticated, or Azure rejected the supplied credentials. | Error |
403 |
Connected, but listing the container’s contents was denied. | Error |
404 |
The named container does not exist in the storage account. | Error |
500 |
Server error, or an unexpected error validating the connection. | Error |