weboptions — Create an options struct that configures webread and webwrite HTTP behaviour.

weboptions builds a MATLAB-style options struct that controls HTTP behaviour for functions such as webread, webwrite, and websave. The struct stores option fields like Timeout, ContentType, HeaderFields, and RequestMethod, all with MATLAB-compatible defaults.

How weboptions works in RunMat

• Returns a struct with canonical field names: ContentType, Timeout, HeaderFields, UserAgent, Username, Password, RequestMethod, MediaType, and QueryParameters.
• Defaults mirror MATLAB: ContentType="auto", Timeout=60, UserAgent="" (RunMat substitutes a default agent when this is empty), RequestMethod="auto", MediaType="auto", and empty structs for HeaderFields and QueryParameters.
• Name-value arguments are case-insensitive. Values are validated to ensure MATLAB-compatible types (text scalars for string options, positive scalars for Timeout, structs or two-column cell arrays for HeaderFields and QueryParameters).
• Passing an existing options struct as the first argument clones it before applying additional overrides, matching MATLAB's update pattern opts = weboptions(opts, "Timeout", 5).
• Unknown option names raise descriptive errors.

How weboptions runs on the GPU

weboptions operates entirely on CPU metadata. It gathers any gpuArray inputs back to host memory before validation, because HTTP requests execute on the CPU regardless of the selected acceleration provider. No GPU provider hooks are required for this function.

GPU memory and residency

No. weboptions gathers any GPU-resident values automatically and always returns a host struct. HTTP builtins ignore GPU residency for metadata.

Examples

Setting custom timeouts for webread calls

opts = weboptions("Timeout", 10);
html = webread("https://example.com", opts)

Providing HTTP basic authentication credentials

opts = weboptions("Username", "ada", "Password", "lovelace");
profile = webread("https://api.example.com/me", opts)

Sending JSON payloads with webwrite

opts = weboptions("ContentType", "json", "MediaType", "application/json");
payload = struct("title", "RunMat", "stars", 5);
reply = webwrite("https://api.example.com/projects", payload, opts)

Applying custom headers with struct syntax

headers = struct("Accept", "application/json", "X-Client", "RunMat");
opts = weboptions("HeaderFields", headers);
data = webread("https://api.example.com/resources", opts)

Combining existing options with overrides

base = weboptions("ContentType", "json");
opts = weboptions(base, "Timeout", 15, "QueryParameters", struct("verbose", true));
result = webread("https://api.example.com/items", opts)

FAQ

Which option names are supported in RunMat?

weboptions implements the options consumed by webread and webwrite: ContentType, Timeout, HeaderFields, UserAgent, Username, Password, RequestMethod, MediaType, and QueryParameters. Unknown names raise a MATLAB-style error.

What does RequestMethod="auto" mean?

webread treats "auto" as "get" while webwrite maps it to "post". Override the method when you need put, patch, or delete.

How are empty usernames or passwords handled?

Empty strings leave authentication disabled. A non-empty password without a username raises a MATLAB-compatible error.

Can I pass query parameters through the options struct?

Yes. Supply a struct or two-column cell array in the QueryParameters option. Values may include numbers, logicals, or text scalars, and they are percent-encoded when the request is built.

Do I need to manage GPU residency for options?

No. weboptions gathers any GPU-resident values automatically and always returns a host struct. HTTP builtins ignore GPU residency for metadata.

Does weboptions mutate the input struct?

No. A copy is made before overrides are applied, preserving the original struct you pass in.

How can I clear headers or query parameters?

Pass an empty struct (struct()) or empty cell array ({}) to reset the respective option.

Related functions to explore

These functions work well alongside weboptions. Each page has runnable examples you can try in the browser.

webread, webwrite, jsondecode, jsonencode

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how weboptions works, line by line, in Rust.

• View weboptions.rs on GitHub
• Learn how the runtime works
• Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing