Skip to content

Upload a file

POST /public/v1/upload

Uploads media to your library and returns the id and path that create a post needs. Every post with media starts here, because media cannot travel inside a post’s JSON body.

Doing this in the app? See the media library. Also available as sharek upload (CLI) and uploadWidgetTool (MCP), which shows an upload box in your AI tool’s conversation.

multipart/form-data with a single field named file:

Terminal window
curl -X POST https://dash.sharek.app/api/public/v1/upload \
-H "Authorization: your-api-key" \
-F "file=@/path/to/photo.jpg"

Do not set Content-Type yourself. Let your HTTP client set the multipart boundary.

The media row:

{
"id": "media-id",
"name": "a1b2c3d4e5.jpg",
"originalName": null,
"path": "https://media.example.com/a1b2c3d4e5.jpg",
"thumbnail": null,
"alt": null,
"status": "ready"
}

Take id and path into the post’s image array:

"image": [ { "id": "media-id", "path": "https://media.example.com/a1b2c3d4e5.jpg" } ]

status reads ready, so the file can go into a post straight away. To read it again later, GET /public/v1/media/:id/status with the media id returns that file’s id, path and status, or 404 Media not found when the id is not in your library.

The type is detected from the file’s actual bytes, not from its name or the Content-Type you send, so renaming a file will not get it past this.

Kind Types Maximum size
Images JPEG, PNG, GIF, WebP, AVIF, BMP, TIFF 10 MB
Video MP4 1 GB

Anything else is refused. AVIF, BMP and TIFF files are stored, but create a post only takes paths ending .png, .jpg, .jpeg, .gif, .webp or .mp4, so convert those to JPEG, PNG or WebP first if they are going into a post. Note the list is what Sharek stores; an individual platform may still reject a format it does not support when the post publishes.

Sharek stores the file under a generated name with the detected extension, and that is the name you get back. Your filename is not kept, so originalName is null.

Response Meaning
400 {"msg": "No file provided"} No file field in the request. Check the field name.
400 Unsupported file type. The bytes are not one of the accepted types.
400 File is too large. Over the cap for its type.
400 Failed to read file Sharek could not read the start of the file to detect its type. Send it again.

The first comes back as {"msg": ...}. The other three come back in the standard shape, {"statusCode": 400, "message": "File is too large.", "error": "Bad Request"}.

  • Uploading is not throttled. Only create a post is.
  • Uploaded media stays in your media library and can be reused across posts. To reuse an existing upload, list media returns its id and path again.
  • If the file is already on a public HTTPS URL, use upload from a URL and skip the download.