Skip to content

Let an agent read form submissions ​

An agent can work through what visitors send your forms: summarise new applications, pull the details out of a résumé, or check a scanned document. It reads submissions and their files through Edge, so each read goes through the same checks: the file must have passed its malware scan, your redaction settings apply, every read is logged, and a daily cap limits how much any one agent or token can read.

Submissions are visitor personal data. Ask for what the task needs, not everything.

This page uses the apply form on acme-careers (b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14) from Accept file uploads on a form.

Who can read submissions. Workspace managers and admins can, and so can an agent they connect. A personal access token can only if its creator chose the submission permission explicitly. It is not part of any preset, and Edge warns that the token will be able to read visitor personal data. See Permission scopes for the exact permission.

The web console has no submissions inbox yet. Read submissions through an agent, the CLI or the API.

1. List recent submissions ​

text
List this week's submissions to the apply form on acme-careers.
bash
edge api GET "/v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14/submissions?form_id=apply&since=2026-10-12T00:00:00Z"
bash
curl -s -G \
  https://api.edge.deca-dev.com/v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14/submissions \
  --data-urlencode form_id=apply \
  --data-urlencode since=2026-10-12T00:00:00Z \
  -H "Authorization: Bearer $EDGE_TOKEN"

The agent runs edge_submission_list. Each page holds up to 50 submissions, oldest first for each form, with a short preview of the fields:

json
{
  "submissions": [
    {
      "submission_id": "19a3f0c4e2b5c8d1e3f7",
      "form_id": "apply",
      "received_at": "2026-10-18T02:41:07.512Z",
      "file_count": 1,
      "preview": "name: Mika Tanaka · email: mika@example.com · resume: upl_01M4ZK6Q2T9V8X3N5P7R1W4Y6B"
    }
  ],
  "cursor": null
}

Without since, the list starts 30 days ago. Without form_id, it covers every form on the distribution. When cursor is not null, pass it back for the next page.

2. Read one submission ​

text
Show me submission 19a3f0c4e2b5c8d1e3f7 on acme-careers.
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 every field and a files list with each file's upload_id, status and has_text. A file can be read only once its status is clean; the other statuses are explained in Check the scan.

3. Read an attached file ​

A file can be read three ways:

OutputReturnsUse it for
textThe text Edge extracted, 100,000 characters per page. Pass next_offset back as offset for the next page.PDF, Word (.docx), plain text and CSV, when has_text is true
contentThe file itself, inline, so the model can look at itImages and PDF up to 10 MiB, such as a scanned résumé with no text layer
linkA download URL valid for 15 minutesAnything else, or a file you want to open yourself
text
Read the résumé attached to submission 19a3f0c4e2b5c8d1e3f7 on acme-careers and summarise
the candidate's experience in five bullet points.
bash
edge api GET "/v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14/submissions/19a3f0c4e2b5c8d1e3f7/files/upl_01M4ZK6Q2T9V8X3N5P7R1W4Y6B?output=text"
bash
curl -s \
  "https://api.edge.deca-dev.com/v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14/submissions/19a3f0c4e2b5c8d1e3f7/files/upl_01M4ZK6Q2T9V8X3N5P7R1W4Y6B?output=text" \
  -H "Authorization: Bearer $EDGE_TOKEN"

The agent runs edge_submission_file_get:

json
{
  "file": {
    "field": "resume",
    "upload_id": "upl_01M4ZK6Q2T9V8X3N5P7R1W4Y6B",
    "name": "mika-tanaka-cv.pdf",
    "type": "application/pdf",
    "size": 482113,
    "status": "clean",
    "reason": null,
    "has_text": true
  },
  "text": "Mika Tanaka\nSenior Backend Engineer\n…",
  "offset": 0,
  "next_offset": null,
  "total_chars": 6214
}

If the résumé is a scan with no text, ask the agent to look at it instead, for example "Look at the résumé attached to submission 19a3f0c4e2b5c8d1e3f7 and read it." The agent asks edge_submission_file_get for content. Over the API, output=content returns the file as content_base64.

To download a file yourself, GET …/files/{upload_id}/download redirects to a download that lasts 60 seconds. Follow the redirect straight away:

bash
curl -sL -o mika-tanaka-cv.pdf \
  https://api.edge.deca-dev.com/v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14/submissions/19a3f0c4e2b5c8d1e3f7/files/upl_01M4ZK6Q2T9V8X3N5P7R1W4Y6B/download \
  -H "Authorization: Bearer $EDGE_TOKEN"

4. Redact personal data from agent reads (optional) ​

By default agents see fields and extracted text as the visitor wrote them. A workspace admin can have Edge hide matches of a PII detector, such as email addresses, from agent and token reads of a distribution's submissions.

text
On acme-careers, redact email addresses when agents and tokens read form submissions.
bash
edge api PUT /v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14/pii-policy --input - <<'EOF'
{
  "scope_type": "submission",
  "detector_key": "email",
  "mode": "redact"
}
EOF
bash
curl -s -X PUT \
  https://api.edge.deca-dev.com/v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14/pii-policy \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scope_type": "submission", "detector_key": "email", "mode": "redact"}'

The agent runs edge_pii_policy_set with scope_type submission. From then on, agent and token reads show [redacted:email] in place of each match, in fields, previews and extracted text. Set mode to allow to show that detector's matches again. The detectors are listed by edge_pii_detector_list.

The setting changes what is shown, not what is stored:

  • A person reading with their own sign-in, as the console does, still sees raw values.
  • A link or content read returns the file's original bytes. Files are never redacted.

5. See who read what ​

text
Who has read submissions on acme-careers in the last 30 days?
bash
edge api GET /v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14/submissions/access-log
bash
curl -s \
  https://api.edge.deca-dev.com/v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14/submissions/access-log \
  -H "Authorization: Bearer $EDGE_TOKEN"

The agent runs edge_submission_access_log. Every read writes an entry: listing, reading a submission, reading a file as text, link or content, downloading, and each use of a webhook download link. Entries come newest first, up to 100, from the last 30 days unless you pass since:

json
{
  "entries": [
    {
      "at": "2026-10-18T03:02:44.118Z",
      "action": "file_text",
      "actor_type": "agent",
      "form_id": "apply",
      "submission_id": "19a3f0c4e2b5c8d1e3f7",
      "upload_id": "upl_01M4ZK6Q2T9V8X3N5P7R1W4Y6B"
    }
  ]
}

Each entry also carries id, and who read: actor_id, plus token_id for a token and client_id for an agent.

actor_type is agent, pat (a personal access token), user (a person signed in), or webhook_link. action is list, get, file_text, file_link, file_content or download. Entries are kept for a year.

Daily limits ​

Each agent and each personal access token can make up to 1,000 submission reads and 200 file reads a day. For agents the count is per person; for tokens it is per token. The count resets at 00:00 UTC. Over the limit, reads fail with 429 rate_limited until the reset. People reading with their own sign-in are not capped.

If an agent reaches the limit, it is usually reading more than the task needs. Narrow the request to one form, a shorter since window, or the submissions you name.

Next ​