Retrieve blob metadata and download blob content, plus manage your uploaded files through the ModelWorks website.

Blob Storage API

The Blob Storage API lets you retrieve metadata and download content for file blobs stored in Google Cloud Storage (GCS). Uploading new blobs and listing all of your own blobs are web-session-only actions — you do them through the ModelWorks website (see Managing Your Blobs).

Authentication

The two documented endpoints — retrieve metadata (GET /blobs/{uid}) and download content (GET /blobs/{uid}/download) — are publicly accessible. No API token or login is required to read blob metadata or download blob content.

Endpoints

1. Retrieve Blob Metadata

GET /blobs/{uid}

Fetch metadata about a single blob by its uid. No authentication required.

Path Parameters:
- uid (string): The unique identifier of the blob.

Response (200 OK):

JSON

{
  "uid": "uuid",
  "blob_type": "GCS",
  "path": "gs://bucket/uuid",
  "hash": "<sha256>",
  "user_uid": "<uploader-id>",
  "created_at": "2025-01-01T12:00:00Z",
  "can_delete": true,
  "bytes": 12345,
  "total_reads": 0,
  "mime_type": "image/png"
}

Errors:
- 404 Not Found if no blob exists with the given uid.

2. Download Blob Content

GET /blobs/{uid}/download

Redirects to the blob's content in Google Cloud Storage. Returns an HTTP 302 response with a Location header pointing to a signed GCS URL that the client can follow to download the file directly.

Path Parameters:
- uid (string): The unique identifier of the blob.
Response (302 Found):
- Location: A signed GCS URL the client follows to stream or download the file content.
Errors:
- 404 Not Found if no blob exists with the given uid.

Managing Your Blobs

Uploading files and viewing the full list of your blobs happen in the ModelWorks website — there are no API endpoints for these actions.

Upload Files

To upload files, log in to modelworks.ai, click your avatar (top-right) → Settings → Infrastructure Services → Blob Store. Here you can upload files (images, documents, etc.) by dragging them into the upload area or selecting them from your computer. Each file gets a unique blob UID that you can reference in your circuits.

List Your Blobs

The Blob Store page in Settings shows all your uploaded files with their UIDs, sizes, and upload dates. You can use this page to find and copy blob UIDs for use in your circuits.

Blob Public Schema

All blob responses share the following structure:

Field	Type	Description
`uid`	string	Unique blob identifier.
`blob_type`	string	Storage backend (always `GCS`). Admin/system tokens only.
`path`	string	Full GCS path (e.g. `gs://bucket/uuid`). Admin/system tokens only.
`hash`	string	SHA-256 checksum of the file content.
`user_uid`	string	Uploader's user ID.
`created_at`	datetime	Timestamp when blob was created.
`can_delete`	boolean	Whether the caller may delete this blob.
`bytes`	integer	Size of the blob in bytes.
`total_reads`	integer	Number of times blob metadata has been fetched.
`mime_type`	string?	Inferred MIME type (if detectable).

Note: The blob_type and path fields are only included in responses for admin/system tokens. Regular requests do not receive these fields.

Usage Examples

Retrieve Metadata

Bash

curl https://api.modelworks.ai/blobs/123e4567-e89b-12d3-a456-426614174000

Download Blob Content

Add -L so curl follows the redirect to the signed GCS URL: