On this page
Images and assets
Images, diagrams, PDFs, and downloads are uploaded through the API and served from /assets/<path> on your site's hostname.
Assets are shared across all versions of a site. Upload images and downloads separately: the folder push script sends Markdown only.
Uploading
The upload endpoint takes the file as a raw request body. The path is the URL path, given after /assets/:
curl -s -X POST "$DOCSARY_API/v1/sites/acme/assets/img/architecture.png" \
-H "authorization: Bearer $DOCSARY_KEY" \
-H "content-type: image/png" \
--data-binary @architecture.png
{ "path": "img/architecture.png", "size": 48213, "sha256": "9f2c..." }
Set content-type explicitly. It is stored verbatim and served back on every request for that asset. When the header is missing, the asset is stored as application/octet-stream, and browsers will download it instead of displaying it. curl will not guess for you.
Posting to a path that already exists replaces the object and updates its recorded size and hash.
Referencing from markdown
*The request path, end to end.*
Images fit the content width. Add a caption as italic text below the image; raw HTML captions are not supported. See HTML in Markdown.
Always reference assets by absolute path. Relative image paths are emitted verbatim and will break on any page that is not at the depth you assumed.
Constraints
| Constraint | Value |
|---|---|
| Maximum size | 20 MB per asset (413 above that) |
| Total storage | Your organization's asset storage ceiling (413) |
| Path characters | letters, digits, ., _, -, / |
| Path start | must begin with a letter or digit |
| Path traversal | .. anywhere in the path is rejected |
| Empty body | rejected with 400 |
Compress and size images before uploading. Docsary does not resize, convert, or generate thumbnails or responsive image variants.
Caching and filenames
Give changed assets new filenames so readers can distinguish each revision:
/assets/img/architecture-9f2c1a.png
/assets/img/architecture-4d81e7.png
Upload the new file first, then update and push the Markdown. Keep the old file while any retained version still references it.
Assets use cache-control: public, max-age=60, s-maxage=31536000. A browser may retain an older response briefly, and previously saved offline copies can remain older. A publish cannot recall a downloaded copy.
Listing and deleting
curl -s -H "authorization: Bearer $DOCSARY_KEY" \
"$DOCSARY_API/v1/sites/acme/assets"
{
"assets": [
{ "path": "img/architecture.png", "content_type": "image/png", "size": 48213, "sha256": "9f2c..." }
]
}
curl -s -X DELETE "$DOCSARY_API/v1/sites/acme/assets/img/architecture.png" \
-H "authorization: Bearer $DOCSARY_KEY"
Check references in every version before deleting an asset. Deletion can leave broken images. A 503 with cleanup: "pending" means the URL is removed but storage cleanup is incomplete; retry the same delete. See Assets API.
Site deletion also removes access to its assets. Export the Markdown and save the asset files separately before deleting; Markdown exports do not include assets, and there is no undo.