Media

Upload and manage images, video, and PDFs (up to 50MB) for use in posts, reels, stories, and PDF carousels.

List uploaded media

GET

/media

List uploaded media › query Parameters

limit

integer · max: 100

Default: 20

offset

integer

Default: 0

search

string

Case-insensitive search across the media name and filename. Use this to find an existing asset by name instead of re-uploading it.

folder_id

string

Return only media in this folder. Use "root" for unfiled items at the top level.

List uploaded media › Responses

200

List of media files

Media[]

Pagination

Get a single media item

GET

/media/{id}

Fetch one media item by id — use this to poll a large URL upload until its status becomes ready (or failed).

Get a single media item › path Parameters

id

string · required

Media id returned by an upload endpoint.

Get a single media item › Responses

The media item

Media

Delete a media file

DELETE

/media/{id}

Delete a media file › path Parameters

id

string · required

Delete a media file › Responses

Media deleted

No data returned

Rename or move a media file

PATCH

/media/{id}

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.

Rename or move a media file › path Parameters

id

string · required

Rename or move a media file › Request Body

name

string

Human-readable label (e.g. "pp-play5get50"). Send an empty string to clear it.

folder_id

string | null

Move the file into this folder. Send null to move it to the root ("All media").

Rename or move a media file › Responses

Media updated

Media

Upload a media file (image, video, or PDF carousel)

POST

/media/upload

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 media file (image, video, or PDF carousel) › Request Body

file

string · required

The file to upload — 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.

name

string

Optional 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.

folder

string

Optional 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_id

string

Optional id of an existing folder to file the asset under.

Upload a media file (image, video, or PDF carousel) › 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.

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for Variant 1:

Media

MediaCompatibility

Whether the file fits the platforms connected to your workspace. compatible is true when no connected platform would reject it.

message

string

POST/media/upload

curl /media/upload \
  --request POST \
  --header 'Content-Type: multipart/form-data' \
  --header 'Authorization: Bearer <token>' \
  --form 'file=file' \
  --form 'name=name' \
  --form 'folder=folder' \
  --form 'folder_id=folder_id'

Example Request Body

{
  "file": "file",
  "name": "name",
  "folder": "folder",
  "folder_id": "folder_id"
}

text

Example Responses

{
  "data": {
    "id": "id",
    "url": "url",
    "thumbnail_url": "thumbnail_url",
    "type": "image",
    "name": "name",
    "folder_id": "folder_id",
    "filename": "filename",
    "size": "size",
    "status": "ready",
    "created_at": "2024-08-25T15:00:00Z"
  },
  "compatibility": {
    "compatible": true,
    "warnings": [
      {
        "platform": "platform",
        "display_name": "display_name",
        "reasons": [
          "string"
        ]
      }
    ],
    "summary": "summary"
  },
  "message": "message"
}

json

application/json

Upload media from base64 data

POST

/media/upload-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 media from base64 data › Request Body

data

string · required

Base64-encoded file data (without data URI prefix)

mime_type

string · required

MIME type of the file (e.g. image/jpeg, image/png, application/pdf)

filename

string

Optional filename

name

string

Optional human-readable label so the asset is findable by name later (e.g. "pp-play5get50").

folder

string

Optional folder name to file the asset under (created at the top level if missing).

folder_id

string

Optional id of an existing folder to file the asset under.

Upload media from base64 data › Responses

File uploaded successfully. A single data (Media) for image/video; a PdfUploadResult (slides + media_ids) for a PDF.

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for Variant 1:

Media

POST/media/upload-from-base64

curl /media/upload-from-base64 \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "data": "data",
  "mime_type": "mime_type",
  "filename": "filename",
  "name": "name",
  "folder": "folder",
  "folder_id": "folder_id"
}'

Example Request Body

{
  "data": "data",
  "mime_type": "mime_type",
  "filename": "filename",
  "name": "name",
  "folder": "folder",
  "folder_id": "folder_id"
}

json

Example Responses

{
  "data": {
    "id": "id",
    "url": "url",
    "thumbnail_url": "thumbnail_url",
    "type": "image",
    "name": "name",
    "folder_id": "folder_id",
    "filename": "filename",
    "size": "size",
    "status": "ready",
    "created_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Upload media from a URL

POST

/media/upload-from-url

Download a file from a URL and upload it to your media library — 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 media from a URL › Request Body

url

string · uri · required

HTTP or HTTPS URL of the file to download (max 1 GB for video; per-platform caps apply at scheduling).

filename

string

Optional filename override

name

string

Optional human-readable label so the asset is findable by name later (e.g. "pp-play5get50").

folder

string

Optional folder name to file the asset under (created at the top level if missing).

folder_id

string

Optional id of an existing folder to file the asset under.

Upload media 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.

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for Variant 1:

Media

MediaCompatibility

Whether the file fits the platforms connected to your workspace. compatible is true when no connected platform would reject it.

message

string

POST/media/upload-from-url

curl /media/upload-from-url \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "url": "https://www.example.com/path/to/resource",
  "filename": "filename",
  "name": "name",
  "folder": "folder",
  "folder_id": "folder_id"
}'

Example Request Body

{
  "url": "https://www.example.com/path/to/resource",
  "filename": "filename",
  "name": "name",
  "folder": "folder",
  "folder_id": "folder_id"
}

json

Example Responses

{
  "data": {
    "id": "id",
    "url": "url",
    "thumbnail_url": "thumbnail_url",
    "type": "image",
    "name": "name",
    "folder_id": "folder_id",
    "filename": "filename",
    "size": "size",
    "status": "ready",
    "created_at": "2024-08-25T15:00:00Z"
  },
  "compatibility": {
    "compatible": true,
    "warnings": [
      {
        "platform": "platform",
        "display_name": "display_name",
        "reasons": [
          "string"
        ]
      }
    ],
    "summary": "summary"
  },
  "message": "message"
}

json

application/json

Check media compatibility before uploading

POST

/media/check

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 compatibility before uploading › Request Body

url

string

Public URL of the file to check (HEAD-probed for size + type).

media_id

string

Id of an already-uploaded library item to check.

size_bytes

integer

File size in bytes (use with mime when you already know them).

mime

string

MIME type, e.g. "video/mp4" (use with size_bytes).

Check media compatibility before uploading › Responses

Compatibility result

object

connected_platforms

string[]

compatible

boolean

true when no connected platform would reject the file.

object[]

summary

string | null

One-line human summary, or null when fully compatible.

Posts Folders

OmniSocials API

Media

Upload and manage images, video, and PDFs (up to 50MB) for use in posts, reels, stories, and PDF carousels.

List uploaded media

GET

/media

List uploaded media › query Parameters

limit

integer · max: 100

Default: 20

offset

integer

Default: 0

search

string

Case-insensitive search across the media name and filename. Use this to find an existing asset by name instead of re-uploading it.

folder_id

string

Return only media in this folder. Use "root" for unfiled items at the top level.

List uploaded media › Responses

200

List of media files

Media[]

Pagination

Get a single media item

GET

/media/{id}

Fetch one media item by id — use this to poll a large URL upload until its status becomes ready (or failed).

Get a single media item › path Parameters

id

string · required

Media id returned by an upload endpoint.

Get a single media item › Responses

The media item

Media

Delete a media file

DELETE

/media/{id}

Delete a media file › path Parameters

id

string · required

Delete a media file › Responses

Media deleted

No data returned

Rename or move a media file

PATCH

/media/{id}

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.

Rename or move a media file › path Parameters

id

string · required

Rename or move a media file › Request Body

name

string

Human-readable label (e.g. "pp-play5get50"). Send an empty string to clear it.

folder_id

string | null

Move the file into this folder. Send null to move it to the root ("All media").

Rename or move a media file › Responses

Media updated

Media

Upload a media file (image, video, or PDF carousel)

POST

/media/upload

Upload a media file (image, video, or PDF carousel) › Request Body

file

string · required

name

string

Optional 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.

folder

string

Optional 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_id

string

Optional id of an existing folder to file the asset under.

Upload a media file (image, video, or PDF carousel) › 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.

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for Variant 1:

Media

MediaCompatibility

Whether the file fits the platforms connected to your workspace. compatible is true when no connected platform would reject it.

message

string

POST/media/upload

curl /media/upload \
  --request POST \
  --header 'Content-Type: multipart/form-data' \
  --header 'Authorization: Bearer <token>' \
  --form 'file=file' \
  --form 'name=name' \
  --form 'folder=folder' \
  --form 'folder_id=folder_id'

Example Request Body

{
  "file": "file",
  "name": "name",
  "folder": "folder",
  "folder_id": "folder_id"
}

text

Example Responses

{
  "data": {
    "id": "id",
    "url": "url",
    "thumbnail_url": "thumbnail_url",
    "type": "image",
    "name": "name",
    "folder_id": "folder_id",
    "filename": "filename",
    "size": "size",
    "status": "ready",
    "created_at": "2024-08-25T15:00:00Z"
  },
  "compatibility": {
    "compatible": true,
    "warnings": [
      {
        "platform": "platform",
        "display_name": "display_name",
        "reasons": [
          "string"
        ]
      }
    ],
    "summary": "summary"
  },
  "message": "message"
}

json

application/json

Upload media from base64 data

POST

/media/upload-from-base64

Upload media from base64 data › Request Body

data

string · required

Base64-encoded file data (without data URI prefix)

mime_type

string · required

MIME type of the file (e.g. image/jpeg, image/png, application/pdf)

filename

string

Optional filename

name

string

Optional human-readable label so the asset is findable by name later (e.g. "pp-play5get50").

folder

string

Optional folder name to file the asset under (created at the top level if missing).

folder_id

string

Optional id of an existing folder to file the asset under.

Upload media from base64 data › Responses

File uploaded successfully. A single data (Media) for image/video; a PdfUploadResult (slides + media_ids) for a PDF.

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for Variant 1:

Media

POST/media/upload-from-base64

curl /media/upload-from-base64 \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "data": "data",
  "mime_type": "mime_type",
  "filename": "filename",
  "name": "name",
  "folder": "folder",
  "folder_id": "folder_id"
}'

Example Request Body

{
  "data": "data",
  "mime_type": "mime_type",
  "filename": "filename",
  "name": "name",
  "folder": "folder",
  "folder_id": "folder_id"
}

json

Example Responses

{
  "data": {
    "id": "id",
    "url": "url",
    "thumbnail_url": "thumbnail_url",
    "type": "image",
    "name": "name",
    "folder_id": "folder_id",
    "filename": "filename",
    "size": "size",
    "status": "ready",
    "created_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Upload media from a URL

POST

/media/upload-from-url

Upload media from a URL › Request Body

url

string · uri · required

HTTP or HTTPS URL of the file to download (max 1 GB for video; per-platform caps apply at scheduling).

filename

string

Optional filename override

name

string

Optional human-readable label so the asset is findable by name later (e.g. "pp-play5get50").

folder

string

Optional folder name to file the asset under (created at the top level if missing).

folder_id

string

Optional id of an existing folder to file the asset under.

Upload media 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.

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for Variant 1:

Media

MediaCompatibility

Whether the file fits the platforms connected to your workspace. compatible is true when no connected platform would reject it.

message

string

POST/media/upload-from-url

curl /media/upload-from-url \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "url": "https://www.example.com/path/to/resource",
  "filename": "filename",
  "name": "name",
  "folder": "folder",
  "folder_id": "folder_id"
}'

Example Request Body

{
  "url": "https://www.example.com/path/to/resource",
  "filename": "filename",
  "name": "name",
  "folder": "folder",
  "folder_id": "folder_id"
}

json

Example Responses

{
  "data": {
    "id": "id",
    "url": "url",
    "thumbnail_url": "thumbnail_url",
    "type": "image",
    "name": "name",
    "folder_id": "folder_id",
    "filename": "filename",
    "size": "size",
    "status": "ready",
    "created_at": "2024-08-25T15:00:00Z"
  },
  "compatibility": {
    "compatible": true,
    "warnings": [
      {
        "platform": "platform",
        "display_name": "display_name",
        "reasons": [
          "string"
        ]
      }
    ],
    "summary": "summary"
  },
  "message": "message"
}

json

application/json

Check media compatibility before uploading

POST

/media/check

Check media compatibility before uploading › Request Body

url

string

Public URL of the file to check (HEAD-probed for size + type).

media_id

string

Id of an already-uploaded library item to check.

size_bytes

integer

File size in bytes (use with mime when you already know them).

mime

string

MIME type, e.g. "video/mp4" (use with size_bytes).

Check media compatibility before uploading › Responses

Compatibility result

object

connected_platforms

string[]

compatible

boolean

true when no connected platform would reject the file.

object[]

summary

string | null

One-line human summary, or null when fully compatible.

Posts Folders