What does the `webwrite` function do in MATLAB / RunMat?

webwrite sends data to an HTTP or HTTPS endpoint using methods such as POST, PUT, PATCH, or DELETE. It mirrors MATLAB behaviour: request bodies are created from MATLAB values (structs, cells, strings, numeric tensors), request headers come from weboptions style arguments, and the response is decoded the same way as webread.

How does the `webwrite` function behave in MATLAB / RunMat?

The first input is an absolute URL supplied as a character vector or string scalar.
The second input supplies the request body. Structs and two-column cell arrays become application/x-www-form-urlencoded payloads. Character vectors / strings are sent as UTF-8 text, and other MATLAB values default to JSON encoding via jsonencode.
Name-value arguments (or an options struct) accept the same fields as MATLAB weboptions: ContentType, MediaType, Timeout, HeaderFields, Username, Password, UserAgent, RequestMethod, and QueryParameters.
ContentType controls how the response is parsed ("auto" by default). Set it to "json", "text", or "binary" to force JSON decoding, text return, or raw byte vectors.
MediaType sets the outbound Content-Type header. When omitted, RunMat chooses a sensible default (application/x-www-form-urlencoded, application/json, text/plain; charset=utf-8, or application/octet-stream) based on the payload.
Query parameters can be appended through the QueryParameters option or by including additional, unrecognised name-value pairs. Parameter values follow MATLAB scalar rules.
HTTP errors, timeouts, TLS verification problems, and JSON encoding issues raise MATLAB-style errors with descriptive text.

`webwrite` Function GPU Execution Behaviour

webwrite is a sink in the execution graph. Any GPU-resident inputs (for example tensors inside structs or cell arrays) are gathered to host memory before encoding the request body. Network I/O always runs on the CPU; fusion plans are terminated with ResidencyPolicy::GatherImmediately.

Examples of using the `webwrite` function in MATLAB / RunMat

Posting form fields to a REST endpoint

payload = struct("name", "Ada", "score", 42);
opts = struct("ContentType", "json");          % expect JSON response
reply = webwrite("https://api.example.com/submit", payload, opts);
disp(reply.status)

Expected output:

    "ok"

Sending JSON payloads

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

resp is decoded from JSON into structs, doubles, logicals, or strings.

Uploading plain text

message = "Hello from RunMat!";
reply = webwrite("https://api.example.com/echo", message, ...
                 "MediaType", "text/plain", "ContentType", "text");

reply holds the echoed character vector.

Uploading raw binary data

bytes = uint8([1 2 3 4 5]);
webwrite("https://api.example.com/upload", bytes, ...
         "ContentType", "binary", "MediaType", "application/octet-stream");

The body is transmitted verbatim as bytes.

Supplying credentials, custom headers, and query parameters

headers = struct("X-Client", "RunMat", "Accept", "application/json");
opts = struct("Username", "ada", "Password", "lovelace", ...
              "HeaderFields", headers, ...
              "QueryParameters", struct("verbose", true));
profile = webwrite("https://api.example.com/me", struct(), opts);

profile contains the decoded JSON profile while the request carries Basic Auth credentials and custom headers.

GPU residency in RunMat (Do I need `gpuArray`?)

No. webwrite executes on the CPU. Any GPU values are automatically gathered before serialising the payload, and results are created on the host. Manually gathering is unnecessary.

FAQ

Which HTTP methods are supported?
webwrite defaults to POST. Supply "RequestMethod","put" (or "patch", "delete") to use other verbs.
How do I send JSON?
Set "MediaType","application/json" (optionally via a struct) or "ContentType","json". RunMat serialises the payload with jsonencode and sets the appropriate Content-Type.
How are form posts encoded?
Struct inputs and two-column cell arrays are turned into application/x-www-form-urlencoded bodies. Field values must be scalar text or numbers.
Can I post binary data?
Yes. Provide numeric tensors (double, integer, or logical) and set "ContentType","binary" or "MediaType","application/octet-stream". Values must be in the 0–255 range.
What controls the response decoding?
ContentType mirrors webread: "auto" inspects response headers, while "json", "text", and "binary" force the output format.
How do I add custom headers?
Use "HeaderFields", struct("Header-Name","value",...) or a two-column cell array. Header names must be valid HTTP tokens.
Does webwrite follow redirects?
Yes. The underlying reqwest client follows redirects with the same credentials and headers.
Can I send query parameters and a body simultaneously?
Yes. Provide a QueryParameters struct/cell in the options. Parameters are percent-encoded and appended to the URL before the request is issued.
How do timeouts work?
Timeout accepts a scalar number of seconds. The default is 60 s. Requests exceeding the limit raise webwrite: request to <url> timed out.
What happens with GPU inputs?
They are gathered before serialisation. The function is marked as a sink to break fusion graphs and ensure residency is released.

What does the webwrite function do in MATLAB / RunMat?

How does the webwrite function behave in MATLAB / RunMat?

webwrite Function GPU Execution Behaviour

Examples of using the webwrite function in MATLAB / RunMat