Media
Upload and manage images, video, and PDFs (up to 100 MB per upload, 1 GB from a URL) for use in posts, reels, stories, and PDF carousels.
List media
query Parameters
limitoffsetsearchCase-insensitive search across the media name and filename. Use this to find an existing asset by name instead of re-uploading it.
folder_idReturn only media in this folder. Use "root" for unfiled items at the top level.
List media › Responses
List of media files
Rename or move media
Update the human-readable name and/or move a media file into a folder. Lets you label assets so they can be found later by name instead of re-uploading. Only the fields you send are changed.
path Parameters
idRename or move media › Request Body
nameHuman-readable label (e.g. "pp-play5get50"). Send an empty string to clear it.
folder_idMove the file into this folder. Send null to move it to the root ("All media").
Rename or move media › Responses
Media updated
Upload a file
Upload an image or video, or a PDF. A PDF is rasterized into one image slide per page and returned as a carousel (see PdfUploadResult): pass all of media_ids to POST /posts. On LinkedIn the slides post as a native swipeable document; on Instagram, TikTok, Threads and Pinterest as an image carousel. PDFs are capped at 20 pages.
Upload a file › Request Body
fileThe file to upload: an image, video, or PDF (max 100MB). Per-platform caps apply at scheduling: Mastodon 99MB, Bluesky 100MB, X 512MB (free tier), Threads/Reddit 1GB, Pinterest 2GB, Facebook/Instagram/TikTok 4GB, LinkedIn 5GB, YouTube 256GB. A PDF is split into image slides (max 20 pages) and returned as a carousel.
nameOptional human-readable label (e.g. "pp-play5get50") so the asset is findable by name later. If the same bytes were already uploaded, the existing file is returned and labelled with this name.
folderOptional folder name to file the asset under (created at the top level if it does not exist). Use folder_id instead to target an existing folder.
folder_idOptional id of an existing folder to file the asset under.
pdf_modePDF uploads only. slides (default): one image media item per page, one id each; pass ALL of media_ids to POST /posts. document: ONE media item for the whole PDF (type document, its pages in pdf.pages); pass its single id in media_ids and the post gets every page, in order. Both modes keep the original file, which LinkedIn receives when the pages are posted unchanged.
Upload a file › Responses
File uploaded successfully. For an image or video the body has a single data (Media). For a PDF the body is a PdfUploadResult with slides + media_ids for the whole carousel.
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
Whether the file fits the platforms connected to your workspace. compatible is true when no connected platform would reject it.
messageUpload from base64
Upload a file from base64-encoded data. Useful for MCP integrations where the AI has image data but no URL. Accepts images, video, and PDF (a PDF is split into image slides and returned as a carousel, see PdfUploadResult; pass all of media_ids to POST /posts). Max 100MB after decoding; per-platform caps apply at scheduling (Mastodon 99MB, Bluesky 100MB, X 512MB free tier, Threads/Reddit 1GB, Pinterest 2GB, Facebook/Instagram/TikTok 4GB, LinkedIn 5GB, YouTube 256GB).
Upload from base64 › Request Body
dataBase64-encoded file data (without data URI prefix)
mime_typeMIME type of the file (e.g. image/jpeg, image/png, application/pdf)
filenameOptional filename
nameOptional human-readable label so the asset is findable by name later (e.g. "pp-play5get50").
folderOptional folder name to file the asset under (created at the top level if missing).
folder_idOptional id of an existing folder to file the asset under.
pdf_modePDF uploads only. slides (default): one image media item per page, one id each; pass ALL of media_ids to POST /posts. document: ONE media item for the whole PDF (type document, its pages in pdf.pages); pass its single id in media_ids and the post gets every page, in order. Both modes keep the original file, which LinkedIn receives when the pages are posted unchanged.
Upload from base64 › Responses
File uploaded successfully. A single data (Media) for image/video; a PdfUploadResult (slides + media_ids) for a PDF.
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
Upload from a URL
Download a file from a URL and upload it to your media library. It is the recommended path for MCP/programmatic uploads. Supports videos up to 1 GB: files over 100 MB are streamed to storage by a background worker and the response returns 202 with the item in processing state (poll GET /media/{id} until status is ready). Files at or under 100 MB upload inline and return 201 ready. A PDF URL is split into image slides and returned as a carousel (see PdfUploadResult; pass all of media_ids to POST /posts). Every response also includes a compatibility block listing any connected platforms that would reject the file by size or format.
Upload from a URL › Request Body
urlHTTP or HTTPS URL of the file to download (max 1 GB for video; per-platform caps apply at scheduling).
filenameOptional filename override
nameOptional human-readable label so the asset is findable by name later (e.g. "pp-play5get50").
folderOptional folder name to file the asset under (created at the top level if missing).
folder_idOptional id of an existing folder to file the asset under.
pdf_modePDF uploads only. slides (default): one image media item per page, one id each; pass ALL of media_ids to POST /posts. document: ONE media item for the whole PDF (type document, its pages in pdf.pages); pass its single id in media_ids and the post gets every page, in order. Both modes keep the original file, which LinkedIn receives when the pages are posted unchanged.
Upload from a URL › Responses
File uploaded inline (<= 100 MB) and ready to use. A single data (Media) for image/video; a PdfUploadResult (slides + media_ids) for a PDF.
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
Whether the file fits the platforms connected to your workspace. compatible is true when no connected platform would reject it.
messageCreate an upload URL
Create a one-time upload URL, for code that cannot send the API key with the upload, such as an AI assistant's code sandbox. POST the file as multipart file to upload_url (POST /media/upload-by-token) within 10 minutes; the URL works once. The MCP server's upload tool uses this flow. Requires the media:write scope.
Create an upload URL › Responses
The one-time upload URL and how to use it.
upload_urlPOST the file here (POST /media/upload-by-token with the token in the query).
upload_tokenThe one-time token (64 hex characters), also part of upload_url.
expires_in_secondsmethodcontent_typeinstructionsUpload commands (curl and Python) written for an AI assistant's code sandbox.
hintWhat an AI assistant should tell the user when its sandbox blocks the upload host.
Split a PDF into pages
For a media item of type document (a PDF kept as one item): creates one image media item per rendered page, in page order, each a copy of the page image and each carrying pdf with its page number. The document item stays. Use it when a single page is needed as a normal image. A full, ordered set of the slides still publishes the original PDF on LinkedIn. Requires media:write.
path Parameters
idSplit a PDF into pages › Responses
The new slide items, in page order
media_idsCheck media limits
Preflight a file against the platforms connected to your workspace and find out which (if any) would reject it by size or format, before you upload or post. Provide ONE of: a public url (we read its size/type via a HEAD request), an existing media_id, or an explicit size_bytes + mime. Use this to warn the user ("this 995 MB video won't post to Instagram") and confirm before uploading.
Check media limits › Request Body
urlPublic URL of the file to check (HEAD-probed for size + type).
media_idId of an already-uploaded library item to check.
size_bytesFile size in bytes (use with mime when you already know them).
mimeMIME type, e.g. "video/mp4" (use with size_bytes).
Check media limits › Responses
Compatibility result
connected_platformscompatibletrue when no connected platform would reject the file.
summaryOne-line human summary, or null when fully compatible.
How each connected channel with a fit rule shows this IMAGE as a feed post (sizes known for library images). fits: false = the ratio is outside the window the channel shows uncropped; default_action is what a post create does (crop = Instagram crops it to target around the subject; keep = Pinterest sends it as it is and reports it) unless the post's media_fit says otherwise. Empty for videos and unknown sizes.
Upload with a token
Upload a file to a one-time URL from POST /media/create-upload-url. No API key: the upload_token query parameter is the auth, valid once for 10 minutes. Takes the same files as POST /media/upload (images, video, PDF; up to 100 MB). If storage is briefly down (503), the token stays valid and the same request can be sent again.
query Parameters
upload_tokenThe token from POST /media/create-upload-url.
Upload with a token › Request Body
fileAn image, video or PDF, up to 100 MB.
nameOptional label so the file is findable by name later.
pdf_modePDF uploads only, as on POST /media/upload.
Upload with a token › Responses
The stored file. For an image or video, data is the media item. For a PDF the body is a PdfUploadResult.
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |