Files (SFTP)

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

Method	Endpoint	Description
`GET`	`/v1/benchmark-runs/{id}/files/inbox`	List 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.

Getting Started

Core Concepts

Simulators

Observability

Guides

How your agent connects

Endpoints

Driving the rollout

Configuration

Verification

Next Steps

Criteria

Datasets

Simulators overview

Sandboxes

​How your agent connects

​Endpoints

​Driving the rollout

​Configuration

​Verification

​Next Steps

Criteria

Datasets

Simulators overview

Sandboxes

How your agent connects

Endpoints

Driving the rollout

Configuration

Verification

Next Steps