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 403 with API_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:

shell
export MDSHARE_API_KEY="mds_EXAMPLE-not-a-real-key"
header
Authorization: Bearer $MDSHARE_API_KEY

Create a share

POST /api/v1/shares

curl
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, so Notes.md and notes.md are 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, so notes or data.json is 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 send null for a share that never expires; the website’s editor suggests 30 days instead.
burnAfterReading
Optional boolean, false by default. When true, the share can be opened only once.
hideWordmark
Optional boolean, false by default. With the key owner’s current canHideBranding permission, true opts 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 letter a–z, a digit or a hyphen, not starting or ending with a hyphen. Some names are reserved, such as support, pricing and security, and so is any link that contains mdshare once its hyphens are removed. null and "" 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 (see CUSTOM_SLUG_UNAVAILABLE below).
  • Markdown links between files in one share, such as [the details](details.md), work only when the file names end in .md, .markdown or .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:

json
{
  "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:

shell
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
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.

json
{
  "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}.
isCustomSlug
true for a custom link.
hideWordmark
The stored per-share choice, not the current permission to hide the header wordmark. Default false; an existing true is 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. null for password-protected shares made on the web.
createdAt, expiresAt
ISO 8601 timestamps. expiresAt is null when the share never expires.
viewCount, fileCount
How often the share was opened, and how many files it holds.
passwordProtected
Always false for shares created through the API.
unavailable
true when the share was burned after reading, has expired, or was removed after a legal request.
canDelete
false for 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
curl -X DELETE https://www.mdshare.online/api/v1/shares/aB3dE5fG7hJ9kL1mN3pQ5 \
  -H "Authorization: Bearer $MDSHARE_API_KEY"

A deleted share answers 200:

json
{
  "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-Remaining and X-RateLimit-Reset (Unix time in milliseconds); a 429 adds Retry-After in 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 413 that 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.

json
{
  "code": "SHARE_NOT_FOUND",
  "error": "Share not found"
}

Any request

INVALID_API_KEYHTTP 401
The Authorization header 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-After seconds.
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, even false or null.
INVALID_BURN_AFTER_READINGHTTP 400
burnAfterReading is not a boolean.
INVALID_HIDE_WORDMARKHTTP 400
hideWordmark is not a boolean; null is refused too.
HIDE_WORDMARK_NOT_ALLOWEDHTTP 403
The key owner does not have permission to hide the MDShare header wordmark.
INVALID_EXPIRATIONHTTP 400
expiresAt is not a valid date in the future.
INVALID_CUSTOM_SLUGHTTP 400
customSlug breaks 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 400
files is not an array, or a file lacks a unique, non-blank name of at most 255 characters or string content.
INVALID_FILE_COUNTHTTP 400
files is 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) and retryAt.
SHARE_CREATE_UNAVAILABLEHTTP 503
A brief conflict. Retry after Retry-After seconds.
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.