POST/api/v1/files/uploads

Start a file upload

Starts publishing a file of any size: send its name, size and SHA-256, and get back presigned URLs to PUT each part to. Then finish the upload. With target_slug, the file replaces the one behind an existing link instead, keeping the link, its access and its views.

The CLI does all of this, with resume, in one command.

API token required30 per minute per IPMCP: create_upload CLI: markdrop upload

Guide: Large uploads

Code samples and Try it

Request body

application/json, required

file_namestringRequired
The file's name, with its extension. 1–255 characters.
size_bytesintegerRequired
The file's exact size in bytes. At least 1.
content_typestring
Up to 255 characters. Default "".
sha256stringRequired
The SHA-256 of the whole file, in hex. The server checks it before the file goes live. Matches ^[0-9a-fA-F]{64}$.
target_slugstring
Replace the file behind this existing address instead of publishing a new one. The link, access and views stay. Matches ^[A-Za-z0-9_-]{1,64}$.
titlestring
Shown on the page and in link previews. Up to 200 characters.
access"link" | "private" | "password" | "workspace"
Who can open it: link, private, password (needs password) or workspace (needs workspace).
passwordstring
1–100 characters.
workspacestring
File it in this workspace: the workspace's id. 1–64 characters.
folderstring
An existing folder of workspace: its id or its path, like guides/setup. 1–400 characters.
slugstring
Your own address: markdrop.in/<slug>. 3–50 characters. Matches ^[a-zA-Z0-9_-]+$.

Responses

200OK.
401No token, or the token is revoked or mistyped.
409The address you asked for is taken, or reserved.
413The file is over the size limit for its type.
422The request didn't validate. detail lists each problem, with where it is (loc) and why (msg).
429Too many requests from your IP address. Wait the seconds in Retry-After.
507Your storage is full.

200 response: 4 fields (UploadSessionResponse)

upload_idstring
part_sizeinteger
partsarray of object
2 fields inside
- part_numberinteger
- urlstring
expires_atstring (date-time)
ISO 8601, for example 2026-11-30T12:00:00Z.

curl -X POST https://api.markdrop.in/api/v1/files/uploads \ -H "Authorization: Bearer $MARKDROP_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "file_name": "deck.pdf", "size_bytes": 1048576, "sha256": "SHA256_OF_THE_FILE", "title": "Q3 deck" }'

const res = await fetch("https://api.markdrop.in/api/v1/files/uploads", { method: "POST", headers: { Authorization: `Bearer ${process.env.MARKDROP_TOKEN}`, "Content-Type": "application/json", }, body: JSON.stringify({ "file_name": "deck.pdf", "size_bytes": 1048576, "sha256": "SHA256_OF_THE_FILE", "title": "Q3 deck" }), }); const data = await res.json();

import os import requests r = requests.post( "https://api.markdrop.in/api/v1/files/uploads", headers={"Authorization": f"Bearer {os.environ['MARKDROP_TOKEN']}"}, json={ "file_name": "deck.pdf", "size_bytes": 1048576, "sha256": "SHA256_OF_THE_FILE", "title": "Q3 deck", }, ) r.raise_for_status() print(r.json())