/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Import Content

Import Content

Upload Markdown and MDX pages, images and config as a .zip or a folder, and publish them.

POST/v1/projects/{projectId}/content/importTry it
API key or session token

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.

Note

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

NameDescription
projectId:stringpathRequired
The project ID.

Request Body

Send multipart/form-data with either a .zip or a folder's files:

NameDescription
file:filebody
One .zip.
files:file[]body
A folder's files, one files 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.
paths:string[]body
The relative path of each files part.
mode:stringbody
replace — the upload becomes the whole project: files it doesn't contain are deleted (they stay in history). merge — only adds and overwrites.
Default"replace"
publish:stringbody
false to save the upload as a draft without publishing.
Default"true"

What's imported

•
Pages — .md and .mdx, UTF-8, up to 1 MB each.
•
Config — 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.
•
Images — PNG, JPEG, GIF, WebP and SVG, up to 5 MB each; an SVG up to 512 KB. Each is checked against its extension, and SVGs are sanitised.

The layout is read the way the CLI reads a project:

•
One folder wrapping everything (the ZIP of a folder) is removed.
•
Pages in docs/ move to the top level when the top level has none.
•
Images in 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

LimitValue
Upload size50 MB
Unpacked size100 MB
Files per upload2,000
Files per project, after the import2,000
Project size, after the import200 MB
Imports at a time, per project1
Imports per workspace30 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

CodeWhen
validation_errorNot multipart/form-data, no file or files, or a mode other than replace or merge
no_pagesThe upload has no .md or .mdx pages. details.skipped lists up to 20 skipped files
invalid_zipThe file isn't a ZIP archive, or it's damaged
zip_unsupportedA ZIP64 archive, or an unsupported compression method
zip_symlinkThe archive contains a symbolic link. details.path names it
zip_encryptedThe archive is password-protected
zip_bombA 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

CodeWhen
payload_too_largeThe request is over 50 MB
zip_too_largeOver 2,000 files, over 100 MB unpacked, or one entry over 5 MB
too_many_filesThe project would hold more than 2,000 files
content_too_largeThe 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.

Was this page helpful? Yes No
Request
A .zipA folderJavaScriptPythonGoRubyPHPJavaC#A .zip
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/content/import \
-H "Authorization: Bearer stx_A1b2C3d4_..." \
-F "file=@docs.zip"
Responseapplication/json
201Created
{
"data": {
"revision": { "id": "5b0f9c1e-7a2d-4e8b-9c3f-1d6a8e2b4c70", "number": 1 },
"files": { "pages": 18, "config": 1, "images": 6, "deleted": 0 },
"skipped": [
{ "path": ".DS_Store", "reason": "hidden or system file" },
{ "path": "mint.json", "reason": "converted to syntext.json" },
{ "path": "videos/demo.mp4", "reason": "Hosted projects hold .md, .mdx, .json and .yaml files and png, jpg, gif, svg and webp images." }
],
"warnings": ["Converted mint.json to syntext.json."],
"converted": "mint.json",
"contentSource": "hosted",
"publish": { "build": { "id": "b7d2e9a4-1c3f-4b8e-9a6d-2f5c8e1b4a70", "status": "queued" }, "revision": { "id": "5b0f9c1e-7a2d-4e8b-9c3f-1d6a8e2b4c70", "number": 1 } }
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext