webwrite — Write data to a web service and decode its response.
webwrite sends data to an HTTP or HTTPS service and decodes the response according to its content type and options.
Syntax
response = webwrite(url, data)
response = webwrite(url, data, optionsStruct)
response = webwrite(url, data, name, value, ...)
response = webwrite(url, data, optionsStruct, name, value, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
url | StringScalar | Yes | — | HTTP/HTTPS URL target. |
data | Any | Yes | — | Request payload value. |
optionsStruct | Any | Yes | — | weboptions struct or option struct literal. |
name | StringScalar | Variadic | — | Option or query parameter name. |
value | Any | Variadic | — | Option or query parameter value. |
Returns
| Name | Type | Description |
|---|---|---|
response | Any | Decoded response payload from the remote endpoint. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:webwrite:InvalidArgument | Argument type/shape does not match webwrite call contract. | webwrite: invalid argument |
RunMat:webwrite:InvalidUrl | URL is empty or malformed. | webwrite: invalid URL |
RunMat:webwrite:MissingData | Required data argument is missing. | webwrite: missing data argument |
RunMat:webwrite:MissingOptionValue | A name-value option key has no value. | webwrite: missing option value |
RunMat:webwrite:InvalidOptionValue | An option value fails validation. | webwrite: invalid option value |
RunMat:webwrite:InvalidCredentials | Password is provided without username. | webwrite: invalid credentials |
RunMat:webwrite:Transport | HTTP transport fails. | webwrite: transport failure |
RunMat:webwrite:ResponseJson | Response body cannot be decoded as JSON. | webwrite: failed to parse JSON response |
RunMat:webwrite:Output | Output payload cannot be materialized. | webwrite: output materialization failure |
RunMat:webwrite:Flow | Nested flow fails while gathering inputs or nested builtin calls. | webwrite: flow failure |
How webwrite works
- The first input is an absolute URL supplied as a character vector or string scalar.
- Post names are text. Post values may be text, numeric, logical, or datetime values, including supported arrays; native integer values are serialized from exact storage.
- A structure or supported numeric value may be used as JSON data. Nested native integer values remain exact through JSON serialization.
- A final options structure controls
ContentType,MediaType,Timeout,HeaderFields,Username,Password,UserAgent, andRequestMethod. The default timeout is 5 seconds, and an integer timeout is read exactly. 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.- RunMat additionally supports
QueryParameters, direct option-like name-value pairs, and raw byte-oriented uploads. These conveniences are distinct from the portable post-pair plus final-options form. - HTTP errors, timeouts, TLS verification problems, and JSON encoding issues raise MATLAB-style errors with descriptive text.
Does RunMat run webwrite on the GPU?
The request path terminates fusion and gathers automatically resident values through their owning provider. Explicit gpuArray input crosses the webwrite-explicit-gpu-input extension gate before any gather.
GPU memory and residency
Requests and results are host-side. Automatically resident values gather transparently; explicit gpuArray input requires RunMat mode.
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)Using webwrite with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how webwrite changes the result.
Run a small webwrite example, explain the result, then change one input and compare the output.
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 positive numeric scalar up to 2147.483647 seconds or Inf. The default is 5 seconds.
What happens with GPU inputs?⌄
Automatically resident values gather transparently before serialization. Explicit gpuArray input is a named RunMat extension and is rejected before provider access in MATLAB-compatible mode.
Related Io functions
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fileattrib · fileparts · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · ls · matlabroot · memmapfile · mkdir · movefile · open · opentoline · path · pathsep · pcode · pwd · readstruct · rehash · restoredefaultpath · rmdir · rmpath · run · savepath · setenv · setpref · system · tempdir · tempname · uigetdir · uigetfile · uiputfile · unsetenv · userpath · what · winqueryreg · xmlread · xmlwrite
Tabular
arrayDatastore · csvread · csvwrite · detectImportOptions · dlmread · dlmwrite · fileDatastore · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · spreadsheetImportOptions · writecell · writematrix · writetable · writetimetable · xlsread · xlswrite
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Import
Json
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how webwrite is executed, line by line, in Rust.
- View the source for webwrite in Rust on GitHub
- Learn how the RunMat 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 blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.