gateway files

gateway files is the project’s file drive: the same store the dashboard’s Files tab, the REST routes under /api/public/files and the MCP tools (list_files, get_file, request_file_upload, confirm_file_upload, delete_file, move_file, create_folder) use. Files are addressed by path, e.g. corpora/2026/train.jsonl. A drive: prefix on a path is accepted and ignored. Bytes move directly between your machine and storage over presigned URLs. The platform keeps the index. Each command below is one REST route; the exit codes are the CLI’s usual ones: 0 done, 1 the platform refused or a transfer failed, 2 bad arguments or missing credentials.

Upload

gateway files upload rows.json                       # -> drive:rows.json
gateway files upload rows.json --to seeds/            # -> drive:seeds/rows.json
gateway files upload rows.json --to seeds/acme.json   # -> drive:seeds/acme.json (one file, a full path)
gateway files upload ./corpus --to in                 # a directory recurses: drive:in/corpus/<its layout>

Flag	What it does
`--to`	Drive folder to put the files under (default the root). With exactly one file, a `--to` ending in a file name is that file’s full path.
`--content-type`	MIME type recorded for every uploaded file. Default: from the extension (`.jsonl` is `application/x-ndjson`), else `application/octet-stream`.
`--overwrite`	Replace a file already at the same path. Without it, a taken path is refused.
`--json`	Print `{ uploaded: [...], refused: [...] }` instead of one line per file.

Each file is three requests: POST /files returns a presigned PUT URL; the bytes stream to it with the SHA-256 the platform signed; POST /files/confirm marks the file ready. A failed PUT is confirmed with ok=false, so no placeholder is left behind. Files starting with . are skipped when a directory is walked. Empty files are refused. One refused file does not stop the others; the exit code is 1 when any was refused. Progress prints on standard error on a TTY, or when GATEWAY_PROGRESS=1.

List and read

gateway files list                       # the root: folders, then files
gateway files list seeds --json          # the platform's listing as JSON
gateway files get seeds/rows.json        # metadata and a time-limited download URL
gateway files download seeds/rows.json --out ./rows.json
gateway files cat seeds/rows.json | jq .

Command	Route	Output
`list [path] [--page N] [--json]`	`GET /files?prefix=&page=&limit=200`	One line per sub-folder (`name/`), then per file: path, size, type, uploader, modified time. `--page` is 0-based.
`get <path>`	`GET /files/download?path=`	`{ path, url, urlExpiry, sizeBytes, contentType, sha256 }`.
`download <path> [--out]`	the same, then a GET from `url`	Streams to `--out`, default the file’s own name in the working directory.
`cat <path>`	the same	The bytes on standard output.

Organize

gateway files mkdir corpora/2026
gateway files move seeds/rows.json corpora/2026/rows.json
gateway files move corpora archive          # a whole folder
gateway files delete archive                # a folder and everything under it

move is metadata only; no bytes are copied. delete removes the stored bytes too. Both print how many entries changed and exit 1 naming the path when nothing was there.

Fetch a URL into the drive

gateway files fetch https://example.com/products.csv --to imports/products.csv

The bytes pass through your machine, then upload as above. The response’s Content-Type is recorded unless --content-type says otherwise. --overwrite replaces a file at that path. The MCP tool download_url_to_drive does the same fetch on the platform.

Connectors

A connector is a saved sync from an external connection (a Slack channel, a Google Drive file, an http URL) into a drive folder. Humans create them on the Connectors tab; only connectors with agent access turned on are visible here.

gateway files connectors list          # id, name, kind, target folder, last sync
gateway files connectors sync <id>     # run it now; the result lists the landed files

Routes: GET /files/connectors and POST /files/connectors/sync { connectorId }. A connector without agent access is refused with 400.

The drive in worlds data commands

Every gateway worlds data input that takes a local file takes drive:<path>; the file is downloaded to a scratch copy, the command runs unchanged, and the report names the drive path under inputs.

gateway files upload rows.json --to seeds/acme/rows.json
gateway worlds data import acme drive:seeds/acme/rows.json
gateway worlds data check acme drive:seeds/acme/rows.json
gateway worlds data extract acme drive:exports/tools.json --shape tool-results --entity users --to rows/users.jsonl
gateway worlds data ingest acme --from drive:calls/tools.jsonl --transform shape.py
gateway worlds data calls pull --from drive:queries/tools.json --to calls/tools.jsonl

Command	Drive input	Drive output
`worlds data import`, `check`	`drive:<path>` among the rows files	—
`worlds data extract`	`drive:<path>` as the source	`--to <path>`
`worlds data ingest`	`drive:<path>` among the inputs; `--from drive:<path>` reads tool-call records from that file	—
`worlds data calls pull`	`drive:<path>` among the saved results; `--from drive:<path>` reads a saved ClickHouse result from that file	`--to <path>`; `<out>` may then be omitted
`worlds session export`	—	`--to <path>`
`traces export`	—	`drive:<path>` as `<out>`

--to takes drive:<path> or a bare path, overwrites, and works beside a local output. The manifest under .gateway/imports/ records the drive spelling, so --resume matches the same import.

From code

TypeScript: import { files } from "@withgateway/sdk" (or @withgateway/sdk/files) — uploadFile, uploadBytes, listFiles, iterateFiles, getFile, readFile, downloadFile, deleteFile, moveFile, createFolder, listFileConnectors, syncFileConnector. Python: from gatewaysdk.files import FilesClient — upload, upload_bytes, list, iter_files, get, read, download, delete, move, mkdir, connectors, sync_connector. Both read GATEWAY_HOST, GATEWAY_PUBLIC_KEY and GATEWAY_SECRET_KEY.

CLI

Python SDK

TypeScript SDK

SDK Reference

REST API

MCP Server

Upload

List and read

Organize

Fetch a URL into the drive

Connectors

The drive in worlds data commands

From code

​Upload

​List and read

​Organize

​Fetch a URL into the drive

​Connectors

​The drive in worlds data commands

​From code

Upload

List and read

Organize

Fetch a URL into the drive

Connectors

The drive in worlds data commands

From code