Working with BLOBs

BLOB (Binary Large Object) properties store binary data like file uploads. Use them for images, documents, or any file type.

Requirements

To upload a BLOB:

• The item must already exist
• The target field must be defined as a BLOB type in your schema
• Use POST with Content-Type: multipart/form-data
• The form field must be named file

URL Format

/api/{collection}/{item-id}/{blob-field}

Example:

/api/products/abc-123/image

External Clients

External clients should replace /api with https://<region>.restapi.com/<api-name>. See Virtual Paths for details.

Upload Examples

Using fetch

const formData = new FormData();
formData.append("file", fileInput.files[0]);

const response = await fetch("/api/products/abc-123/image", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
  },
  body: formData,
});

Using axios

const formData = new FormData();
formData.append("file", file);

await axios.post("/api/products/abc-123/image", formData, {
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "multipart/form-data",
  },
});

Using curl

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/image.png" \
  https://<region>.restapi.com/<api-name>/products/abc-123/image

Using an HTML Form

<form
  action="/api/products/abc-123/image"
  method="POST"
  enctype="multipart/form-data"
>
  <input type="file" name="file" />
  <button type="submit">Upload</button>
</form>

Response Codes

Code	Description
200 OK	Upload successful
400 Bad Request	Invalid request or field is not a BLOB type
404 Not Found	Item doesn't exist

Retrieving BLOBs

BLOB data is returned when you GET the item. The response includes the binary data or a URL to access it, depending on your API configuration.

Best Practices

• Validate file types on the client before uploading
• Set size limits appropriate for your use case
• Use appropriate BLOB fields — don't store large files in regular string fields
• Consider CDN caching for frequently accessed files