---
title: "Upload Media"
method: POST
path: "/v1/media/upload"
tags: ["Media"]
---

# Upload Media

`POST /v1/media/upload`

## Request

- Base URL: `https://api.linkedmash.com`
- URL: `https://api.linkedmash.com/v1/media/upload`
- Auth: one of:
  - OAuth 2 (client credentials, token URL `https://api.linkedmash.com/auth/oauth/token`, scopes: `content:write`)
  - HTTP bearer
  - API key in header `linkedmash-api-key`

Re-host an image, video, or PDF for use in a post. Provide either url or file_base64, not both. Requires a paid Premium or Lifetime plan.

POST /v1/media/upload re-hosts an image, video or PDF on LinkedMash and returns a stable public URL to use as media_url on a draft or a schedule call. It takes either a remote url to fetch and copy, or file_base64 with a file_name for raw bytes — one or the other, not both.

Re-hosting is the recommended path even when you already have a URL. A scheduled post publishes hours or days after it is created, and an asset that has expired or moved by then publishes as a post with a broken attachment.

## Request body

- object
  - `url` string, uri: Remote http(s) URL to re-host. Provide either url or file_base64.
  - `file_base64` string: Base64-encoded file bytes — an alternative to url.
  - `file_name` string: Original file name.
  - `mime_type` string: MIME type of the file (e.g., 'image/png').

## Response `201`

Successful response.

- object
  - `status` boolean, required
  - `data` object, required
    - `url` string, uri, required
    - `file_type` string, required
    - `file_name` string, required
    - `mime_type` string, required

## Other responses

- `400`: Bad Request. Neither url nor file_base64 was given, the url was invalid or not http(s), the source could not be fetched, file_name was missing alongside file_base64, or the base64 payload could not be decoded.
- `401`: Unauthorized. The Authorization header is missing or the key is not a valid LinkedMash API key. Create or rotate keys on the API page in your LinkedMash settings.
- `402`: Payment Required. Returned with code SUBSCRIPTION_REQUIRED. The content API requires a Premium or Lifetime plan; Reader and free accounts get this on every /v1/posts, /v1/queue, /v1/schedule, /v1/media and /v1/analytics call.
- `500`: Server Error. Something failed on our side. The body carries message "Failed to upload media". Retry once; if it persists the request is not the problem.

---

[API](https://skmtc.dev/linkedmash/apis/linkedmash-api.md) · [All operations](https://skmtc.dev/linkedmash/apis/linkedmash-api/llms.txt) · [OpenAPI document](https://skmtc.dev/linkedmash/apis/linkedmash-api/revisions/eef45d6fbea3?raw)