Import Content
Upload Markdown and MDX pages, images and config as a .zip or a folder, and publish them.
Upload a project's files — one .zip, or the files of a folder — as one revision, then publish it. This is the dashboard's Upload files. See Upload Markdown for the walkthrough.
Any workspace member (session JWT), or an API key bound to this project with the full scope. Works on a project written in Syntext, and on one published with stx deploy — which then becomes written in Syntext. A GitHub project returns 409 content_source_github.
Path Parameters
projectIdRequest Body
Send multipart/form-data with either a .zip or a folder's files:
file.zip.filesfiles part each. Send a paths part for each, in the same order, with its path relative to the folder — e.g. guides/quickstart.mdx. A file with no path uses its name.pathsfiles part.modereplace — the upload becomes the whole project: files it doesn't contain are deleted (they stay in history). merge — only adds and overwrites."replace"publishfalse to save the upload as a draft without publishing."true"What's imported
.md and .mdx, UTF-8, up to 1 MB each.syntext.json (or .yaml). With no Syntext config, a Mintlify mint.json or docs.json is converted to syntext.json; the response says so in converted and warnings. With neither, the sidebar lists pages by folder.The layout is read the way the CLI reads a project:
docs/ move to the top level when the top level has none.public/ move to the path they're served from: public/images/logo.png becomes images/logo.png.Hidden files, __MACOSX, node_modules and anything that isn't a page, config or image are skipped and listed in skipped with the reason — as are duplicate paths, names that aren't allowed (starting with a dot, or with control characters), pages that aren't UTF-8 or are over 1 MB, and images over their size limit or that don't match their extension.
Limits
| Limit | Value |
|---|---|
| Upload size | 50 MB |
| Unpacked size | 100 MB |
| Files per upload | 2,000 |
| Files per project, after the import | 2,000 |
| Project size, after the import | 200 MB |
| Imports at a time, per project | 1 |
| Imports per workspace | 30 an hour |
Response — 201 Created
revision — the import's revision, or null when the upload matched the project exactly.files — pages, config files and images written, and files deleted (replace only).publish — present when the import was published. When the publish couldn't start, build is null and skipped says why, e.g. { "code": "USAGE_LIMIT_EXCEEDED", "current": 100, "limit": 100 }. The files are saved either way: publish later with Publish Content.Error Responses
Nothing is written when an import is refused.
400 Bad Request
| Code | When |
|---|---|
validation_error | Not multipart/form-data, no file or files, or a mode other than replace or merge |
no_pages | The upload has no .md or .mdx pages. details.skipped lists up to 20 skipped files |
invalid_zip | The file isn't a ZIP archive, or it's damaged |
zip_unsupported | A ZIP64 archive, or an unsupported compression method |
zip_symlink | The archive contains a symbolic link. details.path names it |
zip_encrypted | The archive is password-protected |
zip_bomb | A file expands far more than a document would |
409 Conflict
import_in_progress — another import into this project is still running. Wait for it to finish, then try again.content_source_github — the project is written in its GitHub repository. Commit the files there, or disconnect GitHub first.413 Payload Too Large
| Code | When |
|---|---|
payload_too_large | The request is over 50 MB |
zip_too_large | Over 2,000 files, over 100 MB unpacked, or one entry over 5 MB |
too_many_files | The project would hold more than 2,000 files |
content_too_large | The project would be larger than 200 MB |
429 Too Many Requests
rate_limited — the workspace has imported 30 times in the last hour. Wait a while and try again.