> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verial.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Files (SFTP)

> SFTP-style file drops for batch intake and outbound deliveries.

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](/guides/concepts/datasets), 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/`.

<Note>
  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.
</Note>

## Driving the rollout

List the inbox:

```bash theme={null}
curl "https://api.verial.ai/v1/benchmark-runs/$BENCHMARK_RUN_ID/files/inbox" \
  -H "Authorization: Bearer $RUN_TOKEN"
```

Download a specific file:

```bash theme={null}
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.

```bash theme={null}
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](/guides/concepts/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.

```json theme={null}
{
  "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](/guides/concepts/criteria#sftp-claim-file-uploaded) for the full assertion spec.

## Next Steps

<CardGroup cols={2}>
  <Card title="Criteria" icon="check-double" href="/guides/concepts/criteria">
    Full reference for `sftp-file-present` assertions.
  </Card>

  <Card title="Datasets" icon="database" href="/guides/concepts/datasets">
    How file manifests seed the Files sandbox.
  </Card>

  <Card title="Simulators overview" icon="server" href="/guides/simulators/overview">
    Lifecycle, provisioning, and configuration patterns.
  </Card>

  <Card title="Sandboxes" icon="box" href="/guides/concepts/sandboxes">
    File-system branching and checkpoints.
  </Card>
</CardGroup>