Documentation

Getting started

1. Create a project (a folder that holds your collections).
2. Add a collection, then a request — set the method and URL.
3. Hit Send. The response (status, time, headers, body) appears alongside.

Prefer to start from something you have? Jump to Importing to bring in cURL, Postman, OpenAPI, or HAR.

Projects & collections

Collections are stored as plain YAML files inside your project folder, so they can live in Git next to your code. Organize requests into folders; drag order defines run order.

Use the sidebar search to filter by request name, URL, or folder, and the expand/collapse controls (global, or per-folder from a folder's menu) to manage large trees.

Environments & variables

Reference a variable anywhere (URL, headers, body, auth) with {{name}}. Define the variable with the bare name (no braces).

Key:   baseUrl
Value: https://api.example.com

Request URL: {{baseUrl}}/users

Variables resolve by scope, highest wins: request → environment → collection → project → global. Pick the active environment in the status bar. Global environments persist across restarts.

Sending requests

Requests are sent from the desktop app's native process, so they are not subject to browser CORS — you get the real response and real error codes, like Postman or Insomnia. Response cookies are captured, and history persists across restarts.

Authentication

The Auth tab supports Bearer, Basic, and API Key. Credentials can use variables:

Auth type: Bearer Token
Token:     {{token}}    →  sends  Authorization: Bearer <token>

API Key can be added as a header or a query parameter.

Chaining requests (extractors)

Capture a value from one response and reuse it in the next. On the login request, add an Extractor:

Variable name: token
Source:        Response Body
Expression:    token        (dot path, e.g. data.token, items[0].id)

Send it — you'll see “Captured {{token}}” — then reference {{token}} in later requests. Extractors also feed the collection runner during a full run.

Pre-request scripts

Run JavaScript before a request to compute values (timestamps, signatures, nonces) via a pm-style API:

const ts = Date.now();
pm.variables.set("timestamp", ts);
pm.variables.set("nonce", Math.random().toString(36).slice(2));

Anything you set applies to that request (highest precedence). Reference it as {{timestamp}}.

Tests & the collection runner

Add assertions (status, header, body, time) on a request's Tests tab. Then run a whole collection from its menu → Run collection: it executes every request in order, chains extracted variables, runs tests, and shows a pass/fail report.

Importing & export

Import from the sidebar (auto-detects the format):

• cURL — paste a command.
• OpenAPI/Swagger — from a file, or fetched live from a running server.
• Postman — v2.x collections.
• HAR — browser DevTools captures (XHR/fetch by default).

Export any collection to Postman or OpenAPI (copy or download) — no lock-in.

Drift detection & re-sync

Collections imported from an OpenAPI spec remember their source. From the collection menu → Check for API changes, FetchMate re-reads the live spec and shows what changed — added, removed, or changed payload fields. Applying re-syncs the collection while keeping the values you already typed.

Git & GitHub

Because collections are plain files, they version like code. Initialize Git on a project from the status bar, then use the changes dialog to view diffs, discard, commit, and push/pull. If you're connected to GitHub, one click can create a repo and wire up the remote.

AI request builder

Click AI in the request header and describe the call in plain English — FetchMate generates the request for you to review.

By default it uses your locally-authenticated claude CLI (no API key stored). You can also use an Anthropic or OpenAI key. Secrets are protected: only variable names are shared with the model, and any secret value you paste is replaced with a {{placeholder}} before the prompt is sent.

MCP server & CLI

Your collections aren't trapped in the app. The MCP server lets agents (Claude, Cursor) list and run your requests as tools; the CLI runs a collection headlessly for CI.

# CLI (exits non-zero on failure)
FETCHMATE_DIR=./ fetchmate run "Users API" --env staging

# Register with Claude Code
claude mcp add fetchmate -e FETCHMATE_DIR=./ -- npx tsx packages/mcp/src/server.ts

Tools: list_collections, list_requests, run_request, run_collection.

Privacy & security

No cloud, no account, no telemetry — everything stays on your machine. Collections are plain text, so treat them like code: avoid committing real secrets into collection/environment variables. Prefer variables filled at run time, or your CLI-based AI auth (which stores no key).

Troubleshooting

“Unresolved variable” when sending

The URL still has a {{placeholder}} that isn't defined. Add the variable (exact name, no braces) to an environment and select it. The error lists which variables are available.

“Could not reach…” on the desktop app

The host is unreachable, DNS failed, or the server isn't running — a real network error (not CORS, since the app sends natively).

CLI says “No collections found”

Point FETCHMATE_DIR at a folder that contains your collection .yaml files (it scans recursively).

AI: “claude CLI not found”

Install Claude Code and ensure it's on your PATH, or switch the AI provider to an Anthropic/OpenAI API key.