Blueprint Reference

Every node below lives under Mod HTTP in the Blueprint node palette, split into Mod HTTP > Request and Mod HTTP > Response.

Start Http Request

Starts an HTTP request and returns a handle to it. The handle is always valid, and may be ignored unless you need to cancel the request.

If you supply a body but no Content-Type header, one is added for you: text/plain; charset=utf-8 for StringContent, or application/octet-stream for RawContent.

Examples

POSTing some JSON to an endpoint, setting the Content-Type appropriately.

Cancelling an in-flight request before it completes.

EModHttpVerbs

Valid values for HTTP verbs:

GET, HEAD, POST, PUT, PATCH, DELETE, QUERY.

OnSuccess means the server returned a response

OnSuccess fires whenever a response comes back, whatever its status code. A 404, a 500, and a 302 all arrive there. Check IsOK before you use the result, or read GetResponseCode and handle the codes you care about.

OnFailure means something more fundamental went wrong: the request was rejected before being sent, the connection failed, or the request was cancelled. See Failure Types.

Redirects are not followed

A 3xx response is delivered to OnSuccess like any other. If you want to follow it, read the Location header and call StartHttpRequest again yourself.

Timeouts

Every request has a deadline. TimeoutSeconds sets it and defaults to 30 seconds. It is clamped to at most 120, and to greater than zero, so there is no way to ask for no timeout at all. A value outside that range is clamped rather than refused, and a warning naming the clamped value is written to the log.

A request that runs past its deadline is abandoned and fires OnFailure with a failure type of TimedOut. Whether the server ever saw it is unknown, so only retry if the request is safe to repeat. A GET usually is. A POST that creates something usually is not.

Ordering

Your callback never runs before StartHttpRequest has returned the handle to you, even when the request is rejected outright or the response is already available. It is always safe to store the handle first and use it from the callback.

Delivery can also be delayed by a frame or so when a response arrives at a moment the Blueprint VM cannot be entered. Do not assume a response arrives on any particular frame.

Request headers

Header names must be valid HTTP tokens: letters, digits, and ! # $ % & ' * + - . ^ _ ` | ~.

Header values must be non-empty, printable ASCII, with horizontal tab allowed. Control characters and bytes at or above 0x7F are rejected. An empty value is rejected rather than sent, because the HTTP stack would silently drop the header and leave you believing you had set it.

Reserved headers

These are set by the game and cannot be supplied by a mod:

Host, Content-Length, Transfer-Encoding, TE, Trailer, Expect, Connection, Proxy-Connection, Keep-Alive, Upgrade, Proxy-Authorization, User-Agent, X-Request-Id

Sending one fails the request with BlockedByPolicy rather than being silently ignored, so you find out at the call rather than from the far end’s behaviour.

URL rules

Beyond needing an approved origin, a URL must:

• use the http or https scheme
• carry no embedded credentials — https://user:pass@host/ is rejected
• be printable ASCII with no whitespace, control characters, or backslashes. Percent-encode anything else with UrlEncode
• be at most 8000 characters

A URL that breaks any of these fails with InvalidArguments, except for the scheme and credential rules, which fail with BlockedByPolicy.

Which mod a request is attributed to

A request is checked against the approved origins of the mod that made it, worked out by walking the Blueprint call stack and taking the outermost mod on it. Base-game frames are ignored.

So if your mod calls into a Blueprint belonging to another mod, and that Blueprint starts a request, the request is attributed to your mod and checked against your approved origins. A shared helper mod cannot make requests on your behalf under its own permissions. Every mod that calls it has to declare the origins itself and have them approved.

Request Handle

Cancel

Call Cancel on the Request Handle to drop a request that is still in-flight. It is safe to call, and does nothing, if it has already completed or was rejected.

A cancelled request still fires OnFailure, with a failure type of Cancelled. Requests still outstanding when the game shuts down are cancelled the same way.

RequestID

A read-only String on the Request Handle, unique to this request.

It is also sent to the server as the X-Request-Id header, and appears in the game’s logs. If you need to correlate something a player reports with an entry in your own server logs, this is the value to use.

Success Response

Your OnSuccess event is given a UModHttpSuccessResult object, which has the following available functions:

Header names are matched case-insensitively by both GetHeader and the map from GetAllHeaders.

Failure Response

Your OnFailure event is given a FModHttpFailureResult struct, which has the following properties:

Failure Types

You may want to branch on FailureType to retry a request, or surface an error to the player. ErrorInfo may provide additional information for logging and diagnostics, not for parsing.

A response that arrives with an error status is not a failure at this level. It goes to OnSuccess, where you read it back with IsOK and GetResponseCode.

URL helpers

UrlEncode, UrlDecode, and MakeUrlQueryString do not use the HTML form convention where + means a space. A space becomes %20. MakeFormBody is the one that uses the form convention.

MakeUrlQueryString takes an array rather than a map so that parameters keep the order you wrote them in and a field name may repeat. For example, given an array with entries ("field1", "Value With Space"), ("field1", "anothervalue"), ("field2", "some/path") it returns:

field1=Value%20With%20Space&field1=anothervalue&field2=some%2Fpath

It returns only the query string itself, with no leading ?.

MakeFormBody

MakeFormBody takes the same array and produces a request body instead of a query string. The encoding is the same except that a space becomes +, so the entries above give:

field1=Value+With+Space&field1=anothervalue&field2=some%2Fpath

Pass the result as StringContent, and set a Content-Type header of application/x-www-form-urlencoded yourself. Without that header the body goes out as text/plain; charset=utf-8 and the far end will not read it as a form.

FModHttpQueryParam

A query string entry given to MakeUrlQueryString.