.http files

Many developers keep requests in plain-text .http files next to their code, for VS Code’s REST Client or JetBrains’ HTTP Client. Cloak Proxy reads and writes the same format, so you can bring those requests into the API client, run them with scripts, tests and environments, and give them back to your editor.

@baseUrl = https://api.example.com

### Orders / Create order
# @name createOrder
POST {{baseUrl}}/orders HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{"sku": "TEE-01", "qty": 2}

Import a .http file

1. In the API client, click Import in the toolbar.
2. Click Choose Files… and pick one or more .http or .rest files, or paste the file’s text into the sheet. You can also drop files on the window.
3. Click Import. The file becomes a collection named after it.

In the file	Becomes
@name = value lines before a request	Collection variables, used as {{name}}
###	The start of a request. Text after it names the request
### Folder / Name	A request in a folder (nested for more /)
# @name createOrder	The request’s name when ### has no text
# and // lines before the request line	The request’s docs
METHOD URL HTTP/1.1	Method and URL. Without a method, GET. Lines starting with ? or & continue the URL
Name: value lines	Headers
The text after a blank line	The body. JSON, XML and text become a raw body by Content-Type; x-www-form-urlencoded becomes form fields
X-Request-Type: GraphQL	A GraphQL body: the query, then a blank line and the variables as JSON
< ./body.json	A file body

Response handler scripts (> {% … %}, > ./handler.js) and >> response.json lines aren’t imported: Cloak Proxy’s scripts use the pm API instead. The collection’s Overview lists what was left out, so you can add tests in each request’s Scripts tab.

Tip

Run a .http file directly in CI: cloakctl collection run requests.http treats it as a collection, with your environments and scripts. See cloakctl.

Export a collection as .http

Right-click a collection and choose Export › .http File (REST Client, JetBrains)…, or choose it from More in the collection’s tab.

The file starts with the collection’s variables (secret ones are left out and listed in a comment), then has one block per HTTP and GraphQL request:

• ### Folder / Name and # @name with a camel-case name.
• The request’s docs as comments.
• Its query parameters in the URL.
• Every header it sends, including headers it inherits from its folders and collection.
• Bearer, Basic and API key auth (its own or inherited) as headers, with {{variables}} left in place.
• The body. Form-data bodies aren’t written, and the block says which fields they had.

Requests of other kinds (gRPC, WebSocket, MQTT…) are left out.

Copy one request

• In the API client, right-click a request and choose Copy as .http.
• In the traffic list, right-click captured requests and choose Copy as › .http (REST Client). Each becomes a block with its headers (without Host and Content-Length) and its decoded body. In the inspector’s code view, choose .http (REST Client) in the language menu.

Use from an AI assistant or the command line

Tool or command	Does
import_into_client	Takes .http text or a .http / .rest path, as well as the other formats
export_http_file	Returns a collection (or one folder) as a .http file, or writes it to path
cloakctl collection import FILE.http	Adds the file to the workspace as a collection
cloakctl collection export NAME --out FILE.http [--folder NAME]	Writes a collection as a .http file
cloakctl collection run FILE.http	Runs the file’s requests, Newman-style

Related

Import and exportPostman, OpenAPI, HAR, Insomnia and cURL.

Variables and environmentsEnvironments built on a base, and .env files.

Collections and requestsHeaders every request in a folder sends.