SurrealDB Docs Logo

Enter a search query

HTTP functions

These functions can be used when opening and submitting remote web requests, and webhooks.

FunctionDescription
http::head()Perform a remote HTTP HEAD request
http::get()Perform a remote HTTP GET request
http::put()Perform a remote HTTP PUT request
http::post()Perform a remote HTTP POST request
http::patch()Perform a remote HTTP PATCH request
http::delete()Perform a remote HTTP DELETE request

http::head

The http::head function performs a remote HTTP HEAD request. The first parameter is the URL of the remote endpoint. If the response does not return a 2XX status code, then the function will fail and return the error.

API DEFINITION
http::head(string) -> null

If an object is given as the second argument, then this can be used to set the request headers.

API DEFINITION
http::head(string, object) -> null

The following example shows this function, and its output, when used in a RETURN statement:

RETURN http::head('https://surrealdb.com'); null

To specify custom headers with the HTTP request, pass an object as the second argument:

RETURN http::head('https://surrealdb.com', { 'x-my-header': 'some unique string' }); null

http::get

The http::get function performs a remote HTTP GET request. The first parameter is the URL of the remote endpoint. If the response does not return a 2XX status code, then the function will fail and return the error. If the remote endpoint returns an application/json content-type, then the response is parsed and returned as a value, otherwise the response is treated as text.

API DEFINITION
http::get(string) -> value

If an object is given as the second argument, then this can be used to set the request headers.

API DEFINITION
http::get(string, object) -> value

The following example shows this function, and its output, when used in a RETURN statement:

RETURN http::get('https://surrealdb.com'); -- The HTML code is returned

To specify custom headers with the HTTP request, pass an object as the second argument:

RETURN http::get('https://surrealdb.com', { 'x-my-header': 'some unique string' }); -- The HTML code is returned

http::put

The http::put function performs a remote HTTP PUT request. The first parameter is the URL of the remote endpoint, and the second parameter is the value to use as the request body, which will be converted to JSON. If the response does not return a 2XX status code, then the function will fail and return the error. If the remote endpoint returns an application/json content-type, then the response is parsed and returned as a value, otherwise the response is treated as text.

API DEFINITION
http::put(string, object) -> value

If an object is given as the second argument, then this can be used to set the request headers.

API DEFINITION
http::put(string, object, object) -> value

The following example shows this function, and its output, when used in a RETURN statement:

RETURN http::put('https://dummyjson.com/comments', { "id": 1, "body": "This is some awesome thinking!", "postId": 100, "user": { "id": 63, "username": "eburras1q" } }); { "id": 1, "body": "This is some awesome thinking!", "postId": 100, "user": { "id": 63, "username": "eburras1q" } }

http::post

The http::post function performs a remote HTTP POST request. The first parameter is the URL of the remote endpoint, and the second parameter is the value to use as the request body, which will be converted to JSON. If the response does not return a 2XX status code, then the function will fail and return the error. If the remote endpoint returns an application/json content-type, then the response is parsed and returned as a value, otherwise the response is treated as text.

API DEFINITION
http::post(string, object) -> value

If an object is given as the second argument, then this can be used to set the request headers.

API DEFINITION
http::post(string, object, object) -> value

The following example shows this function, and its output, when used in a RETURN statement:

RETURN http::post('https://dummyjson.com/comments/1', { "id": 1, "body": "This is some awesome thinking!", "postId": 100, "user": { "id": 63, "username": "eburras1q" } }); { "id": 1, "body": "This is some awesome thinking!", "postId": 100, "user": { "id": 63, "username": "eburras1q" } }

http::patch

The http::patch function performs a remote HTTP PATCH request. The first parameter is the URL of the remote endpoint, and the second parameter is the value to use as the request body, which will be converted to JSON. If the response does not return a 2XX status code, then the function will fail and return the error. If the remote endpoint returns an application/json content-type, then the response is parsed and returned as a value, otherwise the response is treated as text.

API DEFINITION
http::patch(string, object) -> value

If an object is given as the second argument, then this can be used to set the request headers.

API DEFINITION
http::patch(string, object, object) -> value

The following example shows this function, and its output, when used in a RETURN statement:

RETURN http::patch('https://dummyjson.com/comments/1', { "id": 1, "body": "This is some awesome thinking!", "postId": 100, "user": { "id": 63, "username": "eburras1q" } }); { "id": 1, "body": "This is some awesome thinking!", "postId": 100, "user": { "id": 63, "username": "eburras1q" } }

http::delete

The http::delete function performs a remote HTTP DELETE request. The first parameter is the URL of the remote endpoint, and the second parameter is the value to use as the request body, which will be converted to JSON. If the response does not return a 2XX status code, then the function will fail and return the error. If the remote endpoint returns an application/json content-type, then the response is parsed and returned as a value, otherwise the response is treated as text.

API DEFINITION
http::delete(string) -> value

If an object is given as the second argument, then this can be used to set the request headers.

API DEFINITION
http::delete(string, object) -> value

The following example shows this function, and its output, when used in a RETURN statement:

RETURN http::delete('https://dummyjson.com/comments/1'); null

To specify custom headers with the HTTP request, pass an object as the second argument:

RETURN http::delete('https://dummyjson.com/comments/1', { 'x-my-header': 'some unique string' }); null


On this page

© SurrealDB GitHub Discord Community Cloud Features Releases Install