POST
/
media
/
upload
# Send as Multipart Form-Data
curl \
-H "Authorization: Bearer API_KEY" \
-F "[email protected]" \
-F "fileName=test.png" \
-F "description=best image" \
-X POST https://api.ayrshare.com/api/media/upload

# Send as Base64
curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: application/json' \
-d '{"file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...", "fileName": "test.png", "description": "best image"}' \
-X POST https://api.ayrshare.com/api/media/upload

{
    "id": "1167335b-6c37-4fc6-ab8a-044e0005d335-jpeg",
    "url": "https://images.ayrshare.com/q3Ls85VTsrbODnGIJHpy7PaHWwA3/1167335b-6c37-4fc6-ab8a-044ed885d.jpeg",
    "fileName": "fun.jpg",
    "description": "good times"
}
Available on Premium, Business, Enterprise plans.

This endpoint allows you to upload a file or an image or small video to include in your post. Returned will be the URL to the image that can be used in the /post endpoint.

You can pass the file either as a multipart form data as a form parameter or a Base64 encoded file as a body parameter.

Important notes about media uploads:

  1. For best performance, we recommend

    • Hosting media files on your own server (e.g. AWS S3).
    • Passing the media URL directly in the mediaUrls parameter of the /post endpoint.
    • This approach is faster than uploading files through this endpoint.

  2. Media file retention

    • Uploaded files are stored for 90 days.
    • After 90 days:
      • Published posts on social networks are unaffected.
      • Scheduled posts will fail to publish if they reference expired media.

  3. File size limits

If you already have your media accessible by an external URL, such as an S3 bucket, you can skip uploading the files to Ayrshare. Just POST to the /post endpoint with your externally accessible URL in the mediaURLs body parameter and your file will automatically be uploaded.

​
Header Parameters

​
Authorization
string
required
API Key of the Primary Profile.

Format: Authorization: Bearer API_KEY
​
Content-Type
string
required

Use multipart/form-data if sending a multipart form data - see below. Otherwise, send the standard application/json.

​
Body Parameters

​
file
string or object
required

Max 30 MB file size.

We recommend sending as a multipart form-data object instead of Base64 encoding.

​
fileName
string

The name of the file to be uploaded.

​
description
string

A description of the file.

​
Send as Multipart Form-Data

Send the media file as a multipart form-data object. Please be sure to specify the Content-Type as mentioned above.

​
Send as Base64

Send the media file as a Base64 encoded string as a Data URI string. The string should begin with data:content/type;base64

Example encoding with Output Format Data URI:

Note: The /post endpoint accepts larger files via an external URL with the mediaUrls parameter.

# Send as Multipart Form-Data
curl \
-H "Authorization: Bearer API_KEY" \
-F "[email protected]" \
-F "fileName=test.png" \
-F "description=best image" \
-X POST https://api.ayrshare.com/api/media/upload

# Send as Base64
curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: application/json' \
-d '{"file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...", "fileName": "test.png", "description": "best image"}' \
-X POST https://api.ayrshare.com/api/media/upload

{
    "id": "1167335b-6c37-4fc6-ab8a-044e0005d335-jpeg",
    "url": "https://images.ayrshare.com/q3Ls85VTsrbODnGIJHpy7PaHWwA3/1167335b-6c37-4fc6-ab8a-044ed885d.jpeg",
    "fileName": "fun.jpg",
    "description": "good times"
}