Send requests
How a request is saved
The YAML file that Luvin writes for each request, the keys it contains, how folders are stored and which values never reach the file.
In a workspace, every request is one readable YAML file. You can open it in any editor, review it in a pull request and keep it in git together with the collection.
A complete request file
Section titled “A complete request file”This is the file that Luvin writes for a request named Create post: a POST with a Bearer token from a variable and a JSON body.
name: Create postkind: httpmethod: POSTurl: "{{baseUrl}}/posts"headers: - key: X-Trace value: "{{traceId}}"auth: type: bearer token: "{{token}}" prefix: Bearerbody: mode: json text: |- { "title": "Hello Luvin", "body": "My first post", "userId": 1 }requiredFields: - body:title - body:userIdWhere the files live
Section titled “Where the files live”Requests are in the requests/ folder of the collection. A folder in the sidebar is a real subfolder, with a small marker file inside.
Directoryshop/ a collection
- collection.yaml
Directoryenvironments/
- local.yaml
Directoryrequests/
- get-post.request.yaml
- create-post.request.yaml
Directorycustomers/
- _folder.request.yaml the folder marker
- list-customers.request.yaml
- create-customer.request.yaml
Directoryuploads/
- _folder.request.yaml
- upload-avatar.request.yaml
- The file name is the request name in lowercase, without accents, with hyphens: Create post becomes
create-post.request.yaml. If the name is taken, Luvin adds-2,-3and so on. - Renaming a request in Luvin renames the file. Dragging a request onto a folder moves the file.
- The marker
_folder.request.yamlkeeps the visible name of the folder, with spaces and capitals:
kind: foldername: CustomersA subfolder you create by hand on disk also appears in the sidebar, even without a marker. Its name is the name of the folder.
The keys
Section titled “The keys”Luvin leaves out every key that is empty, so a file only has what the request uses.
| Key | What it holds |
|---|---|
name, kind |
The name, and the type: http, graphql, grpc or websocket. A file without a valid kind is not read as a request. |
description |
The text of the request, when it has one. |
method, url |
The method (HTTP and GraphQL) and the address. For gRPC the url is host:port; for WebSocket it starts with ws:// or wss://. |
params, headers |
A list of rows (see below). In gRPC the headers are saved as metadata. |
auth |
The authorization. Not written when the type is No Auth. |
body |
HTTP only: mode and then text, form or file for that mode. Not written with No Body. |
query, variables |
GraphQL: the query, and the variables when they are not {}. |
proto, service, rpc, message, tls |
gRPC. |
messages |
WebSocket: the saved messages, each with a name and a text. |
autoHeadersOff |
The automatic headers you unticked, in lowercase. |
requiredFields |
The fields you marked as required, such as query:bank or body:title. |
examples |
The responses saved as examples. |
params, headers and the fields of a form share one shape:
params: - key: userId value: "1" - key: _limit value: "10" enabled: false description: Not sentenabled: false appears only on unticked rows.
Body types
Section titled “Body types”mode is one of json, text, xml, sparql, urlencoded, formdata or file. The first four write the text in text. urlencoded and formdata write a form list. file writes a file.
A file field of a Multipart Form keeps the path of the file, not its content:
name: Upload avatarkind: httpmethod: POSTurl: "{{baseUrl}}/avatars"auth: type: inheritbody: mode: formdata form: - key: name value: Ana - key: avatar type: file file: path: /Users/ana/pics/ana.png name: ana.png contentType: image/pngIn the browser version a file has no path on disk, so path is saved empty and Luvin asks you to choose the file again. See Body.
Saved examples
Section titled “Saved examples”The responses you save with Save response go in the same file, under examples. An example keeps the request (method, URL, params, headers and body) and the response. It does not keep the authorization.
examples: - id: m1x2 name: 201 - Create post savedAt: 2026-11-17T14:03:22.000Z request: method: POST url: "{{baseUrl}}/posts" body: mode: json text: '{"title":"Hello Luvin"}' response: status: 201 statusText: Created durationMs: 312 headers: content-type: application/json; charset=utf-8 body: |- { "title": "Hello Luvin", "id": 101 }See Cookies and saved examples.
Where secrets go
Section titled “Where secrets go”Some fields of the auth block are secrets: token, password, value (of an API Key), consumerSecret, tokenSecret, clientSecret, secretAccessKey, sessionToken, clientToken and accessToken.
| You type in the field | In the file | Where the value is |
|---|---|---|
{{token}} (a variable) |
token: "{{token}}" |
In your environment. |
s3cr3t (as-is) |
The key is left out | Encrypted on this computer. The desktop app uses the keychain of the operating system; the browser version encrypts it in the browser. |
For example, a Basic Auth request with the password typed as-is is saved with the username only:
auth: type: basic username: anaThe authorization of the whole collection is written to collection.yaml, with the same rules:
version: 1name: Shopauth: type: bearer token: "{{token}}"Edit a file by hand
Section titled “Edit a file by hand”It is safer to change a request in the app: it has a fixed shape and Luvin rewrites the file when you change something. If you do edit a file with another program, keep the keys above and the YAML valid. Luvin reads the files when you open a collection, so close the workspace (Close and switch workspace) and open it again to see the change. See What is on disk.