Help › Guide

Requests

Reqlyn 0.5.1 is not released yet. This help describes it ahead of release.

The Requests destination is the first icon on the rail. Its sidebar lists your saved requests (COLLECTIONS) and what you have sent (HISTORY). The work panel is the request editor.

Sending a request

  1. Choose the method: GET, POST, PUT, PATCH, DELETE, HEAD or OPTIONS.
  2. Type the address, such as http://127.0.0.1:8787/devices. An address with no scheme, such as 127.0.0.1:8787/devices, is not sent: Reqlyn says "Begin the address with http:// or https://. Nothing was sent." with "Use https://" and "Use http://", either of which puts that scheme in front and sends it. No scheme is assumed for you.
  3. Press Send, Ctrl Enter, or Enter in the address field.

While it is under way, Send becomes Cancel (Ctrl .); cancelling closes the connection and leaves the request as you wrote it. Under "Response" you see the status, how long it took, the size, and the body.

Requests are sent from this computer. Redirects are never followed: a redirect comes back as the response it is, so a credential goes only where you sent it. Proxy settings of the operating system and the environment are not used; a proxy is used only when you set one under Connections.

Query parameters

The Params tab lists the address's query, one parameter a row, and keeps the two the same: typing ?site=lax&role=PE in the address makes two rows, and editing a row writes the address again, each name and value encoded once (a b&c becomes a%20b%26c) and {{variables}} left as written. Its count is the parameters that are sent. A row turned off leaves the address and is kept with the request, not sent; turned on again, it goes back at the end of the query.

Checks

The Checks tab holds what the response is tested for each time the request is sent: its status, a header, or a value in its body; compared ("is", "is not", "below", "at most", "above", "at least" a value), matched against a pattern, or selected by a JSONPath query such as $.items[[email protected] == 'active']. They are an operation step's own criteria, kept with the request, synchronized and exported with it. After a send, the response line says how many held ("All 2 checks hold", "1 of 2 checks hold"), and each check says "holds", "does not hold", or why it could not be read.

Running a folder

Right-click a folder and choose "Run folder" to send its saved requests one after the other from this computer, each with its checks; the run lists each with its status and how many of its checks held, then says whether every one answered and held. A request that does not only read (anything but GET, HEAD and OPTIONS) is named first, and nothing is sent until you choose "Send them all". Nothing is sent twice. A run with inputs, values passed from one request to the next, and a data file is an operation.

Headers

The Headers tab lists the request's headers, with a count of those turned on. "+ Add header" adds one; each can be turned off without removing it. Reqlyn adds only what the body needs, such as its Content-Type.

Body

The Body tab chooses the kind:

  • No body.
  • Text: sent as written.
  • JSON: checked as JSON before it is sent, after variables are filled.
  • Form: fields sent as application/x-www-form-urlencoded, encoded when the request is sent, so a value cannot add a field.
  • Multipart: parts that are text or a file chosen on this computer, 50 MiB at most. A file is read only when the request is sent, and only from the full path the file dialog gave.

Auth

The Auth tab chooses a credential kept under Connections, and a client certificate. The secret itself is never part of the request: it is read from the operating system's secret store when the request is sent. A request that uses a credential and also sets its own Authorization header is refused, as is one whose credential was deleted.

Saving and organizing

Requests open in tabs above the editor. Choosing a saved request in the sidebar opens it in a tab of its own, or shows the tab already holding it; the plus at the end of the tabs, or Ctrl N, starts a new one beside the others. Each tab keeps its own response, and one sent from a tab you have left is there when you come back. A tab with unsaved changes has a dot; closing it asks you to save or discard them. The saved requests you had open come back the next time Reqlyn starts.

Name the request in "Name this request" and press Save (Ctrl S); saved with no name, it is named for its method and path, such as "GET /devices", which you can change. The state beside the name says "Not saved", "Saving" or "Saved on this computer". Leaving a request with changes asks you to save or discard them.

Under the name, "What it is for, optional" holds a description of the request, kept and exported with it; resting the pointer on the request in the sidebar shows it.

In the sidebar:

  • the folder icon makes a folder, and a request can be moved into one;
  • the plus starts a new request (Ctrl N);
  • "Find a request" narrows the list to the saved requests whose name holds what you type;
  • right-click a saved request for its menu, which duplicates it or moves it to a folder.

"Use in an operation" beside a saved request starts a new operation whose first step sends it (see Operations).

"Export saved requests" in the command palette writes your requests as Reqlyn definitions, with no secret in them. "Export saved requests as an OpenCollection (Bruno)" writes them as a folder Bruno opens: opencollection.yml, a folder.yml for each folder and a .yml file for each request; a request's credential is written as auth: inherit, never its value. "Export saved requests as a Postman Collection 3.0" writes them as Postman's Git-native YAML: .resources/definition.yaml for the collection and each folder, and a <name>.request.yaml for each request, its query written in queryParams too, a credential as auth: {type: inherit}.

A folder workspace

A folder can be the workspace, its files the authority for the requests: one file a request, requests/<id>.yaml, in Reqlyn's definition format, kept with your own tools and in your own repository. Set REQLYN_FOLDER to the folder before starting Reqlyn or a command. Its index, runs and history are kept in a data folder of its own under Reqlyn's (named for the folder's full path), never in the folder, so every window and command on one folder shares them.

On opening and at each sync, a file changed outside Reqlyn, by Git, an editor or another window, is taken as it is written, and left as written: Reqlyn does not rewrite it in its own form. A file an editor adds is a request; a request whose file is deleted, as a branch switch may do, is gone, its history kept. A file that does not parse is said and left as it is, and a save does not overwrite it. A save writes the request's file.

Operations are files too: operations/<id>.yaml, and beside it what is kept for the operation, its regression cases (<id>.cases.yaml, a cases pack), its example (<id>.example.json) and its negative cases as last sent (<id>.negatives.yaml). An operation whose file goes is gone with them, and comes back with them when the files do, as on a switch to another branch and back. A case kept, changed or removed here is written to its file; when that file was changed outside first, it is left as it is and said, and the next sync takes it. Environments are files too: each created environment is environments/<name>.yaml (reqlyn: environment/1), its variables in order, a secret one named with no value. A secret's value stays in this computer's secret store and is never written; a file that writes one is refused. An environment taken from a file with a secret variable needs its value typed on each computer. When an environment's file goes, as on another branch, the environment stays here with what was typed for it, and its file is not put back unless the environment is changed here; deleting an environment here removes its file. The environment that always exists has no file.

On the desktop, "Open a folder as a workspace…" in the command palette (Ctrl K) opens a folder in a window of its own, named "Folder · <folder>" in the title bar; the window follows the folder, so a change made by Git (a branch switched, a pull), an editor or another window shows in its lists within a second, and a file it could not take is said above the editor. Windows on one folder share its index. A request open in a tab is not refreshed when its file changes; open it again. Settings, under the folder workspace, has Git for the folder: commit, pull and push, the branches ("Switch to <name>"), and a field to make a branch and switch to it; a switch shows the other branch's requests at once. "Propose this branch" pushes the branch checked out and shows the forge's page for a pull request from it (GitHub, GitLab or Gitea, read from the remote's address), with "Open"; no token is asked for, the forge asks what it needs when the page opens. "History in Git" beside a saved request lists the commits that changed its file, newest first, each with what it changed, and what is changed and not committed above them. Reqlyn's pull only fast-forwards and never merges; a file a merge made in Git leaves in conflict is said (it does not parse) and shown in Settings as each side has it, with "Keep mine" and "Take theirs", which resolve and stage it for you to commit.

Variables and environments

Write {{name}} in the address, an enabled header or the body, and the variable's value is put there when the request is sent. Typing {{ at the end of the address lists the names that fit.

The Variables tab holds the variables of the environment chosen beside Send ("Default" unless you made others). "Add variable", then "Save variables": sends use the saved values, not what is typed and not yet saved. A variable with no value stops the send before anything leaves, naming it: "No value is defined for {{rack}}."

  • Secret variables: mark a variable Secret and its value goes to the operating system's secret store, not to the database. It is shown masked ("Hidden. Type to replace it") and never written to history or exports.
  • At a glance: resting the pointer on the environment chooser names its first six variables with their values ("Sent with Lab: base = http://127.0.0.1:8787; token (secret)"), a secret one by name only.
  • Environments: "New environment…" in the chooser makes one, which starts with no variables. Choosing another environment first says what it changes: "Switching to Lab changes where this request goes: … → …", with Switch and Stay.

A variable's value is put in as text. Values are never converted, and an input that holds braces is refused where it could be read as a placeholder.

Responses

Drag the line between the request and the response to give either more room; Reqlyn keeps where you left it. A JSON response is coloured, its lines numbered, and each object and list can be folded from the arrow beside its first line.

A response is shown in one of three ways, chosen above the body:

  • Formatted: JSON laid out and indented. Settings decides whether a new JSON response opens formatted or raw; the other is one click away.
  • Table: a list in the body as rows. "Filter rows" keeps the rows any of whose values holds the text, whatever its case, and says how many match. Columns can be hidden. At most the first 200 rows are laid out. How a saved request's table was left comes back when it is opened again.
  • Raw: the body as received.

"Show N headers" beside the time and size lists the response's headers. A header that carries a credential, such as Set-Cookie, shows [masked].

Large numbers are shown exactly as the API sent them, never rounded through a floating-point number. A body larger than the view shows at once says how much of it is shown. A response larger than 10 MiB is cut and labeled as cut.

"Find in response" finds the lines of the body that hold its text. The export icon writes the body to a file in Downloads (or REQLYN_EXPORT_DIR); a body that was cut is exported as the part received, and said so.

History

HISTORY in the sidebar lists each send newest first, under LAST 24 HOURS, LAST 7 DAYS and OLDER: the method, the status or why there was none, the address and the time. History keeps no credential and no body: a header that carried a credential is listed with "Value not kept". A request refused before anything left this computer, such as one with no valid address or a variable with no value, is said in the response and not listed. Choosing an entry opens what it sent as a new request in a tab of its own: its method, address and headers; a secret value is the word hidden, and a header whose value was not kept is turned off and empty.

Beyond request and response

Each of these is in the command palette and works on the request on screen, with its headers, variables and credential.

GraphQL

"Explore the GraphQL schema" asks the API for its schema by introspection and lists QUERIES and MUTATIONS, each with its signature, such as devices(site: String): [Device!]!. "Use" writes that query into a JSON body with its variables to fill, and sets POST. Try it on http://127.0.0.1:8787/graphql.

Server-sent events

"Listen to the response as it arrives" sends the request and shows each event as it comes, newest first: its type and id over its data. "LISTENING · 4 events" with Stop while it runs; "ENDED" or "STOPPED" with Close after. A body that is not events is shown as text as it grows. Try http://127.0.0.1:8787/events.

The stream of an LLM API reads as what it says: when its events are OpenAI's (Chat Completions or Responses), Anthropic's or Gemini's, the panel shows the text as it arrives, a line above it naming the API, the model and the tokens in and out when the stream gives them. "Show events" shows the events as they came, and "Show text" the text again.

WebSocket

"Open as a WebSocket" opens the address (ws, wss, http or https) with the request's headers and credential. A field "A message to send" with Send; messages newest first, "→" for one sent, "←" for one received. Close ends it, and it is kept in the history with the bytes received. It goes through the proxy or the bastion set under Connections, by their tunnel. Try ws://127.0.0.1:8793.

Socket.IO

A Socket.IO server is opened from a request whose address is socketio://host:port/namespace#event (or socketios:// over TLS): the namespace is the path, / when there is none, and the event the one after #. Send, or "Open as a WebSocket", connects the namespace on Socket.IO's WebSocket transport (Engine.IO 4, Socket.IO 5) in the same panel, headed "Socket.IO". What you type is emitted to the event, as JSON when it is JSON, else as a string, asking for an acknowledgement; with no event in the address, write ["event", data]. The panel shows each emit, each event the server emits as event: data, and each acknowledgement as ack N: data; the server's pings are answered without being shown. A namespace that refuses the connection is said so. Binary attachments are not sent or shown.

A step of an operation emits and hears Socket.IO events as an AsyncAPI step does on a WebSocket: a send emits the step's body to the address's event; a receive takes the next event of that name, with its name in the message's event header; an acknowledgement is heard as the event it answers, with an ack header. An AsyncAPI description whose server's protocol is socket.io is read so: its channel is the namespace, its message's name the event.

gRPC

"Call by gRPC" reads the service by server reflection, or from .proto files ("From .proto files…"), and lists each method as package.Service/Method(Input) → Output. "Use" puts the method's input as a JSON template in the body; "Call" calls it and shows the answer, or the status code and message. Metadata comes from the request's headers and credential. A method that takes a stream is given a JSON array of messages, all sent as the call starts; one that answers a stream is answered with an array of every message, up to the first 1000. Try grpc://127.0.0.1:8792, whose LookUpDevices answers each device asked for.

A step of an operation calls gRPC when its saved request's address names the method in its path: grpc://127.0.0.1:8792/inventory.Inventory/WatchDevices, its body the message or the array of them. The step reads the answer as JSON, as it reads any response: 200 for an answer, or for a status the HTTP code gRPC maps it to (NotFound is 404), with grpc-status and grpc-message headers. On this computer only. A published operation's gRPC step runs on the server and on agents too, its method described by the service's reflection: it is held to its address's destinations and the server's or agent's address guard (grpc:// read as http://), and its credential goes as metadata when it is a bearer token, Basic or a header.

MCP

An MCP server is asked from a request whose address names it: mcp+https://tools.example/mcp (or mcp+http://) for a server over Streamable HTTP, or mcp+stdio: and a command line for a program on this computer, such as mcp+stdio:npx -y @modelcontextprotocol/server-everything (quote a word with spaces). Send, or "Ask an MCP server" in the command palette, lists what it offers: its tools, each with what it says it does, its prompts and its resources. "Use" beside a tool puts a template of its arguments in the body, a JSON object; "Call" calls it with the body and shows its answer, said plainly when the tool says it failed. Over HTTP the request's variables, credential (a bearer token, Basic or a header; one that signs each request is refused), certificate authorities and route apply as they do to any request. A STDIO command is a program that runs with your permissions, so it is never started by opening, importing or sending the request: the command is shown, and only "Start" beside it runs it. A STDIO server is given no credential.

A server that asks for OAuth, as the MCP authorization specification has it, answers 401, and the panel offers "Sign in…". Reqlyn reads what the server says of itself: the address of its sign-in description in its 401, that description (RFC 9728), which names its authorization server, and that server's description (RFC 8414), which names where people sign in, where tokens are given and where clients register. It registers itself there as a client (RFC 7591), adds an OAuth sign-in credential named MCP · and the host, with what it found, and opens the sign-in in your browser; once you are back, the request uses that credential and the server is asked again. The panel's auth log says each step as it went, its addresses and the client id, never a token. A server that registers no clients is said so: add an OAuth sign-in credential with the client id it gave you, under Connections.

A step of an operation calls an MCP tool when its saved request's address names the tool after #: mcp+https://tools.example/mcp#add, its body the tool's arguments, a JSON object, with {{placeholders}} filled as in any body. Its answer reads as a response: 200, or 500 when the tool says it failed, with a JSON body of text (the tool's text), isError, content and, when the tool gives it, structuredContent; an output reads text or any part of it. The step goes where its HTTP address goes: the server's and an agent's destinations, rate limits and the credential's destinations apply to it as to any request. A step at an mcp+stdio: address is refused: a run never starts a program.

SOAP

A SOAP request is an ordinary POST: its envelope is a text body, its SOAPAction a header. Importing the service's WSDL (Discovery) writes them for each operation. When the service answers with a SOAP fault, the response says it above the body ("SOAP fault: Division by zero (soap:Server)"), and a step whose response is a fault fails saying what the fault said. A step's XPath outputs read the answer as any XML response's do.

Code snippets

"Code", beside the request's name, shows the request as curl, Python, Rust or TypeScript under the request line, its language chosen above it, with Copy. The code is written as the request stands: variables are left as {{name}}, and a credential is named in a comment, never its value.

"Copy as curl", "Copy as Python" (httpx), "Copy as Rust" (reqwest) and "Copy as TypeScript" (fetch) copy the request as code that sends it. Variables stay as {{name}}, a likely secret is masked and the credential is left out; the notice says what was left out. reqlyn snippet <request> --language python prints the same for a saved request.

Importing curl

A curl command typed or pasted in the address is read into the request when you press Send: its method, address, headers and body. It is not sent yet, and nothing in it is run; check it, then Send. "Import a curl command" takes a pasted curl command line and shows what it would make before anything is created. The text is read, never run as a shell command, and likely secrets are masked. Files (HAR, Postman, OpenAPI) are imported from Discovery.

Help for Reqlyn 0.5.1. All help topics