File uploads & downloads

An operation declared with a binary response returns an owned byte response. You can inspect its HTTP status, media type, content length, headers, and Content-Disposition filename before consuming it. The generated README shows the response type and usage for your SDK’s language.

Use the bounded read helper for small files, supplying the maximum number of bytes your application will accept. For larger files, stream chunks to a sink instead. Where the language supports backpressure, the SDK waits for the sink before reading more data. Close the response when you finish or stop early; scoped ownership and explicit cancellation release the underlying transfer.

The read limit counts the bytes delivered to your application, including any transparent decompression by the HTTP client. Content-Length remains response metadata and may describe compressed bytes on the wire.

Mixed responses and errors

An operation can return JSON for one success status and a file for another. Its generated return type exposes both outcomes; an explicitly documented no-content success also remains distinct. Error statuses follow the SDK’s ordinary error handling, including JSON error bodies.

A JSON string with a base64 schema stays a value inside a JSON document. It does not become a file response merely because the schema’s format is byte or binary. Binary response handling follows the operation’s media type.

Uploading

Raw octet-stream bodies accept the language’s byte representation. Multipart operations expose their declared file and scalar fields, and the SDK builds the multipart boundary. Use the generated operation example for the correct argument names and file representation; do not set the outer multipart Content-Type yourself without its matching boundary.

These uploads take in-memory values. They do not provide a streaming upload or a resumable transfer protocol. Per-part filename and media-type controls depend on the language’s existing upload surface.

Request defaults, overrides, and establishment deadlines follow Retries & timeouts. A download’s opening timeout does not limit the lifetime of an established transfer.