Skip to main content

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​

CodeDescription
200 OKUpload successful
400 Bad RequestInvalid request or field is not a BLOB type
404 Not FoundItem 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.

Inline Upload via JSON Body​

Blob fields can also be set directly in a POST or PATCH request body using base64-encoded content. This is useful for AI agents, MCP tools, or any client that doesn't support multipart form-data.

{
  "name": "Product Manual",
  "document": {
    "data": "SGVsbG8gV29ybGQ=",
    "filename": "manual.pdf",
    "contentType": "application/pdf"
  }
}
FieldRequiredDescription
dataYesBase64-encoded file content
filenameYesOriginal filename
contentTypeYesMIME type of the file

To clear a blob field, set it to null in a PATCH. Omitting the blob field in a PATCH leaves it untouched.

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
Last updated on