Skip to content

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:

  1. POST /_upload/{form_id} asks for an upload ticket for one file.
  2. The browser sends the file to the URL in the ticket.
  3. 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.

text
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.
bash
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
          }
        }
      }
    }
  }
}
EOF
bash
curl -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:

  • types is 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_bytes is 1 byte to 5 GiB. It defaults to 100 MiB.
  • max_files is 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.

html
<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>
javascript
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:

SizeTicketThe 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:

StatusBodyMeaning
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.

javascript
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:

json
{ "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:

json
{ "error": "invalid_upload", "field": "resume", "reason": "not_uploaded" }
reasonMeaning
not_an_uploadThe value is not an upload id
too_manyMore ids than the field's max_files
duplicateThe same upload id appears twice
invalidThe id belongs to another session, form or field, was already used, or its file was rejected
not_uploadedThe 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:

statusMeaning
scanningNot settled yet
cleanNo malware found and the contents match the declared type. The file can be read and downloaded.
rejectedreason is malware, type_mismatch (the first bytes do not match the declared type) or size_mismatch. The file is deleted.
scan_failedNo verdict after one retry. The file is never readable.
text
On acme-careers, show me submission 19a3f0c4e2b5c8d1e3f7 and the scan status of its files.
bash
edge api GET /v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14/submissions/19a3f0c4e2b5c8d1e3f7
bash
curl -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:

json
{
  "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.

text
Send apply-form submissions from acme-careers, and the scan result of each attached file,
to https://ats.acme.example/edge-applications.
bash
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"}
EOF
bash
curl -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:

json
{
  "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:

bash
curl -sL -o mika-tanaka-cv.pdf "$DOWNLOAD_URL"
  • The link works only once the file is clean. Before that it answers 409; after a rejected or scan_failed result it never works. Wait for form.file.scanned with status clean before 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 ​