ImageURL (Semantic Module)

← Back to Modules Reference

The ImageURL semantic module manages visual media attachments—such as user profile pictures, product photo galleries, cover banners, and catalog thumbnails.

Rather than handling complex multi-part binary file streaming through your application endpoints, decorating a property with ImageURL leverages API Now’s Two-Phase Upload Architecture. Clients upload images directly to secure cloud storage, while the Serverless Engine validates image formats, enforces size limits, optimizes files into modern web formats (such as WebP), and serves images via secure, expiring signed URLs.

Technical Specifications

Attribute	Specification
Scope	`Property` (Applied to a text property)
Data Type	`String`
Default Max Size	`5242880` bytes (5 MB)
Default Allowed MIME Types	`image/jpeg`, `image/png`, `image/webp`, `image/gif`
Automatic Optimization	Enabled by default (`requireOptimization: true`)
Delivery Mechanism	Time-limited Read-Only Signed URLs (15-minute expiration)

Key Capabilities

1. Image Format Allow List (`allowedMimeTypes`)

Restricts uploads strictly to visual formats. By default, only safe, standard web images (JPEG, PNG, WebP, and GIF) are permitted. Non-image files (such as PDFs, scripts, or executables) are blocked during initial upload initialization.

2. Automatic Image Optimization (`requireOptimization`)

When enabled (default: true), the runtime automatically compresses oversized uploads and re-encodes images into lightweight, modern web formats (like WebP). This significantly reduces page load times and mobile bandwidth usage without requiring third-party image transformation pipelines.

3. Two-Phase Upload Flow

API Now decouples binary file storage from your database records:

Initialize (POST /.well-known/upload): The client requests permission to upload, specifying filename and image MIME type, and receives a temporary signed upload URL plus a unique file_reference token.
Direct Upload (PUT upload_url): The client uploads the binary image directly to cloud storage, bypassing API servers.
Record Association: The client passes the file_reference token as the string value when creating or updating the record.

For a complete architectural walkthrough of this workflow, see the File Uploads Guide.

4. Secure Delivery via Signed URLs

Images are not exposed through static public bucket links. When reading records (GET /products/prod_101 or GET /products), the engine replaces the internal storage reference with a temporary, read-only Signed URL valid for 15 minutes. Access is protected by the entity’s authorization and RBAC rules—if a user lacks permission to read the record, they cannot view the image.

Configuration Options

When configuring the ImageURL semantic in the Domain Modeler, you can adjust:

Option	Type	Default	Description
`maxSizeInBytes`	`number`	`5242880` (5 MB)	Maximum permitted file size in bytes.
`allowedMimeTypes`	`string[]`	`['image/jpeg', 'image/png', 'image/webp', 'image/gif']`	Allow list of permitted image MIME types.
`requireOptimization`	`boolean`	`true`	Hints the engine to optimize and convert uploaded images to WebP.

API Lifecycle Examples

1. Initializing Image Upload

The client initiates an upload:

POST /api/v1/.well-known/upload
Content-Type: application/json

{
  "filename": "headshot.png",
  "contentType": "image/png"
}

Server Response (200 OK):

{
  "data": {
    "file_reference": "ref_img_89a1c24e",
    "upload_url": "https://storage.googleapis.com/app-bucket/tmp/ref_img_89a1c24e.png?GoogleAccessId=..."
  }
}

2. Saving the Record

After uploading the binary content to the upload_url, the client creates the user profile:

POST /profiles
Content-Type: application/json

{
  "name": "Sarah Connor",
  "avatar": "ref_img_89a1c24e"
}

Server Response (201 Created):

{
  "data": {
    "id": "prof_301",
    "name": "Sarah Connor",
    "avatar": "https://storage.googleapis.com/app-bucket/uploads/profiles/prof_301/avatar.webp?X-Goog-Signature=..."
  }
}

3. Reading the Record (`GET`)

When querying the record, the platform dynamically generates a fresh signed URL:

GET /profiles/prof_301