API documentation
With a Premium plan, your scripts, CI pipelines and other tools can create, list and delete your shares. Requests and responses are JSON over HTTPS, authenticated with an API key.
Before you start
- Create a key on your Account page. An account can hold up to 5 keys. The full key is shown once, when you create it.
- A key is a password for your account’s shares. Keep it out of source control: store it in your CI’s secret settings or an environment variable. If a key leaks, revoke it on your Account page; it stops working at once.
- Shares created through the API are stored unencrypted, like web shares without a password. Password protection is not available through the API, because MDShare encrypts in the browser and your password never reaches our server.
- Keys work only while your plan includes the API. After a downgrade or a lapse, requests get
403withAPI_NOT_ALLOWED; you can still revoke the keys.
Authentication
Send the key in an Authorization header on every request. Keys are never accepted in a URL or a cookie. The examples read the key from an environment variable:
export MDSHARE_API_KEY="mds_EXAMPLE-not-a-real-key"Authorization: Bearer $MDSHARE_API_KEYCreate a share
POST /api/v1/shares
curl -X POST https://www.mdshare.online/api/v1/shares \
-H "Authorization: Bearer $MDSHARE_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"files": [
{
"name": "notes.md",
"content": "# Release notes\n\nSee [the details](details.md)."
},
{
"name": "details.md",
"content": "# Details\n\nShipped from CI."
}
],
"expiresAt": null,
"burnAfterReading": false,
"hideWordmark": false
}'files- Required. An array of 1 to 10 files, each
{ "name": string, "content": string }. Content is your markdown, sent as is. Names must be unique and non-blank (compared exactly, soNotes.mdandnotes.mdare two names, although links between files ignore case and a link to either opens the first of them; a name of only spaces is blank), at most 255 characters (counted as UTF-16 code units, so most emoji count as two or more). Names are kept exactly as you send them: no extension is required or added, sonotesordata.jsonis accepted as given. Files keep the order you send. expiresAt- Optional. An ISO 8601 date in the future, such as
"2030-01-31T12:00:00Z", at the latest"9999-12-31T23:59:59.999Z". Omit it or sendnullfor a share that never expires; the website’s editor suggests 30 days instead. burnAfterReading- Optional boolean,
falseby default. Whentrue, the share can be opened only once. hideWordmark- Optional boolean,
falseby default. With the key owner’s currentcanHideBrandingpermission,trueopts this share into hiding only the MDShare header wordmark on its reader page. Other links, controls and the tab title stay. The wordmark returns if the owner loses permission. customSlug- Optional, part of Premium. A custom link, so the share opens at
/s/{customSlug}instead of a random link. It is used exactly as sent, never trimmed or lowercased: 3 to 60 characters, each a lowercase lettera–z, a digit or a hyphen, not starting or ending with a hyphen. Some names are reserved, such assupport,pricingandsecurity, and so is any link that containsmdshareonce its hyphens are removed.nulland""are refused, not read as “random”: omit the field for a random link. Anyone who sees the URL can read the link, so keep private details out of it. A link given up by another account is free again 30 days later (seeCUSTOM_SLUG_UNAVAILABLEbelow).
- Markdown links between files in one share, such as
[the details](details.md), work only when the file names end in.md,.markdownor.txt. A link to a file named any other way, such as[the data](data.json), is treated as a link to another web page: it opens in a new tab at an address beside the share’s, which can be a different MDShare share, and does not reach the file. Name files with one of these endings if they link to each other. - Each new share counts toward your monthly quota, including shares you later delete.
A new share answers 201:
{
"slug": "aB3dE5fG7hJ9kL1mN3pQ5",
"editCode": "EXAMPLE-edit-code-not-a-real-one",
"url": "https://www.mdshare.online/s/aB3dE5fG7hJ9kL1mN3pQ5",
"createdAt": "2026-11-11T09:30:00.123456+00:00"
}The editCode lets anyone edit or delete the share on the web. Keep it private, like the key.
Send a file from disk
With jq, the file’s text is escaped as JSON for you. This example also makes the share open only once:
jq -n --rawfile content README.md \
'{files: [{name: "README.md", content: $content}], burnAfterReading: true}' |
curl -X POST https://www.mdshare.online/api/v1/shares \
-H "Authorization: Bearer $MDSHARE_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @-List your shares
GET /api/v1/shares?page=1
curl "https://www.mdshare.online/api/v1/shares?page=1" \
-H "Authorization: Bearer $MDSHARE_API_KEY"Your shares, newest first, 20 to a page. When hasNext is true, ask for the next page. Listing never counts a view and never opens a burn-after-reading share. usage is the number of shares created in this billing month, and entitlements describes your plan. Share content and edit codes are never listed. entitlements.canHideBranding is your current permission to hide the header wordmark, separately from each share’s stored choice.
{
"page": 1,
"hasNext": false,
"usage": 12,
"entitlements": {
"plan": "premium",
"shareLimit": 1000,
"window": {
"type": "billing-month",
"start": "2026-11-03T08:15:00.000Z",
"end": "2026-12-03T08:15:00.000Z"
},
"canNeverExpire": true,
"canCustomLink": true,
"canHideBranding": true
},
"shares": [
{
"slug": "aB3dE5fG7hJ9kL1mN3pQ5",
"isCustomSlug": false,
"hideWordmark": false,
"title": "notes.md",
"createdAt": "2026-11-11T09:30:00.123456+00:00",
"expiresAt": null,
"viewCount": 3,
"fileCount": 2,
"passwordProtected": false,
"unavailable": false,
"canDelete": true
}
]
}slug- The share’s link is
/s/{slug}. isCustomSlugtruefor a custom link.hideWordmark- The stored per-share choice, not the current permission to hide the header wordmark. Default
false; an existingtrueis kept after plan loss but cannot hide the wordmark without current permission. title- The first file’s name, trimmed and cut to 120 Unicode code points (most emoji count as one), or the slug.
nullfor password-protected shares made on the web. createdAt, expiresAt- ISO 8601 timestamps.
expiresAtisnullwhen the share never expires. viewCount, fileCount- How often the share was opened, and how many files it holds.
passwordProtected- Always
falsefor shares created through the API. unavailabletruewhen the share was burned after reading, has expired, or was removed after a legal request.canDeletefalsefor burned and expired shares, which cannot be deleted through the API. Removed shares can still be deleted.
Delete a share
DELETE /api/v1/shares/{slug}
curl -X DELETE https://www.mdshare.online/api/v1/shares/aB3dE5fG7hJ9kL1mN3pQ5 \
-H "Authorization: Bearer $MDSHARE_API_KEY"A deleted share answers 200:
{
"success": true
}Only your own shares can be deleted. A share that does not exist, belongs to another account, was burned after reading or has expired answers 404 with SHARE_NOT_FOUND. Deleting does not give back quota.
Limits
- 60 requests a minute per key, across creating, listing and deleting, in fixed one-minute windows. Responses to requests with a working key carry
X-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Reset(Unix time in milliseconds); a429addsRetry-Afterin seconds. - Premium’s fair-use limit of 1,000 new shares per billing month, shared with shares you create on the web. It resets monthly, also on yearly billing.
- Up to 10 files per share. Each file’s content can be up to 1 MiB (1,048,576 bytes) once encoded as UTF-8. The whole share can be up to 5 MiB (5,242,880 bytes), counted as the UTF-8 length of the JSON MDShare stores: file names and JSON escaping count too, so a newline or a quote takes two bytes. Our host documents a limit of 4.5 MB per request body: larger requests are refused before they reach MDShare, with a
413that is not JSON, so in practice a share stays below the full 5 MiB.
Errors
Errors answer with a stable code and an English error message. Match on the code; the message may change.
{
"code": "SHARE_NOT_FOUND",
"error": "Share not found"
}Any request
INVALID_API_KEYHTTP 401- The
Authorizationheader is missing or malformed, or the key is unknown or revoked. API_NOT_ALLOWEDHTTP 403- The key’s account no longer includes the API, for example after a downgrade or a lapse.
RATE_LIMIT_EXCEEDEDHTTP 429- The key has used its 60 requests for this minute. Wait for
Retry-Afterseconds. RATE_LIMIT_UNAVAILABLEHTTP 503- The rate limiter is unavailable, so the request was refused. Try again later.
API_KEY_AUTH_UNAVAILABLEHTTP 503- The key could not be checked. Try again later.
INTERNAL_ERRORHTTP 500- Something unexpected failed.
Create
INVALID_REQUESTHTTP 400- The body is not a JSON object.
PASSWORD_PROTECTION_NOT_SUPPORTEDHTTP 400- The body has a field whose name starts with
password, evenfalseornull. INVALID_BURN_AFTER_READINGHTTP 400burnAfterReadingis not a boolean.INVALID_HIDE_WORDMARKHTTP 400hideWordmarkis not a boolean;nullis refused too.HIDE_WORDMARK_NOT_ALLOWEDHTTP 403- The key owner does not have permission to hide the MDShare header wordmark.
INVALID_EXPIRATIONHTTP 400expiresAtis not a valid date in the future.INVALID_CUSTOM_SLUGHTTP 400customSlugbreaks the link rules or is reserved.CUSTOM_SLUG_UNAVAILABLEHTTP 409- That custom link is unavailable: a share still has it (yours too, even burned or expired until the daily cleanup), or another account gave it up less than 30 days ago. A link is given up when its share is deleted, renamed or cleaned up, and the account that gave it up can take it again at once. Choose another.
CUSTOM_LINK_NOT_ALLOWEDHTTP 403- The plan does not include custom links.
INVALID_FILESHTTP 400filesis not an array, or a file lacks a unique, non-blank name of at most 255 characters or string content.INVALID_FILE_COUNTHTTP 400filesis empty.PLAN_FILE_LIMITHTTP 400- More than 10 files.
FILE_TOO_LARGEHTTP 400- A file’s content is larger than 1 MiB: more than 1,048,576 bytes of UTF-8.
CONTENT_TOO_LARGEHTTP 400- The stored share would be larger than 5 MiB: more than 5,242,880 bytes of UTF-8 JSON.
PLAN_LIMIT_REACHEDHTTP 429- This billing month’s shares are used up. The body adds
plan,retryAfter(seconds) andretryAt. SHARE_CREATE_UNAVAILABLEHTTP 503- A brief conflict. Retry after
Retry-Afterseconds. SHARE_CREATE_FAILEDHTTP 500- The share could not be saved. Try again.
List
ACCOUNT_SHARES_UNAVAILABLEHTTP 503- Your shares cannot be read right now. Try again later.
Delete
SHARE_NOT_FOUNDHTTP 404- No live share with that slug belongs to this account. Burned and expired shares give this answer too.
SHARE_DELETE_FAILEDHTTP 500- The share could not be deleted. Try again.