Media Library Setup

Upload, list, and delete media files in your GoHighLevel sub-account. The media library stores images, documents, and videos for use in emails, blogs, social posts, funnels, and websites. This quick-start covers authentication, uploading your first file, and managing stored media.

Prerequisites

Before making your first Media Library call, confirm you have:

• A GoHighLevel sub-account with active storage (all plans include media storage)
• Access to Settings > Integrations > Private Integrations in your sub-account
• A REST client such as Postman, Insomnia, or curl in your terminal
• Your sub-account’s locationId (found in Settings > Business Profile)
• A test image or file to upload (JPEG, PNG, GIF, PDF, or MP4 are commonly supported)

Set Up Authentication

All Media Library endpoints require a Private Integration Token (PIT) with the medias scope.

Navigate to Settings > Integrations > Private Integrations. Click Create New Integration, name it “Media Library API,” and enable the medias scope. Click Save and copy the generated token.

Pass this token in the Authorization header as a Bearer token. Set your base URL to https://services.leadconnectorhq.com. For the upload endpoint, use Content-Type: multipart/form-data instead of JSON.

Make Your First Call

Start by listing existing media to see what is already in your library:

GET /medias?locationId=your-location-id
Authorization: Bearer {your-pit-token}

This returns all media files with their id, name, url, type, and size fields. Use pagination parameters limit and offset for large libraries.

To upload a new file, send a POST request with form data:

POST /medias/upload-file
Authorization: Bearer {your-pit-token}
Content-Type: multipart/form-data

locationId: your-location-id
file: @image.png

The response returns the uploaded file’s id and hosted url. Use this URL in blog posts, email templates, social posts, and other GHL content.

To delete a file, call DELETE /medias/{id} with the file’s ID.

Handle the Response

A successful upload returns a 200 status with file details:

{
  "id": "media-789",
  "name": "image.png",
  "url": "https://storage.leadconnectorhq.com/media/image.png",
  "type": "image/png",
  "size": 245760,
  "createdAt": "2026-03-07T12:00:00Z"
}

Save the url for embedding in content. The id is needed for deletion. The hosted URL is permanent as long as the file exists in your library.

The list endpoint returns an array of these objects along with total for pagination. Common errors: 400 on upload means the file type is not supported or the file exceeds the size limit. 401 means your token is invalid. 404 on delete means the file ID does not exist.

Test Your Setup

Run through this checklist to confirm everything works:

1. List existing media with GET /medias and note the current count
2. Upload a test image with POST /medias/upload-file and save the returned url
3. Verify the URL loads in a browser by visiting it directly
4. List again to confirm the new file appears in results
5. Delete the test file with DELETE /medias/{id} and confirm it is removed

If uploads fail, check that the file size is within limits and the file format is supported. Common limits are 25MB for images and 100MB for videos. Verify your token has the medias scope enabled.

Next Steps

Read the full Media Library Guide for bulk upload patterns, folder organization, and CDN optimization. From here, explore Blog Post CRUD for embedding media in blog content and Email Template CRUD for using media in email designs.