Skip to main content
The Files simulator stands in for the SFTP drops that payers, clearinghouses, and health information exchanges use to exchange batched documents: claim files, 837/835 batches, lab result packets, referral PDFs, eligibility rosters. Your agent reads inbound files out of an inbox and writes outbound files to a delivery path. The verification engine scores sftp-file-present criteria against the final file tree.

​
How your agent connects

The Files sandbox is exposed over HTTP under the benchmark-run path. All reads and writes happen through /v1/benchmark-runs/{id}/files/*. The sandbox is seeded by the linked Files dataset, which stores the actual files in GCS under datasets/{datasetId}/files/. When the sandbox is branched from the dataset, a copy of the files is made available to the sandbox.

​
Endpoints

MethodEndpointDescription
GET/v1/benchmark-runs/{id}/files/inboxList files in the sandbox inbox
GET/v1/benchmark-runs/{id}/files/{path}Download a specific file by relative path
Paths mirror the directory layout a real SFTP drop would have, for example inbox/referrals/, outbound/claims/, archive/.
The run-scoped v1 files surface is read-only today. Writing outbound files from the agent (PUT/DELETE) is not yet wired on /v1/benchmark-runs/{id}/files/*. When the rollout needs to stage a file for a criterion to read, use a scenario step like drop_file_inbox to seed content before the agent starts.

​
Driving the rollout

List the inbox: 
curl "https://api.verial.ai/v1/benchmark-runs/$BENCHMARK_RUN_ID/files/inbox" \
  -H "Authorization: Bearer $RUN_TOKEN"
Download a specific file: 
curl "https://api.verial.ai/v1/benchmark-runs/$BENCHMARK_RUN_ID/files/inbox/referrals/2026-04-23-referral.pdf" \
  -H "Authorization: Bearer $RUN_TOKEN" \
  --output referral.pdf

​
Configuration

The Files simulator is configured by its linked dataset’s manifest. The dataset’s manifest describes the initial file tree; at provisioning time, the sandbox branches a copy of the dataset’s files so mutations made during the rollout don’t affect the original. 
curl -X POST https://api.verial.ai/simulators \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "Sftp", "name": "Payer SFTP Drop"}'
The accompanying dataset defines the directory layout and seeded contents. See Datasets for the manifest shape.

​
Verification

The sftp-file-present check asserts that at least one file matches a glob pattern in the final file tree, optionally parsing it as JSON and asserting on field values. 
{
  "label": "Claim file written to outbound/",
  "weight": 1.0,
  "assertion": {
    "assert": "sftp-file-present",
    "path_pattern": "outbound/claims/*.json",
    "parse_json": true,
    "fields": [
      { "path": "claim.patient.member_id", "expected": "BCB123456789" },
      { "path": "claim.total_charges", "expected": 420.00 }
    ]
  }
}
See the Criteria concept page for the full assertion spec.

​
Next Steps

Criteria

Full reference for sftp-file-present assertions.

Datasets

How file manifests seed the Files sandbox.

Simulators overview

Lifecycle, provisioning, and configuration patterns.

Sandboxes

File-system branching and checkpoints.