File Transfers 🆕¶

A file transfer record describes one file uploaded or downloaded in a session: its name, size and digests, the antivirus verdict and what happened to the file afterwards. Records can be listed for one session or across all sessions. Their visibility follows the visibility of the sessions they belong to. Antivirus engines are configured with the avscan_engine endpoints.

Data Structures¶

FileTransferModel¶

Attribute

Type

Required

Description

id

string

Read-only. Uniqueness is required.

session_id

string

Read-only. Session the file was transferred in.

direction

string {upload, download}

Read-only. Direction of the transfer.

filename

string

Read-only. Name of the file.

status

string {unknown, completed, blocked, failed}

Read-only. What happened to the file after the verdict.

location

string

Read-only. Where the file came from or went: the source URL for a download, the path the file was published under for an upload.

transferred_at

datetime

Read-only. End of the transfer, or created_at if the transfer was refused before the file was read. The difference to created_at is the scan latency.

size

number

Read-only. Size of the file, in bytes.

sha256

string

Read-only. SHA-256 digest of the file.

sha1

string

Read-only. SHA-1 digest of the file.

md5

string

Read-only. MD5 digest of the file.

outcome

string {not_scanned, clean, infected, unscannable}

Read-only. Verdict the transfer was gated on.

reason

string {unreachable, engine_error, timeout, saturated, too_large, staging_exhausted, source_modified}

Read-only. Why the file could not be scanned. Set only when outcome == unscannable.

service

string

Read-only. Name of the antivirus engine that returned the verdict, as it was at the time of the scan. null if no engine was contacted.

service_url

string

Read-only. URL of that engine, as configured when it answered.

service_istag

string

Read-only. ISTag of the scan response: the signature set that produced the verdict.

detail

string

Read-only. Threat name reported by the engine. Set only when outcome == infected.

scanning

boolean

Read-only. State of the safe’s file_transfer_av_scanning option when the transfer was gated.

created_at

datetime

Read-only. Timestamp of creation.

modified_at

datetime

Read-only. Timestamp of modification.

removed

boolean

Read-only.

Retrieve Available Attributes of the FileTransferModel¶

Request

Method

GET

Path

/api/v2/objspec/file_transfer

GET /api/v2/objspec/file_transfer

Example Request

curl -s -k -X GET \
  -H 'Authorization: <token>' \
  'https://10.33.4.94/api/v2/objspec/file_transfer'

List File Transfers¶

Returns the file transfer records of all sessions the caller can read.

Request

Method

GET

Path

/api/v2/file_transfer

To check allowed methods, available URL parameters and possible responses please refer to the API Overview section.

GET /api/v2/file_transfer

Example Request

curl -s -k -X GET \
  -H 'Authorization: <token>' \
  'https://10.33.4.94/api/v2/file_transfer'

Response

{
    "result": "success",
    "file_transfer": [
        {
            "id": "5890708312600608769",
            "session_id": "5890708312600608789",
            "direction": "upload",
            "filename": "network-diagram.png",
            "status": "completed",
            "location": "uploads\/network-diagram.png",
            "transferred_at": "2026-10-29 02:42:22.82611-07",
            "size": 1112753,
            "sha256": "c617c764930794f867b3a55220dace3223d75a700909b0ac44786e297286b402",
            "sha1": "9be15c7933460f8b60a14eab9f94c0f396801514",
            "md5": "e588aedd614532413e3eb4bac3e9045c",
            "outcome": "clean",
            "service": "ClamAV",
            "service_url": "icap:\/\/icap.example.com:1344\/avscan",
            "service_istag": "CI0001-6ZC63rSqYEnVnp1PWaV\/HwAA",
            "scanning": true,
            "created_at": "2026-10-29 02:42:24.782212-07",
            "modified_at": "2026-10-29 02:42:24.786942-07"
        },
        {
            "id": "5890708312600608770",
            "session_id": "5890708312600608789",
            "direction": "download",
            "filename": "user-manual.pdf",
            "status": "completed",
            "location": "https:\/\/www.example.com\/files\/user-manual.pdf",
            "transferred_at": "2026-10-29 02:46:32.72659-07",
            "size": 2280050,
            "sha256": "aeef73c449e0f33cc0fc2198e5d82feabe2f828efaf323d9f94cbeecb28a0ad3",
            "sha1": "51b7355d2c24bdecf4fdb3616bf35024f16cf063",
            "md5": "d51bc08738f5b662667463eed8ee32c8",
            "outcome": "clean",
            "service": "ClamAV",
            "service_url": "icap:\/\/icap.example.com:1344\/avscan",
            "service_istag": "CI0001-6ZC63rSqYEnVnp1PWaV\/HwAA",
            "scanning": true,
            "created_at": "2026-10-29 02:46:34.484825-07",
            "modified_at": "2026-10-29 02:46:34.488794-07"
        }
    ]
}

List File Transfers of a Session¶

Request

Method

GET

Path

/api/v2/session/<session_id>/file_transfer

GET /api/v2/session/<session_id>/file_transfer

Example Request

curl -s -k -X GET \
  -H 'Authorization: <token>' \
  'https://10.33.4.94/api/v2/session/5890708312600608789/file_transfer'

Response

{
    "result": "success",
    "file_transfer": [
        {
            "id": "5890708312600608769",
            "session_id": "5890708312600608789",
            "direction": "upload",
            "filename": "network-diagram.png",
            "status": "completed",
            "location": "uploads\/network-diagram.png",
            "transferred_at": "2026-10-29 02:42:22.82611-07",
            "size": 1112753,
            "sha256": "c617c764930794f867b3a55220dace3223d75a700909b0ac44786e297286b402",
            "sha1": "9be15c7933460f8b60a14eab9f94c0f396801514",
            "md5": "e588aedd614532413e3eb4bac3e9045c",
            "outcome": "clean",
            "service": "ClamAV",
            "service_url": "icap:\/\/icap.example.com:1344\/avscan",
            "service_istag": "CI0001-6ZC63rSqYEnVnp1PWaV\/HwAA",
            "scanning": true,
            "created_at": "2026-10-29 02:42:24.782212-07",
            "modified_at": "2026-10-29 02:42:24.786942-07"
        },
        {
            "id": "5890708312600608770",
            "session_id": "5890708312600608789",
            "direction": "download",
            "filename": "user-manual.pdf",
            "status": "completed",
            "location": "https:\/\/www.example.com\/files\/user-manual.pdf",
            "transferred_at": "2026-10-29 02:46:32.72659-07",
            "size": 2280050,
            "sha256": "aeef73c449e0f33cc0fc2198e5d82feabe2f828efaf323d9f94cbeecb28a0ad3",
            "sha1": "51b7355d2c24bdecf4fdb3616bf35024f16cf063",
            "md5": "d51bc08738f5b662667463eed8ee32c8",
            "outcome": "clean",
            "service": "ClamAV",
            "service_url": "icap:\/\/icap.example.com:1344\/avscan",
            "service_istag": "CI0001-6ZC63rSqYEnVnp1PWaV\/HwAA",
            "scanning": true,
            "created_at": "2026-10-29 02:46:34.484825-07",
            "modified_at": "2026-10-29 02:46:34.488794-07"
        }
    ]
}