protocols
HTTP requests
Build and send HTTP requests in Cloak Proxy's API client, with params, path variables, every body type, redirects, TLS, timeouts, Unix sockets and timing.
An HTTP request is the default request type in the API client: a method, a URL, headers and an optional body, sent to a REST or any other HTTP API. Use it to call an endpoint by hand, to check what a server returns, or as a step in a collection you run and test. By default the request goes through Cloak Proxy itself, so it also shows up in the traffic list and your debugging tools apply to it.
Create an HTTP request
Section titled “Create an HTTP request”-
Open the API client with ⇧ ⌘ O. See API client overview.
-
Create the request in one of these ways:
Where How Toolbar Click New › HTTP Request. It opens as an unsaved request in a new tab. Collections sidebar Right-click a collection and choose Add Request. Search Everything Press ⇧ ⌘ A and run New HTTP Request. -
Pick a method from the menu at the left of the URL bar and type the URL, for example
https://api.example.com/v1/users. -
Press ⌘ ↩ or click Send. The response appears in the bottom half of the tab.
-
To keep an unsaved request, open the Save menu (⌘ S) and choose a collection, or New Collection….
An HTTP request with a path variable, and its response in the Tree view.
- Method menu
- URL: type one, use {{variables}}, or paste a cURL command
- Send (⌘↩)
- Code: snippets for this request
- Path Variables fill in :name segments of the URL
- Status, total time and body size
The sidebar shows HTTP requests with their method (GET, POST and so on) in its color. Other request types are covered in their own pages: GraphQL, gRPC, WebSocket, Socket.IO, MQTT, MCP, AI, SQL and data and TCP and UDP.
Set the method and URL
Section titled “Set the method and URL”The method menu offers GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS.
The URL field accepts:
| You type | What happens |
|---|---|
| A full URL | Sent as is. A URL without a scheme gets http:// in front. |
{{name}} variables |
Filled in from the active environment, the collection, globals and the vault when you send. See Variables and environments. |
A query string (?page=2&limit=50) |
Each pair becomes a row in Params, and editing Params rewrites the query string. Rows you switch off stay in the table but leave the URL. |
A :name path segment (/pets/:petId) |
Adds a row under Path Variables. The segment is replaced with that row’s value when you send. |
A command starting with curl |
Imported: the method, URL, headers and body are taken from the command. A JSON body is set to Raw with the JSON language. |
For example, both of these produce the same request:
POST {{baseUrl}}/v1/users?notify=trueThen choose Body › Raw › JSON and enter { "name": "Ada Park", "email": "ada@example.com" }.
curl -X POST 'https://api.example.com/v1/users?notify=true' \ -H 'Content-Type: application/json' \ -d '{"name":"Ada Park","email":"ada@example.com"}'If the URL or a header uses a variable that isn’t defined anywhere, a warning under the URL bar lists it: Not defined in the active environment, collection or globals. Sending a request whose URL still contains an undefined variable fails with The URL uses {{name}}, which isn’t defined in the environment, collection or globals.
Request tabs
Section titled “Request tabs”| Tab | What it holds |
|---|---|
| Params | Query Params (key, value, description, on/off) and, when the URL has :name segments, Path Variables. The tab badge counts both. |
| Authorization | The auth type for this request, or inherited from its folder or collection. See Authorization. |
| Headers | Request headers. Cloak Proxy also sends User-Agent, Accept, Host, Content-Length and cookies from the cookie jar when you don’t set them. |
| Body | The request body (see below). |
| Scripts | Pre-request and post-response JavaScript with the pm API. See Scripts and tests. |
| Settings | Transport settings for this request (see below). |
| Docs | Markdown documentation for the request, used in generated docs. See Examples and docs. |
A dot on a tab means it has content; numbers count enabled rows.
Body types
Section titled “Body types”Pick the body type with the radio buttons at the top of Body:
| Type | What is sent | Content-Type set automatically |
|---|---|---|
| None | No body. | None |
| Raw | The text in the editor. Choose a language: JSON, TEXT, XML, HTML or JAVASCRIPT. | application/json, text/plain, application/xml, text/html or application/javascript |
| x-www-form-urlencoded | The key/value table, form-encoded. | application/x-www-form-urlencoded |
| form-data | A multipart body. Each row is a text field or a file; for files the value is a path. The file’s type is guessed from its extension. | multipart/form-data with a boundary |
| Binary | The contents of one file. Click Choose File…. | application/octet-stream |
| GraphQL | A query and JSON variables. See GraphQL requests. | application/json |
A Content-Type you set yourself in Headers always wins. Variables are filled in inside raw bodies, form fields, file paths and GraphQL variables.
Request settings
Section titled “Request settings”The Settings tab controls how this one request is sent:
| Setting | Default | What it does |
|---|---|---|
| Send through Cloak Proxy (shows in traffic; debugging tools apply) | On | Routes the request through Cloak Proxy on its listening port (9090 by default), so it appears in the main traffic list and tools such as Breakpoint and Map Local can act on it. Off, the request goes straight to the server. It also goes direct while Cloak Proxy isn’t listening, and when the URL points at Cloak Proxy’s own port on localhost. |
| Follow redirects | On | Follows up to 10 redirects. Off, you see the 3xx response itself. |
| Verify TLS certificates | On | Off accepts any server certificate, for self-signed development servers. |
| Encode the URL automatically | On | Percent-encodes characters that aren’t valid in a URL, such as spaces, and leaves existing escapes alone. |
| Timeout (ms, 0 = default 30 s) | 0 |
How long to wait for the response before giving up with The request timed out. 0 uses the 30 second default. |
| Unix socket (e.g. /var/run/docker.sock) | Empty | Sends the request over a Unix domain socket instead of TCP. Click Docker to fill in /var/run/docker.sock. |
With a Unix socket, the URL’s host is ignored and only its path and query are sent over the socket. For example, with Unix socket set to /var/run/docker.sock, this request lists your Docker containers:
GET http://localhost/v1.43/containers/jsonUnix socket requests never go through Cloak Proxy.
Other limits that apply to every HTTP request: connecting gives up after 15 seconds, and a response body larger than 50 MB is cut off and marked as truncated.
Read the response
Section titled “Read the response”The response header shows the status (green for 2xx, orange for 3xx, red for 4xx and 5xx), the total time and the body size. Save as Example stores the response as a saved example of the request, and Copy Body copies the body as text.
| Tab | What it shows |
|---|---|
| Body | The body in the same viewers as the traffic inspector: JSON tree, pretty, raw and hex, HTML and image previews. See Body viewers. |
| Visualize | Appears when a script calls pm.visualizer.set(…); renders its HTML. |
| Headers | Response headers, with a count in the tab. |
| Cookies | The client’s cookie jar. Cookies a response sets are stored and sent with later requests to the same site. |
| Test Results | Each pm.test with PASS, FAIL or SKIP, and the error for failures. The tab shows passed/total. |
| Console | console.log output and script errors. |
| Request | What was actually sent, after scripts, variables, auth and cookies: method, URL, headers and body. |
| Timing | How long each phase took (below). |
If the request can’t be sent at all, the bottom half shows Couldn’t send the request with the reason, such as The request timed out, Couldn’t connect to api.example.com:443 (DNS lookup failed) or The server closed the connection. Post-response scripts still run in that case, with pm.response undefined.
Timing splits a send into script time and network time.
- Timing tab
| Row | What it measures |
|---|---|
| Pre-request scripts | Time spent in the collection, folder and request pre-request scripts. |
| Waiting (TTFB) | From sending until the response headers arrived. Includes connecting and TLS. |
| Download | Reading the response body. |
| Post-response scripts | Time spent in post-response scripts and tests. |
The footer shows the total and the time the send started.
What happens when you send
Section titled “What happens when you send”Cloak Proxy runs a send in the same order Postman does:
- Pre-request scripts run: the collection’s, then each folder’s, then the request’s. They see the request before variables are filled in, and can change it or skip it with
pm.execution.skipRequest(). - Variables and path variables are filled in, and the URL is encoded if that setting is on.
- Auth is applied, using the request’s own type or the nearest folder or collection that sets one. With Digest auth, Cloak Proxy answers the server’s
401challenge once and sends the request again. With OAuth 2.0 and no token yet, the console warns you to use Get New Access Token. - Cookies from the jar are added unless you set a
Cookieheader. - The request is sent, and cookies in the response are stored.
- Post-response scripts and tests run in the same collection, folder, request order.
Every send is added to History.
While a request is in flight, Send turns into Cancel. Clicking it lets you send again right away; the earlier request still finishes or times out in the background.
Get code for a request
Section titled “Get code for a request”Click Code at the top right of the request to see it as a cURL command or a snippet in another language. Fill in variables controls whether {{variables}} are replaced with their current values. Auth from the Authorization tab is added only at send time, so it isn’t in the snippet unless you set it as a header. See Code snippets.