Media

Jason Lee

There are two ways to upload media through the API: inline with a page request, or as a standalone upload.

Inline media

When creating pages with POST /pages, you can attach files directly to the request using multipart form data. Reference them in your markdown content with the file: prefix, and the server replaces each reference with the final media URL before saving.

Request

Send Content-Type: multipart/form-data with:

• A payload field containing the JSON body
• One or more file parts

curl -X POST https://sitepaste.com/api/v1/public/pages \
  -H "Authorization: Bearer $TOKEN" \
  -F payload='{"pages": [{"title": "Beach day", "content": "Great sunset.\n\n![sunset](file:sunset.jpg)\n\nDownload the [album](file:album.zip)"}]}' \
  -F files=@sunset.jpg \
  -F files=@album.zip

The file:sunset.jpg reference matches the filename from the file part and is replaced with the uploaded media URL.

A single file can be referenced by multiple pages. Each reference resolves to the same URL.

Limits

Free plans: each file must be 10 MB or smaller. Up to 500 files per request.

Paid plans: files up to 10 GB each. Up to 500 files per request. Large files (over 10 MB) are streamed to disk during processing and do not consume server memory.

Requests with many small files are handled efficiently regardless of the total count.

Processing

Images (JPEG, PNG, GIF, WebP) are compressed to WebP format. Video metadata is stripped for privacy. MOV files are queued for MP4 transcoding. PDF metadata is stripped.

Response

When files are uploaded, the response includes a media array:

{
  "pages": [...],
  "media": [
    {"filename": "sunset.jpg", "url": "/media/.../a1b2c3d4.webp"},
    {"filename": "album.zip", "url": "/media/.../e5f6a7b8.zip"}
  ]
}

Errors

If a file: reference in the content does not match any attached file, the request is rejected:

{
  "error": "unresolved file references",
  "details": {
    "0": {"unresolvedCount": 1}
  }
}

The key is the page index. Check that the filename in your content matches the filename of the attached file exactly.

POST /media

Upload a standalone file outside of a page request. Useful when you want to upload media separately and reference the URL directly in your content.

Request

curl -X POST https://sitepaste.com/api/v1/public/media \
  -H "Authorization: Bearer $TOKEN" \
  -F file=@photo.jpg

Response

200 OK

{
  "url": "/media/.../f8e2a1b3c4d5.webp",
  "filename": "f8e2a1b3c4d5.webp"
}

Use the url value directly in your page content:

![Photo](/media/.../f8e2a1b3c4d5.webp)

Limits

Free plans: 10 MB per file. Paid plans: 10 GB per file.

Large file uploads are rate-limited to 2 concurrent uploads and 10 per hour per workspace. The server also limits total concurrent large uploads across all users. If the server is busy, you will receive a 503 response; retry after a few seconds.

Supported file types

Images: .jpg, .jpeg, .png, .gif, .webp

Documents: .pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .txt, .csv, .md

Archives: .zip

Audio: .mp3

Video: .mp4, .webm, .mov

Both the file extension and the actual file content are validated. A file with a mismatched extension and content type will be rejected.

Storage quota

Your plan includes a storage quota. If an upload would exceed your remaining storage, the request is rejected with 402:

{
  "error": "storage quota exceeded",
  "message": "Upload requires 15 MB but only 3 MB of storage remains"
}

You can free up space by deleting media from the dashboard.