Skip to content

List media

GET /public/v1/media

Returns the images and videos already in your media library, so a post can reuse one instead of uploading it again. Each file carries the id and path that create a post needs, the same pair upload a file and upload from a URL return.

Doing this in the app? See the media library. Also available as mediaListTool (MCP); the CLI has no command for it.

Parameter Required Description
page No Page number, starting at 1. Defaults to 1. Must be 1 or greater.
search No Part of a file’s original name. Case does not matter.

page starts at 1 here, unlike list notifications, which starts at 0, so page=0 is refused.

First page:

Terminal window
curl -H "Authorization: your-api-key" \
https://dash.sharek.app/api/public/v1/media

Second page of the files whose original name contains logo:

Terminal window
curl -H "Authorization: your-api-key" \
"https://dash.sharek.app/api/public/v1/media?page=2&search=logo"
{
"pages": 3,
"results": [
{
"id": "media-id",
"name": "a1b2c3d4e5.png",
"originalName": "launch-logo.png",
"path": "https://media.example.com/a1b2c3d4e5.png",
"createdAt": "2026-09-01T10:00:00.000Z"
}
]
}
Field Description
pages How many pages there are in total, counting only the files that match search.
results The page of files, newest first, up to 32.
id The media id, for the post’s image array.
name The generated name Sharek stored the file under.
originalName The file’s own name when you uploaded it in the app. null when none was kept, which is every file uploaded over the API.
path The file’s address, for the post’s image array.
createdAt When the file was added.

Unlike the upload responses, a listed file carries no thumbnail or alt.

To reuse a file, take its id and path into the post’s image array:

"image": [ { "id": "media-id", "path": "https://media.example.com/a1b2c3d4e5.png" } ]
Response Meaning
400 field validation page is below 1, or not a number.
  • 32 files a page, newest first. The page size is fixed; there is no limit parameter.
  • A search never finds a file uploaded over the API. search looks at originalName only, not the stored name, and those files keep no original name. To find one again, keep the id its upload returned, or page through without search.
  • Page beyond the end and you get an empty results array, not an error. Stop once page reaches pages.
  • Deleted files are left out.
  • To check one file, GET /public/v1/media/:id/status with its media id returns that file’s id, path and status, or 404 Media not found when the id is not in your library.
  • This call is not throttled; only creating posts is (see rate limits).