Upload a file
POST /public/v1/uploadUploads 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.
Request
Section titled “Request”multipart/form-data with a single field named file:
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.
Response
Section titled “Response”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.
Accepted files
Section titled “Accepted files”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.
Errors
Section titled “Errors”| 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
idandpathagain. - If the file is already on a public HTTPS URL, use upload from a URL and skip the download.