bricks_upload_media

Phase 4BeginnerComplexity: 3/10

Upload an image from URL to the WordPress media library

Overview

Upload an image to the WordPress media library from a remote URL. The tool downloads the image from the specified URL, stores it in the WordPress uploads directory, and returns the media ID and URL for immediate use in Bricks elements.

This is the essential first step before referencing images in sections, hero backgrounds, cards, or any visual element. The returned media ID can be used in image elements, featured images, or background settings.

Key Features

URL-Based Upload

Downloads images from any public URL and stores them in the WordPress media library with proper metadata.

Alt Text Support

Accepts optional alt text for accessibility and SEO, attached to the media item at upload time.

Full Media Metadata

Returns media ID, source URL, width, height, and alt text — everything needed to reference the image in Bricks elements.

When to Use

Adding images to a page before building sections that reference them
Uploading hero backgrounds, card images, or logo files from external URLs
Preparing media assets during the design system setup phase
Importing images from a design prototype or stock photo service
Setting up featured images for posts created with bricks_create_post

Prerequisites

A publicly accessible image URL
WordPress media upload permissions enabled
Sufficient server disk space for the uploaded file

When NOT to Use

The image already exists in the media library — use bricks_list_media to check first
You need to upload non-image files like videos or PDFs (limited MIME type support)
The source URL requires authentication or is behind a firewall

Parameters

3 Total Parameters2 Required1 Optional

urlstringREQUIRED

URL of the image to download and upload. Must be a valid, publicly accessible URL.

filenamestringREQUIRED

Filename for the uploaded image (e.g., "hero-background.jpg"). Determines the file name in the uploads directory.

alt_textstringoptional

Alt text for accessibility and SEO. Stored as image metadata in the media library.

Code Examples

Warning: Undefined array key "example_output" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 12

Upload a hero background image

Download an image from Unsplash and store it in the media library with descriptive alt text.

JSON

bricks_upload_media({
  url: "https://images.unsplash.com/photo-example.jpg",
  filename: "hero-background.jpg",
  alt_text: "Modern office workspace with laptops and plants"
})
// Returns: { id: 42, url: "https://site.com/wp-content/uploads/2025/01/hero-background.jpg", width: 1920, height: 1080, alt_text: "Modern office workspace..." }

Warning: Undefined array key "example_output" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 12

Upload and use in a Bricks image element

Upload an image then reference it by ID in a Bricks section element.

JSON

// Step 1: Upload the image
const media = await bricks_upload_media({
  url: "https://example.com/team-photo.jpg",
  filename: "team-member-john.jpg",
  alt_text: "John Smith, Lead Developer"
});

// Step 2: Use in a Bricks image element
{ "type": "image", "settings": {
    "image": { "id": media.id, "url": media.url },
    "_width": "100%",
    "_aspectRatio": "16/9"
}}

Common Mistakes

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49

The source URL must be publicly accessible. URLs behind login walls, private S3 buckets, or authenticated CDNs will fail. Ensure the URL returns the image directly without redirects to login pages.

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49

Always provide descriptive alt text when uploading images. Missing alt text triggers validation warnings in bricks_validate_page and hurts both accessibility and SEO.

Tips & Warnings

Always upload images before building sections that reference them. The returned media ID is needed for image elements and featured images.

Use descriptive filenames like « hero-background.jpg » or « team-member-john.jpg » instead of generic names. This helps with media library organization and SEO.

Check the media library first with bricks_list_media to avoid uploading duplicates.

Return Values

Field	Type	Description
`id`	number	WordPress media attachment ID for referencing in elements.
`url`	string	Full URL to the uploaded image file.
`width`	number	Image width in pixels.
`height`	number	Image height in pixels.
`alt_text`	string	The alt text assigned to the image.

Related Tools

Technical Details

Tool ID

bricks_upload_media

API Endpoint

/bricks-mcp/v1/media

HTTP Method

POST

Namespace

content-queries

Source File

content/media.ts

Version

1.0

Min Bricks Version

1.9

Requires Auth

Yes

Changelog

v1.0

Initial release

20250101