Skip to content

Upload content ​

There are two ways to put files on a deployment. Neither one changes the live site. Commit publishes a preview; promote is the step that moves live traffic. If you do not have a distribution yet, start with Publish your first site.

The exact numbers are on Limits.

Where you can do this ​

Uploading is not available in the web console. The console lists deployments so you can see which one is live. Use an agent, the CLI, or the API.

Write text inline ​

Use this when every file is text, each file is at most 100,000 bytes, and you are patching a deployment that already exists.

text
Branch a new deployment from the live one on acme-marketing and write
the new about.html. Do not upload a bundle, and do not promote yet.
bash
edge deployments create --distribution d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38 --from 01M2QB6JJJS99B7B09VZJ8RST2
# then write onto the new pending deployment id:
edge api PUT /v1/deployments/01M2QF4XK7T0N8MB2VD31HGA9C/content --input - <<'EOF'
{ "objects": [{ "path": "about.html", "content": "<!doctype html>…" }] }
EOF
bash
curl -s -X POST \
  https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/deployments \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "from_deployment": "01M2QB6JJJS99B7B09VZJ8RST2" }'

curl -s -X PUT \
  https://api.edge.deca-dev.com/v1/deployments/01M2QF4XK7T0N8MB2VD31HGA9C/content \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "objects": [{ "path": "about.html", "content": "<!doctype html>…" }] }'

The agent runs edge_deployment_create with from_deployment, then edge_content_write. The API route is PUT /v1/deployments/{id}/content.

The response is a success even when some files do not fit. Each item in results is written or error. Items already written stay written.

  • call total exceeds 2000000 bytes, and the failed file itself is under 100,000 bytes: send only the failed paths again, in a smaller call.
  • object exceeds 100000 bytes, or one file that alone returns the call-total error: stop. That file cannot be written here, and splitting it across calls will not help. Upload a bundle instead. A binary file takes the same path.

Upload a bundle ​

Use this for a first publish, a full rebuild, a binary, or any file over the inline cap. The archive is the whole site, not only the new file. Omit from_deployment.

text
Create a new deployment on acme-marketing without branching from the
live one, upload ./dist as a gzip tar, and give me the preview URL.
Do not promote it yet.
bash
edge deploy ./dist --distribution d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38
bash
curl -s -X POST \
  https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/deployments \
  -H "Authorization: Bearer $EDGE_TOKEN"

COPYFILE_DISABLE=1 tar -czf ../bundle.tar.gz -C ./dist .
curl -s -X PUT --upload-file ../bundle.tar.gz "$UPLOAD_URL"

Opening the deployment returns upload_url. The agent runs edge_deployment_create and PUTs the archive to that URL. The URL looks like an S3 address and is valid for one hour (3,600 seconds). After it expires, open another deployment; do not reuse the old URL.

PUT the gzip tar as-is. Do not set Content-Type, and do not send encryption headers. The archive must be .tar.gz, never .zip, with the site files at the root (index.html at the top, not under dist/). -C ./dist . does that.

The PUT goes straight to S3. It does not pass through the MCP server or the HTTP API, so the firewall in front of those hosts does not inspect the file, and the 100,000-byte and 2 MB inline caps do not apply. S3 rejects one PUT over 5 GiB. There is no multipart upload on this URL.

Commit then reads the whole archive into memory. An upload that S3 accepted can still fail at commit when the archive is very large. If that happens, make the archive smaller and start again from a new deployment.

A branched deployment ignores the upload ​

If the deployment was opened with from_deployment, the worker copies the previous deployment and applies inline writes. It does not read upload_url, even when the PUT returned 200. For a binary or an over-cap file, open the deployment withoutfrom_deployment and upload a complete archive.

Commit, then promote ​

Commit does not change the live site. Poll until the deployment is ready and the preview is published, look at the preview, then promote. The steps are the same as Publish your first site from commit onward, and Patch, promote, and roll back covers promote and rollback.

See also ​