# HTTP

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

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

> [!IMPORTANT]
> All `http::*` functions require network capabilities, which are **denied by default**. Start the server with `--allow-net` (optionally scoped to specific targets); otherwise calls fail with `Access to network target '…' is not allowed` (verified on v3.2.0). See [Capabilities](/docs/learn/security/authorization/capabilities.md).

<table>
  <thead>
    <tr>
      <th scope="col">Function</th>
      <th scope="col">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td scope="row" data-label="Function"><a href="#httphead"><code>http::head()</code></a></td>
      <td scope="row" data-label="Description">Perform a remote HTTP HEAD request</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#httpget"><code>http::get()</code></a></td>
      <td scope="row" data-label="Description">Perform a remote HTTP GET request</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#httpput"><code>http::put()</code></a></td>
      <td scope="row" data-label="Description">Perform a remote HTTP PUT request</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#httppost"><code>http::post()</code></a></td>
      <td scope="row" data-label="Description">Perform a remote HTTP POST request</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#httppatch"><code>http::patch()</code></a></td>
      <td scope="row" data-label="Description">Perform a remote HTTP PATCH request</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#httpdelete"><code>http::delete()</code></a></td>
      <td scope="row" data-label="Description">Perform a remote HTTP DELETE request</td>
    </tr>
  </tbody>
</table>

## Response encoding and errors

Failed requests return descriptive errors with the relevant HTTP status code when the remote server provides one.

Response bodies encode SurrealQL values as follows:

- **Bytes**, sent as raw bytes (not base64- or JSON-encoded).
- **Strings**, sent as raw strings.
- **Other values** (numbers, arrays, objects, booleans, and so on), JSON-encoded.

SurrealDB does not add `Content-Type: application/octet-stream` automatically when the body contains byte values. You can set this header yourself if a client requires it.

## `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.

```surql title="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.

```surql title="API DEFINITION"
http::head(string, $headers: object) -> null
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

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

null
```

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

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

null
```

<br />

## `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.

```surql title="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.

```surql title="API DEFINITION"
http::get(string, $headers: object) -> value
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
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:

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

-- The HTML code is returned
```

<br />

## `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.

```surql title="API DEFINITION"
http::put(string, $body: object) -> value
```

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

```surql title="API DEFINITION"
http::put(string, $body: object, $headers: object) -> value
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql title="Request without headers"
RETURN http::put('https://jsonplaceholder.typicode.com/posts/1', {
  id: 1,
  body: "This is some awesome thinking!",
  postId: 100,
  user: {
    id: 63,
    username: 'eburras1q'
  }
});
```

```surql title="Request with headers"
RETURN http::put('https://jsonplaceholder.typicode.com/posts/1', {
  id: 1,
  body: "This is some awesome thinking!",
  postId: 100,
  user: {
    id: 63,
    username: 'eburras1q'
  }
}, {
  'Authorization': 'Bearer your-token-here',
  'Content-Type': 'application/json',
  'x-custom-header': 'custom-value'
});
```

```surql title="Response"
{
	body: 'This is some awesome thinking!',
	id: 1,
	postId: 100,
	user: {
		id: 63,
		username: 'eburras1q'
	}
}
```

<br />

## `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.

```surql title="API DEFINITION"
http::post(string, $body: object) -> value
```
If an object is given as the third argument, then this can be used to set the request headers.

```surql title="API DEFINITION"
http::post(string, $body: object, $headers: object) -> value
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql title="Request without headers"
RETURN http::post('https://jsonplaceholder.typicode.com/posts/', {
  id: 1,
  body: "This is some awesome thinking!",
  postId: 100,
  user: {
    id: 63,
    username: "eburras1q"
  }
});
```

```surql title="Request with headers"
RETURN http::post('https://jsonplaceholder.typicode.com/posts/', {
  id: 1,
  body: "This is some awesome thinking!",
  postId: 100,
  user: {
    id: 63,
    username: "eburras1q"
  }
}, {
  'Authorization': 'Bearer your-token-here',
  'Content-Type': 'application/json',
  'x-custom-header': 'custom-value'
});
```

```surql title="Response"
{
	body: 'This is some awesome thinking!',
	id: 101,
	postId: 100,
	user: {
		id: 63,
		username: 'eburras1q'
	}
}
```

<br />

## `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.

```surql title="API DEFINITION"
http::patch(string, $body: object) -> value
```
If an object is given as the third argument, then this can be used to set the request headers.

```surql title="API DEFINITION"
http::patch(string, $body: object, $headers: object) -> value
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql title="Request without headers"
RETURN http::patch('https://jsonplaceholder.typicode.com/posts/1', {
  id: 1,
  body: "This is some awesome thinking!",
  postId: 100,
  user: {
    id: 63,
    username: "eburras1q"
  }
});
```

```surql title="Setting the request headers"
RETURN http::patch('https://jsonplaceholder.typicode.com/posts/1', {
  id: 1,
  body: "This is some awesome thinking!",
  postId: 100,
  user: {
    id: 63,
    username: "eburras1q"
  }
}, {
  'Authorization': 'Bearer your-token-here',
  'Content-Type': 'application/json',
  'x-custom-header': 'custom-value'
});
```

```surql title="RESPONSE"
{
	body: 'This is some awesome thinking!',
	id: 1,
	postId: 100,
	title: 'sunt aut facere repellat provident occaecati excepturi optio reprehenderit',
	user: {
		id: 63,
		username: 'eburras1q'
	},
	userId: 1
}
```

<br />

## `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.

```surql title="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.

```surql title="API DEFINITION"
http::delete(string, $headers: object) -> value
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN http::delete('https://jsonplaceholder.typicode.com/posts/1');

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

```surql
RETURN http::delete('https://jsonplaceholder.typicode.com/posts/1', {
	'x-my-header': 'some unique string'
});

{}
```

<br /><br />