# http (/docs/cloud-code/module-reference/http)



## What This Adds In Cloud Code [#what-this-adds-in-cloud-code]

* Unified outbound HTTP client for Cloud Code integrations.
* URL allowlist/security validation before request execution.
* Consistent response shape for all verbs.

## Quick Start [#quick-start]

```js
const HTTP = require('http');
const result = HTTP.get('https://api.example.com/v1/status');
```

## API [#api]

| Function                       | Params                         | Returns        | Notes                                 |
| ------------------------------ | ------------------------------ | -------------- | ------------------------------------- |
| `get(url, options)`            | URL + optional request options | `HttpResponse` | No body payload.                      |
| `head(url, options)`           | URL + optional request options | `HttpResponse` | Headers only from upstream.           |
| `delete(url, options)`         | URL + optional request options | `HttpResponse` | No body payload by default.           |
| `post(url, payload, options)`  | URL + body + request options   | `HttpResponse` | Payload serialized by runtime client. |
| `put(url, payload, options)`   | URL + body + request options   | `HttpResponse` | Same options as `post`.               |
| `patch(url, payload, options)` | URL + body + request options   | `HttpResponse` | Same options as `post`.               |

`HttpResponse` shape:

```js
{ code: 200, headers: { ... }, body: '...', cookies: { ... } }
```

`options` behavior:

* All non-reserved keys are forwarded as request headers (for example `Authorization`, `Content-Type`).
* Reserved key `base64: true` base64-encodes response body.
* Reserved key `skipUrlNormalization: true` skips URL normalization.

## Practical Example [#practical-example]

```js
const HTTP = require('http');

const syncResponse = HTTP.post(
  'https://partner.example.com/api/sync',
  JSON.stringify({ email: request.params.email, consent: true }),
  {
    Authorization: `Bearer ${Nimbu.Site.env.get('PARTNER_TOKEN')}`,
    'Content-Type': 'application/json'
  }
);

if (syncResponse.code >= 400) {
  throw new Error(`Partner sync failed: ${syncResponse.code}`);
}
```

## Failure Modes & Gotchas [#failure-modes--gotchas]

* Blocked/unsafe URLs are rejected by URL security checks.
* Timeout is fixed to Cloud Code HTTP runtime defaults (\~15s).
* Redirects are not automatically followed.

## Related Modules [#related-modules]

* [oauth2](./oauth2)
* [googleauth](./googleauth)
* [site-variables](./site-variables)