Media

get/v1/mediaList media
post/v1/mediaCreate media upload
get/v1/media/{id}Get media
del/v1/media/{id}Delete media
post/v1/media/{id}/completeComplete media upload
get/v1/media-foldersList media folders
post/v1/media-foldersCreate media folder
patch/v1/media-folders/{id}Rename media folder
del/v1/media-folders/{id}Delete media folder
post/v1/media-folders/{id}/moveMove media folder
put/v1/media-folder-colorsSet media folder color
post/v1/media-movesMove media items
put/v1/media/{id}/titleRename media
put/v1/media/{id}/alt-textSet media alt text
get/v1/media/{id}/usageGet media usage
get/v1/media-storageGet storage usage

List media

get/v1/media

List media assets in the selected workspace with optional status and content-type filters and cursor pagination. Returns media IDs, metadata and temporary signed download URLs. Use ready media IDs when attaching assets to posts.

Query parameters

workspaceIdstring
Min length 1
limitinteger
Default 20 · Min 1 · Max 100
starting_afterstring
ending_beforestring
statusstring
One ofpendingprocessingreadyfaileddeduped
contentTypestring
One ofimage/jpegimage/pngimage/webpimage/gifvideo/mp4video/quicktime

Response 200

List of media

objectstringrequired
One oflist
dataarray of Mediarequired
has_morebooleanrequired
next_cursorstringrequirednullable

Errors

401: Unauthenticated
403: Missing scope

Request

curl "https://api.posty.social/v1/media" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "workspaceId": "string",
      "folderId": "string",
      "title": "string",
      "thumbhash": "string",
      "sizeBytes": 1,
      "contentType": "string",
      "etag": "string",
      "status": "pending",
      "width": 1,
      "height": 1,
      "altText": "string",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z",
      "duration": 1,
      "url": "string",
      "thumbnailUrl": "string"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

Create media upload

post/v1/media

Start a media upload by providing a title, supported contentType and sizeBytes in the selected workspace. Creates a pending media record and returns its ID, temporary uploadUrl and expiry. Transfer file bytes separately with HTTP PUT to uploadUrl, then call complete_media_upload. This call alone does not transfer the file.

Request body

titlestringrequired
Min length 1 · Max length 500
contentTypestringrequired
One ofimage/jpegimage/pngimage/webpimage/gifvideo/mp4video/quicktime
sizeBytesintegerrequired
Min 1 · Max 5000000000

Response 201

Upload URL issued

idstringrequired
uploadUrlstringrequired
keystringrequired
expiresAtstring (date-time)required

Errors

400: Validation error
401: Unauthenticated
403: Missing scope
409: Storage limit exceeded

Request

curl -X POST "https://api.posty.social/v1/media" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "string",
  "contentType": "image/jpeg",
  "sizeBytes": 1
}'

Response 201

{
  "id": "string",
  "uploadUrl": "string",
  "key": "string",
  "expiresAt": "2026-01-15T09:30:00.000Z"
}

Get media

get/v1/media/{id}

Retrieve a media asset by ID in the selected workspace. Returns its upload or processing status, file metadata and temporary signed download URLs for the asset and any thumbnail.

Path parameters

idstringrequired

Response 200

Media

idstringrequired
workspaceIdstringrequired
folderIdstringrequirednullable
titlestringrequired
thumbhashstringrequirednullable
Base64 ThumbHash (https://evanw.github.io/thumbhash/) of the thumbnail, for a blurred placeholder while it loads. Null until one has been computed.
sizeBytesintegerrequired
contentTypestringrequired
etagstringrequirednullable
statusstringrequired
One ofpendingprocessingreadyfaileddeduped
widthintegerrequirednullable
heightintegerrequirednullable
altTextstringrequirednullable
createdAtstring (date-time)requirednullable
updatedAtstring (date-time)requirednullable
durationintegerrequirednullable
urlstringrequirednullable
thumbnailUrlstringrequirednullable

Errors

401: Unauthenticated
403: Missing scope
404: Not found

Request

curl "https://api.posty.social/v1/media/$ID" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "id": "string",
  "workspaceId": "string",
  "folderId": "string",
  "title": "string",
  "thumbhash": "string",
  "sizeBytes": 1,
  "contentType": "string",
  "etag": "string",
  "status": "pending",
  "width": 1,
  "height": 1,
  "altText": "string",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "duration": 1,
  "url": "string",
  "thumbnailUrl": "string"
}

Delete media

del/v1/media/{id}

Remove a media asset from the selected workspace library by ID. Hides it from library listings while preserving stored files and existing post attachments. Returns a deletion confirmation.

Path parameters

idstringrequired

Response 204

Deleted

Errors

401: Unauthenticated
403: Missing scope
404: Not found

Request

curl -X DELETE "https://api.posty.social/v1/media/$ID" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 204

No content

Complete media upload

post/v1/media/{id}/complete

Finalize a media upload after transferring its file bytes to the signed upload URL. Provide the media ID and optional dimensions or duration. Checks the uploaded object and storage quota, then returns finalized media metadata. Missing uploads or exceeded quotas produce errors.

Path parameters

idstringrequired

Request body

etagstring
widthinteger
heightinteger
durationinteger

Response 200

Media finalized (or already finalized)

idstringrequired
workspaceIdstringrequired
folderIdstringrequirednullable
titlestringrequired
thumbhashstringrequirednullable
Base64 ThumbHash (https://evanw.github.io/thumbhash/) of the thumbnail, for a blurred placeholder while it loads. Null until one has been computed.
sizeBytesintegerrequired
contentTypestringrequired
etagstringrequirednullable
statusstringrequired
One ofpendingprocessingreadyfaileddeduped
widthintegerrequirednullable
heightintegerrequirednullable
altTextstringrequirednullable
createdAtstring (date-time)requirednullable
updatedAtstring (date-time)requirednullable
durationintegerrequirednullable
urlstringrequirednullable
thumbnailUrlstringrequirednullable

Errors

401: Unauthenticated
403: Missing scope
404: Not found

Request

curl -X POST "https://api.posty.social/v1/media/$ID/complete" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "etag": "string",
  "width": 1,
  "height": 1,
  "duration": 1
}'

Response 200

{
  "id": "string",
  "workspaceId": "string",
  "folderId": "string",
  "title": "string",
  "thumbhash": "string",
  "sizeBytes": 1,
  "contentType": "string",
  "etag": "string",
  "status": "pending",
  "width": 1,
  "height": 1,
  "altText": "string",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "duration": 1,
  "url": "string",
  "thumbnailUrl": "string"
}

List media folders

get/v1/media-folders

List every media library folder in the workspace as a flat tree (parentId null is top level), with file counts. Needs media:view.

Response 200

Folders

dataarray of MediaFolderrequired

Errors

400: Invalid request
403: Missing permission
404: Media or folder not found
409: Name taken, cycle, or uploads still in progress

Request

curl "https://api.posty.social/v1/media-folders" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "data": [
    {
      "id": "string",
      "parentId": "string",
      "name": "string",
      "color": "red",
      "createdBy": "string",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z",
      "mediaCount": 1
    }
  ]
}

Create media folder

post/v1/media-folders

Create a media library folder, at the top level or inside parentId. Sibling names must be unique. Needs media:upload.

Request body

namestringrequired
Min length 1 · Max length 120 · Pattern ^[^/]*$
parentIdstringnullable
Min length 1

Response 201

Folder created

idstringrequired
parentIdstringrequirednullable
namestringrequired
colorstringrequirednullable
One ofredorangeyellowgreenbluepurplegrey
createdBystringrequirednullable
createdAtstring (date-time)required
updatedAtstring (date-time)required
mediaCountinteger
Files directly in this folder. Present on list and create.

Errors

400: Invalid request
403: Missing permission
404: Media or folder not found
409: Name taken, cycle, or uploads still in progress

Request

curl -X POST "https://api.posty.social/v1/media-folders" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "parentId": "string"
}'

Response 201

{
  "id": "string",
  "parentId": "string",
  "name": "string",
  "color": "red",
  "createdBy": "string",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "mediaCount": 1
}

Rename media folder

patch/v1/media-folders/{id}

Rename a media library folder. The new name must be unique among its siblings. Needs media:upload.

Path parameters

idstringrequired
Min length 1

Request body

namestringrequired
Min length 1 · Max length 120 · Pattern ^[^/]*$

Response 200

Folder renamed

idstringrequired
parentIdstringrequirednullable
namestringrequired
colorstringrequirednullable
One ofredorangeyellowgreenbluepurplegrey
createdBystringrequirednullable
createdAtstring (date-time)required
updatedAtstring (date-time)required
mediaCountinteger
Files directly in this folder. Present on list and create.

Errors

400: Invalid request
403: Missing permission
404: Media or folder not found
409: Name taken, cycle, or uploads still in progress

Request

curl -X PATCH "https://api.posty.social/v1/media-folders/$ID" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string"
}'

Response 200

{
  "id": "string",
  "parentId": "string",
  "name": "string",
  "color": "red",
  "createdBy": "string",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "mediaCount": 1
}

Delete media folder

del/v1/media-folders/{id}

Delete a folder, its subfolders, and remove every file inside them from the library. Files already attached to posts stay on those posts. Needs media:delete.

Path parameters

idstringrequired
Min length 1

Response 204

Folder deleted

Errors

400: Invalid request
403: Missing permission
404: Media or folder not found
409: Name taken, cycle, or uploads still in progress

Request

curl -X DELETE "https://api.posty.social/v1/media-folders/$ID" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 204

No content

Move media folder

post/v1/media-folders/{id}/move

Move a folder, with everything in it, under parentId or to the top level with null. A folder cannot move into itself or its descendants. Needs media:upload.

Path parameters

idstringrequired
Min length 1

Request body

parentIdstringrequirednullable
Min length 1

Response 200

Folder moved

idstringrequired
parentIdstringrequirednullable
namestringrequired
colorstringrequirednullable
One ofredorangeyellowgreenbluepurplegrey
createdBystringrequirednullable
createdAtstring (date-time)required
updatedAtstring (date-time)required
mediaCountinteger
Files directly in this folder. Present on list and create.

Errors

400: Invalid request
403: Missing permission
404: Media or folder not found
409: Name taken, cycle, or uploads still in progress

Request

curl -X POST "https://api.posty.social/v1/media-folders/$ID/move" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "parentId": "string"
}'

Response 200

{
  "id": "string",
  "parentId": "string",
  "name": "string",
  "color": "red",
  "createdBy": "string",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "mediaCount": 1
}

Set media folder color

put/v1/media-folder-colors

Tag up to 200 folders with one colour, or clear it with null. All or nothing: an unknown folder id fails the whole change. Needs media:upload.

Request body

folderIdsarray of stringrequired
Min items 1 · Max items 200
colorstringrequirednullable
One ofredorangeyellowgreenbluepurplegrey

Response 200

Folders updated

folderIdsarray of stringrequired

Errors

400: Invalid request
403: Missing permission
404: Media or folder not found
409: Name taken, cycle, or uploads still in progress

Request

curl -X PUT "https://api.posty.social/v1/media-folder-colors" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "folderIds": [
    "string"
  ],
  "color": "red"
}'

Response 200

{
  "folderIds": [
    "string"
  ]
}

Move media items

post/v1/media-moves

Move up to 200 library files into folderId, or to the top level with null. All or nothing: an unknown media id fails the whole move. Needs media:upload.

Request body

mediaIdsarray of stringrequired
Min items 1 · Max items 200
folderIdstringrequirednullable
Min length 1

Response 200

Files moved

movedintegerrequired

Errors

400: Invalid request
403: Missing permission
404: Media or folder not found
409: Name taken, cycle, or uploads still in progress

Request

curl -X POST "https://api.posty.social/v1/media-moves" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mediaIds": [
    "string"
  ],
  "folderId": "string"
}'

Response 200

{
  "moved": 1
}

Rename media

put/v1/media/{id}/title

Rename a library file (its display title, up to 500 characters). Needs media:upload.

Path parameters

idstringrequired
Min length 1

Request body

titlestringrequired
Min length 1 · Max length 500

Response 200

Renamed file

idstringrequired
workspaceIdstringrequired
folderIdstringrequirednullable
titlestringrequired
thumbhashstringrequirednullable
Base64 ThumbHash (https://evanw.github.io/thumbhash/) of the thumbnail, for a blurred placeholder while it loads. Null until one has been computed.
sizeBytesintegerrequired
contentTypestringrequired
etagstringrequirednullable
statusstringrequired
One ofpendingprocessingreadyfaileddeduped
widthintegerrequirednullable
heightintegerrequirednullable
altTextstringrequirednullable
createdAtstring (date-time)requirednullable
updatedAtstring (date-time)requirednullable
durationintegerrequirednullable
urlstringrequirednullable
thumbnailUrlstringrequirednullable

Errors

400: Invalid request
403: Missing permission
404: Media or folder not found
409: Name taken, cycle, or uploads still in progress

Request

curl -X PUT "https://api.posty.social/v1/media/$ID/title" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "string"
}'

Response 200

{
  "id": "string",
  "workspaceId": "string",
  "folderId": "string",
  "title": "string",
  "thumbhash": "string",
  "sizeBytes": 1,
  "contentType": "string",
  "etag": "string",
  "status": "pending",
  "width": 1,
  "height": 1,
  "altText": "string",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "duration": 1,
  "url": "string",
  "thumbnailUrl": "string"
}

Set media alt text

put/v1/media/{id}/alt-text

Set the accessibility description published with this file on platforms that support alt text, or clear it with null or an empty string. Up to 1000 characters. Needs media:upload.

Path parameters

idstringrequired
Min length 1

Request body

altTextstringrequirednullable
Max length 1000

Response 200

File with its alt text

idstringrequired
workspaceIdstringrequired
folderIdstringrequirednullable
titlestringrequired
thumbhashstringrequirednullable
Base64 ThumbHash (https://evanw.github.io/thumbhash/) of the thumbnail, for a blurred placeholder while it loads. Null until one has been computed.
sizeBytesintegerrequired
contentTypestringrequired
etagstringrequirednullable
statusstringrequired
One ofpendingprocessingreadyfaileddeduped
widthintegerrequirednullable
heightintegerrequirednullable
altTextstringrequirednullable
createdAtstring (date-time)requirednullable
updatedAtstring (date-time)requirednullable
durationintegerrequirednullable
urlstringrequirednullable
thumbnailUrlstringrequirednullable

Errors

400: Invalid request
403: Missing permission
404: Media or folder not found
409: Name taken, cycle, or uploads still in progress

Request

curl -X PUT "https://api.posty.social/v1/media/$ID/alt-text" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "altText": "string"
}'

Response 200

{
  "id": "string",
  "workspaceId": "string",
  "folderId": "string",
  "title": "string",
  "thumbhash": "string",
  "sizeBytes": 1,
  "contentType": "string",
  "etag": "string",
  "status": "pending",
  "width": 1,
  "height": 1,
  "altText": "string",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "duration": 1,
  "url": "string",
  "thumbnailUrl": "string"
}

Get media usage

get/v1/media/{id}/usage

List the posts and channels a library file is attached to, limited to posts the caller can see. Needs media:view.

Path parameters

idstringrequired
Min length 1

Response 200

Where the file is used

dataarray of objectrequired
Child attributes
- postIdstringrequired
- postContentIdstringrequired
- postStatusstringrequired
  One ofdraftpending_approvalpending_client_approvalapprovedscheduleddeliveredpartially_delivereddelivery_failed
- platformstringrequired
  One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube
- bodystringrequirednullable

Errors

400: Invalid request
403: Missing permission
404: Media or folder not found
409: Name taken, cycle, or uploads still in progress

Request

curl "https://api.posty.social/v1/media/$ID/usage" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "data": [
    {
      "postId": "string",
      "postContentId": "string",
      "postStatus": "draft",
      "platform": "bluesky",
      "body": "string"
    }
  ]
}

Get storage usage

get/v1/media-storage

Bytes the media library uses against the workspace plan's storage limit, and how many remain. limitBytes and remainingBytes are null on an unlimited plan. Needs media:view.

Response 200

Storage usage

usedBytesintegerrequired
limitBytesintegerrequirednullable
remainingBytesintegerrequirednullable
unlimitedbooleanrequired

Errors

400: Invalid request
403: Missing permission
404: Media or folder not found
409: Name taken, cycle, or uploads still in progress

Request

curl "https://api.posty.social/v1/media-storage" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "usedBytes": 1,
  "limitBytes": 1,
  "remainingBytes": 1,
  "unlimited": true
}

Models

Objects referenced by the endpoints above.

Media

idstringrequired
workspaceIdstringrequired
folderIdstringrequirednullable
titlestringrequired
thumbhashstringrequirednullable
Base64 ThumbHash (https://evanw.github.io/thumbhash/) of the thumbnail, for a blurred placeholder while it loads. Null until one has been computed.
sizeBytesintegerrequired
contentTypestringrequired
etagstringrequirednullable
statusstringrequired
One ofpendingprocessingreadyfaileddeduped
widthintegerrequirednullable
heightintegerrequirednullable
altTextstringrequirednullable
createdAtstring (date-time)requirednullable
updatedAtstring (date-time)requirednullable
durationintegerrequirednullable
urlstringrequirednullable
thumbnailUrlstringrequirednullable

MediaFolder

idstringrequired
parentIdstringrequirednullable
namestringrequired
colorstringrequirednullable
One ofredorangeyellowgreenbluepurplegrey
createdBystringrequirednullable
createdAtstring (date-time)required
updatedAtstring (date-time)required
mediaCountinteger
Files directly in this folder. Present on list and create.