Uploading Media

Overview

Postnomic uses Azure Blob Storage to host all media files associated with your blog. Images and other files are uploaded through the dashboard or API and served to readers through a built-in blob proxy that ensures consistent delivery.

Supported Formats

Uploads are validated against an allowlist of 22 file extensions:

Images

Audio and Video

Documents and Archives

Anything outside this list is rejected with a 400 Bad Request naming the disallowed extension. Separately, files whose Content-Type could be used to serve executable code — text/html, application/javascript, application/xml, application/x-httpd-php, and similar — are rejected regardless of extension, because Azure Blob Storage would serve them as-is.

File Size

The media API applies no per-file size limit of its own. An upload is refused only when it would push you past your plan's storage quota, which comes back as a 403 Forbidden. (The MCP upload_image tool does cap individual images at 10 MB, but that limit belongs to that tool, not to the media API.)

Uploading Images

From the Post Editor

When creating or editing a post, you can upload images directly:

1. Open the post editor
2. Click the image upload button or drag and drop an image onto the editor
3. Select the image from your computer
4. The image is uploaded to Azure Blob Storage and a reference is inserted into your content

Post Images

Each post supports three dedicated image fields:

• Cover Image — Displayed at the top of the post and in blog listings. Recommended size: 1200x630 pixels.
• Thumbnail Image — Used in compact listing views. A smaller version of the cover image.
• Share Image — Used for Open Graph and social media previews. Recommended size: 1200x630 pixels.

Upload these from the post editor's image section.

From the Media Library

Access the media library from your blog dashboard to:

• Browse all uploaded files
• Upload new files outside of the post editor
• Copy media URLs for use in content
• Delete unused files to free up storage

Storage Limits

Media storage is metered per blog owner and counted across all blogs you own:

When you attempt to upload a file that would exceed your storage limit, the API returns a 403 Forbidden response with a message indicating the quota has been reached. Upgrade your plan or delete unused files to free up space.

How the Blob Proxy Works

Postnomic serves media files through the BlobProxyController rather than exposing direct Azure Blob Storage URLs. This provides several benefits:

• Consistent URLs — Media URLs work regardless of the underlying storage configuration
• Access control — Files are served through the API, which can enforce authentication when needed
• Portability — If the storage backend changes, media URLs remain stable

When a Client SDK renders a post with images, it automatically resolves image references through the API's blob proxy endpoint.

Upload Best Practices

• Optimize images before uploading — Compress JPEG and PNG files to reduce storage usage and improve page load times
• Use WebP when possible — WebP provides superior compression compared to JPEG and PNG
• Choose appropriate dimensions — Do not upload 4000-pixel-wide images for a blog that displays at 800 pixels
• Use descriptive filenames — Name files descriptively (e.g., docker-architecture-diagram.png) for easier management
• Monitor storage usage — Check your storage consumption regularly under blog settings