Accept file uploads on a form
A form on your site can take files as well as text. The visitor's browser sends each file straight to storage, outside the form post, and the form then submits the file's upload id in place of the file. Edge scans every file for malware and checks that its contents match the type the browser declared. Only a file whose scan comes back clean can be read or downloaded.
The flow has three requests from the page:
POST /_upload/{form_id}asks for an upload ticket for one file.- The browser sends the file to the URL in the ticket.
POST /_submit/{form_id}submits the form, with the upload id as the value of the file field.
This page assumes the distribution acme-careers (b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14) is live, has an application page, and already serves one data object at /_api/openings. The form is called apply, and its file field is resume.
The web console does not manage forms yet. There is no submissions inbox: Endpoints in the console is still a placeholder. Set the policy and read submissions through an agent, the CLI or the API.
1. Allow uploads on the form
Without a policy, /_upload/apply answers 404 and /_submit/apply stores whatever it is sent as plain text. The policy names the form, the fields that take files, which types each field accepts, how large a file may be, and how many files a field takes.
It lives in the distribution's runtime next to the /_api map. Sending runtime replaces the whole object, so include the api routes you already have.
On acme-careers, let the apply form take one résumé in the resume field: PDF or Word
(.docx), up to 100 MiB. Keep GET /_api/openings serving openings.json.edge api PATCH /v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14 --input - <<'EOF'
{
"runtime": {
"api": {
"routes": [
{ "match": "/_api/openings", "document": "openings.json" }
]
},
"uploads": {
"apply": {
"fields": {
"resume": {
"types": [
"application/pdf",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document"
],
"max_bytes": 104857600,
"max_files": 1
}
}
}
}
}
}
EOFcurl -s -X PATCH \
https://api.edge.deca-dev.com/v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14 \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"runtime":{"api":{"routes":[{"match":"/_api/openings","document":"openings.json"}]},"uploads":{"apply":{"fields":{"resume":{"types":["application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document"],"max_bytes":104857600,"max_files":1}}}}}}'The agent runs edge_distribution_update. The policy goes live as soon as the update compiles, like the /_api map: there is no preview and no promote. To stop taking files on a form, send runtime again without it.
Rules the update checks:
typesis required and each entry must be on the allowed list: PDF, Word, Excel and PowerPoint (.docx,.xlsx,.pptx), ZIP, plain text, CSV, JSON, PNG, JPEG, GIF, WebP, HEIC, AVIF, MP4, QuickTime, WebM, MP3, M4A, WAV and Ogg. HTML, SVG, scripts and executables are never accepted.max_bytesis 1 byte to 5 GiB. It defaults to 100 MiB.max_filesis 1 to 10. It defaults to 1.- A distribution can have 20 forms with uploads, and a form 10 file fields. Across its fields, one submission can carry at most 10 files and 10 GiB.
- A field cannot be called
edge_s; that name carries the visitor's session.
The full list of type strings is in Endpoints.
2. Upload from the page
Every call to /_upload carries the visitor's session as edge_s, either as a body field or as the edge_s cookie. It must be the same session the page then sends to /_submit: an upload id only attaches to a submission from the session that asked for it. If your page already sets the edge_s cookie for analytics, reuse it. Otherwise make a random value once per page load.
<form id="apply">
<input name="name" required>
<input name="email" type="email" required>
<input name="resume" type="file" accept=".pdf,.docx" required>
<button>Apply</button>
</form>const cookie = document.cookie.match(/(?:^|; )edge_s=([^;]*)/);
const seed = cookie ? decodeURIComponent(cookie[1]) : crypto.randomUUID();
async function call(path, body) {
const r = await fetch(path, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ edge_s: seed, ...body }),
});
if (!r.ok) throw await r.json();
return r.json();
}
async function uploadFile(form, field, file) {
const ticket = await call(`/_upload/${form}`, {
field, name: file.name, type: file.type, size: file.size,
});
if (ticket.mode === 'single') {
// Up to 100 MiB: one form post, every ticket field first, the file last.
const data = new FormData();
for (const [key, value] of Object.entries(ticket.fields)) data.append(key, value);
data.append('file', file);
const r = await fetch(ticket.url, { method: 'POST', body: data });
if (!r.ok) throw new Error('upload failed');
return ticket.upload_id;
}
// Larger: 16 MiB parts, each PUT exactly `length` bytes.
const parts = [];
let urls = ticket.parts;
for (let n = 1; n <= ticket.part_count; n += 1) {
let part = urls.find((p) => p.n === n);
if (!part) {
urls = (await call(`/_upload/${form}/${ticket.upload_id}/parts`, { from: n })).parts;
part = urls[0];
}
const start = (n - 1) * ticket.part_size;
const r = await fetch(part.url, { method: 'PUT', body: file.slice(start, start + part.length) });
if (!r.ok) throw new Error('part failed');
parts.push({ n, etag: r.headers.get('ETag') });
}
await call(`/_upload/${form}/${ticket.upload_id}/complete`, { parts });
return ticket.upload_id;
}What the ticket contains depends on the size the page declared:
| Size | Ticket | The page then |
|---|---|---|
| Up to 100 MiB | {"mode": "single", "upload_id", "url", "fields", "expires_at"} | Posts multipart/form-data to url with every entry of fields, then the file last. The ticket is valid 10 minutes. |
| Larger | {"mode": "multipart", "upload_id", "part_size", "part_count", "parts": [{"n", "length", "url"}], "expires_at"} | PUTs exactly length bytes to each part URL, then calls /complete with every part's ETag. Part URLs are valid one hour. The first 100 come in the ticket; ask /parts with from for the rest. |
The size is pinned. Storage refuses a file, or a part, of any other length, so send the File the visitor picked rather than a re-encoded copy.
A refused ticket tells the page why:
| Status | Body | Meaning |
|---|---|---|
| 400 | {"error": "invalid_upload", "field", "reason": "type"} | The type is not in the field's types. reason is size for a file over max_bytes, and name for an empty name, one over 255 characters, or one with a slash or control character. |
| 400 | {"error": "session_required"} | No edge_s in the body or the cookie |
| 403 | {"error": "quota_exceeded"} | Your organization has uploaded 100 GiB or 50,000 files this month |
| 404 | {"error": "not_found"} | No upload policy for this form or field |
| 429 | {"error": "rate_limited"} | More than 20 tickets a minute from one IP address, or 50 in a day from one session |
3. Submit the form
Submit the upload id as the value of the file field. For a field that takes several files, send an array of ids. Do not put the file itself in the submission: /_submit refuses file parts with 400.
document.getElementById('apply').addEventListener('submit', async (event) => {
event.preventDefault();
const form = event.currentTarget;
const resume = await uploadFile('apply', 'resume', form.resume.files[0]);
await call('/_submit/apply', {
name: form.name.value,
email: form.email.value,
resume,
});
});A stored submission answers 200 with its id:
{ "id": "19a3f0c4e2b5c8d1e3f7", "lane": "submit", "path": "/_submit/apply" }If a value in a file field is not a usable upload, /_submit answers 400 and stores nothing, so the visitor can fix it and send the form again:
{ "error": "invalid_upload", "field": "resume", "reason": "not_uploaded" }reason | Meaning |
|---|---|
not_an_upload | The value is not an upload id |
too_many | More ids than the field's max_files |
duplicate | The same upload id appears twice |
invalid | The id belongs to another session, form or field, was already used, or its file was rejected |
not_uploaded | The ticket was issued but the file never arrived |
An upload that is never attached to a submission is deleted after a day. An attached file stays with its submission.
4. Check the scan
The visitor gets 200 as soon as the submission is stored. The scan runs afterwards, and a file stays scanning until it settles. Each file is in one of four states:
status | Meaning |
|---|---|
scanning | Not settled yet |
clean | No malware found and the contents match the declared type. The file can be read and downloaded. |
rejected | reason is malware, type_mismatch (the first bytes do not match the declared type) or size_mismatch. The file is deleted. |
scan_failed | No verdict after one retry. The file is never readable. |
On acme-careers, show me submission 19a3f0c4e2b5c8d1e3f7 and the scan status of its files.edge api GET /v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14/submissions/19a3f0c4e2b5c8d1e3f7curl -s \
https://api.edge.deca-dev.com/v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14/submissions/19a3f0c4e2b5c8d1e3f7 \
-H "Authorization: Bearer $EDGE_TOKEN"The agent runs edge_submission_get. The answer has the submitted fields and a files list with each file's current status:
{
"submission_id": "19a3f0c4e2b5c8d1e3f7",
"form_id": "apply",
"received_at": "2026-10-18T02:41:07.512Z",
"fields": {
"name": "Mika Tanaka",
"email": "mika@example.com",
"resume": "upl_01M4ZK6Q2T9V8X3N5P7R1W4Y6B"
},
"files": [
{
"field": "resume",
"upload_id": "upl_01M4ZK6Q2T9V8X3N5P7R1W4Y6B",
"name": "mika-tanaka-cv.pdf",
"type": "application/pdf",
"size": 482113,
"status": "clean",
"reason": null,
"has_text": true
}
]
}has_text is true when Edge extracted the file's text for agents to read. That happens for PDF, Word (.docx), plain text and CSV files up to 200 MiB.
Every read of a submission is logged. To have an agent read the résumé itself, see Let an agent read form submissions.
5. Send files to your own system
To pass applications to an applicant-tracking system or a CRM, subscribe a webhook to form.submitted and form.file.scanned. Form events carry what visitors typed, so they need the form-forwarding permission, which only workspace admins have, and Edge asks for confirmation before it creates the subscription. See Forward form submissions.
Send apply-form submissions from acme-careers, and the scan result of each attached file,
to https://ats.acme.example/edge-applications.edge webhooks create \
--url https://ats.acme.example/edge-applications \
--event form.submitted \
--event form.file.scanned \
--distribution b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14 \
--filters - --yes <<'EOF'
{"form_id": "apply"}
EOFcurl -s -X POST https://api.edge.deca-dev.com/v1/webhooks \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://ats.acme.example/edge-applications",
"event_types": ["form.submitted", "form.file.scanned"],
"distribution_ids": ["b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14"],
"filters": { "form_id": "apply" },
"confirm": true
}'The agent runs edge_webhook_create, shows you the summary, and repeats the call once you agree.
form.submitted arrives when the submission is stored, usually while its files are still scanning. Its data.envelope.files lists them. form.file.scanned follows once for each attached file, when its scan settles:
{
"type": "form.file.scanned",
"distribution_id": "b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14",
"data": {
"form_id": "apply",
"submission_id": "19a3f0c4e2b5c8d1e3f7",
"file": {
"field": "resume",
"upload_id": "upl_01M4ZK6Q2T9V8X3N5P7R1W4Y6B",
"name": "mika-tanaka-cv.pdf",
"type": "application/pdf",
"size": 482113,
"status": "clean",
"reason": null,
"download_url": "https://api.edge.deca-dev.com/v1/file-links/eyJ2IjoxLCJ1Ijoi…"
}
}
}Each file in either event has a download_url. Your receiver fetches the file from it with no token:
curl -sL -o mika-tanaka-cv.pdf "$DOWNLOAD_URL"- The link works only once the file is
clean. Before that it answers 409; after arejectedorscan_failedresult it never works. Wait forform.file.scannedwithstatuscleanbefore you fetch. - It is valid for 7 days from the event. It redirects to a download that lasts 60 seconds, so follow the redirect straight away.
- Every use is logged. Anyone holding the link can download the file until it expires, so treat it like a password: do not log it or pass it on.
Next
- Let an agent read form submissions
- Send Edge events to a webhook
- Endpoints: every policy rule and type string
- Limits