webwrite — Send data to web services using HTTP POST/PUT requests and return the response.
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 webwrite works in 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-urlencodedpayloads. Character vectors / strings are sent as UTF-8 text, and other MATLAB values default to JSON encoding viajsonencode. - Name-value arguments (or an options struct) accept the same fields as MATLAB
weboptions:ContentType,MediaType,Timeout,HeaderFields,Username,Password,UserAgent,RequestMethod, andQueryParameters. ContentTypecontrols 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.MediaTypesets the outboundContent-Typeheader. When omitted, RunMat chooses a sensible default (application/x-www-form-urlencoded,application/json,text/plain; charset=utf-8, orapplication/octet-stream) based on the payload.- Query parameters can be appended through the
QueryParametersoption 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.
How webwrite runs on the GPU
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.
GPU memory and residency
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.
Examples
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)Uploading plain text
message = "Hello from RunMat!";
reply = webwrite("https://api.example.com/echo", message, ...
"MediaType", "text/plain", "ContentType", "text")Uploading raw binary data
bytes = uint8([1 2 3 4 5]);
webwrite("https://api.example.com/upload", bytes, ...
"ContentType", "binary", "MediaType", "application/octet-stream")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)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.
Related functions to explore
These functions work well alongside webwrite. Each page has runnable examples you can try in the browser.
webread, jsonencode, jsondecode, gpuArray, weboptions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how webwrite works, line by line, in Rust.
- View webwrite.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.