Documentation

1. First launch

On first launch, Synapse asks for a workspaces directory: the folder where every workspace (one per API project) is saved. The choice is remembered.

2. Workspace structure

The workspaces directory holds one folder per workspace. Workspaces are completely independent: each has its own requests, selectors and scripts, and nothing is shared between them. Each workspace has the same layout:

synapse-workspaces/           ← Synapse home directory (workspaces directory)
├── workspace-one/            ← independent workspace
│   ├── workspace.json        ← workspace name (required)
│   ├── collections/          ← HTTP requests (required)
│   ├── selectors/            ← dropdown definitions (optional)
│   └── scripts/              ← .kts automation scripts (optional)
├── workspace-two/            ← independent workspace
│   ├── workspace.json
│   └── collections/
└── workspace-three/          ← independent workspace
    ├── workspace.json
    ├── collections/
    └── selectors/

Secrets are not stored in the workspace. They are encrypted and saved in Synapse's local config folder, outside any repository. See Secrets.

workspace.json

The only file required at the root. It holds the display name.

{
  "name": "DummyJSON API"
}

Live file watching

Synapse watches the workspace folder. A JSON file saved from any editor is reloaded immediately, without a restart.

3. Collections — request files

Each .json file in collections/ defines one HTTP request. Sub-folders become groups. Filenames prefixed with 01-, 02-, … sort by prefix; the rest sort alphabetically.

Requests and folders can also be created, duplicated, moved, and deleted inside Synapse, so the files never have to be written by hand.

Responses

Status, headers, and body are shown for every response. Binary payloads (PDF, ZIP, images) are not rendered and can be saved to a file. Response bodies can be searched with plain text or a regular expression, case-insensitive by default.

Field reference

Templates

Templates work in every string field: url, headers, queryParams, body, graphql, and all auth fields. They resolve at send time.

Templates can be combined in one string and nested: an inner {{…}} resolves first and becomes part of the outer expression.

Resolution rules:

Path params

A URL can contain {{var.KEY}} placeholders, e.g. https://api.example.com/users/{{var.userId}}. Their values are saved with the request under pathParams.

Auth

Per-request authentication is stored in the request file as an auth block. All values support templates. An auth-generated header overrides a manual header of the same name.

"auth": { "type": "bearer", "token": "{{script.TOKEN}}" }

Keep real credentials out of the file and reference them as {{secrets.KEY}}. The Showcases workspace contains a working example of each type.

OAuth 1.0 (oauth1)

The request is signed locally at send time per RFC 5849: the signature base string covers the method, the normalized URL, and all query and form parameters, with a fresh oauth_nonce and oauth_timestamp on every send. The result always goes in the Authorization header.

"auth": {
  "type": "oauth1",
  "oauth1": {
    "consumerKey": "{{secrets.CONSUMER_KEY}}",
    "consumerSecret": "{{secrets.CONSUMER_SECRET}}",
    "token": "{{secrets.OAUTH_TOKEN}}",
    "tokenSecret": "{{secrets.OAUTH_TOKEN_SECRET}}",
    "signatureMethod": "HMAC-SHA1"
  }
}

OAuth 2.0 (oauth2)

Fetched tokens are held in memory only, never written to the request file, and cleared on workspace switch. Only a manually set accessToken is saved to disk.

"auth": {
  "type": "oauth2",
  "oauth2": {
    "grantType": "client_credentials",
    "tokenUrl": "https://auth.example.com/oauth/token",
    "clientId": "{{secrets.CLIENT_ID}}",
    "clientSecret": "{{secrets.CLIENT_SECRET}}",
    "scope": "read write",
    "clientAuth": "basic"
  }
}

Settings

Per-request transport behavior is stored in the request file as a settings block.

The cookie jar is one in-memory store shared by every request with cookiesEnabled: true. It is not isolated per request and resets on every app restart.

"settings": { "httpVersion": "http/1.1", "followRedirects": true, "cookiesEnabled": true, "timeoutMs": 5000 }

How the body is encoded

bodyType selects the editor, not the encoding. raw and table both produce a JSON object; the Content-Type header decides what goes on the wire.

Table body field types

With bodyType: table, the JSON body is built from key/value pairs. Each value is sent as a string (default) or as raw JSON. A raw-JSON value that is not valid JSON falls back to a string.

Binary body (file upload)

A file's raw bytes are sent as the body. The file's absolute path is saved with the request as bodyFilePath. Without a Content-Type header the body goes out as application/octet-stream; a manual header (e.g. image/png) overrides it. The path is machine-specific and does not resolve on another computer.

Multipart form-data body

Text fields and file uploads are combined in one multipart/form-data request. The parts are saved with the request as bodyParts.

Synapse writes Content-Type: multipart/form-data; boundary=... itself, with a fresh random boundary on every send, and ignores a manual one. Parts are never sent on GET or HEAD.

GraphQL body

With bodyType: graphql, the query and its variables are stored separately and unescaped in a graphql block, and sent as the standard JSON envelope {"query", "variables", "operationName"}.

The GraphQL-over-HTTP specification recommends Accept: application/graphql-response+json, application/json. GraphQL is sent as a POST; a GET is not encoded into query parameters.

{
  "id": "graphql-character",
  "name": "Get Character",
  "method": "POST",
  "url": "https://rickandmortyapi.com/graphql",
  "bodyType": "graphql",
  "graphql": {
    "query": "query Character($id: ID!) {\n  character(id: $id) { name status }\n}",
    "variables": { "id": "{{var.characterId}}" }
  }
}

The encoded body is what request.body and response.body script paths see, e.g. request.body.variables.id or response.body.data.character.name.

Example — login with token extraction

{
  "id": "login",
  "name": "Login",
  "method": "POST",
  "url": "{{selector.environment.BASE_URL}}/auth/login",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "User-Agent": "{{selector.device.USER_AGENT}}",
    "X-APP-OS-SYSTEM-VERSION": "{{selector.device.OS_VERSION}}"
  },
  "bodyType": "raw",
  "body": "{\"username\":\"emilys\",\"password\":\"emilyspass\"}",
  "postScriptLines": [
    "saveVariable(\"TOKEN\", response.body.accessToken)",
    "saveVariable(\"REFRESH\", response.body.refreshToken)",
    "saveVariable(\"USER_ID\", response.body.id)",
    "runScript(\"parse-token.kts\")"
  ]
}

4. Selectors — dynamic dropdowns

Each .json file in selectors/ defines one dropdown. Switching a selector retargets every request that references it. Selectors are independent, so each testing axis (environment, profile, device, API version, region, locale) is one selector rather than one copy of the whole environment per combination.

The DummyJSON sample ships three:

Selectors, options, and variables can also be managed inside Synapse.

Field reference

Each option has:

Three patterns

With variables: several values per option.

{
  "id": "device",
  "name": "Device",
  "defaultValue": "android",
  "options": [
    {
      "value": "android",
      "label": "🤖 Android",
      "variables": { "USER_AGENT": "DummyJSON-App/3.2.0 (Android 14; Pixel 8)", "OS_VERSION": "14" }
    },
    {
      "value": "ios",
      "label": "🍎 iOS",
      "variables": { "USER_AGENT": "DummyJSON-App/3.2.0 (iPhone; iOS 17.5)", "OS_VERSION": "17.5" }
    },
    {
      "value": "desktop",
      "label": "🖥️ Desktop",
      "variables": { "USER_AGENT": "DummyJSON-App/3.2.0 (Windows NT 10.0; Win64; x64)", "OS_VERSION": "10" }
    }
  ]
}

Without variables: the option's value is used directly.

{
  "id": "version",
  "name": "API version",
  "defaultValue": "v1",
  "options": [
    { "value": "v1", "label": "v1 (stable)" },
    { "value": "v2", "label": "v2 (beta)" }
  ]
}

Composed from another selector: a variable may itself contain templates.

{
  "id": "environment",
  "name": "Environment",
  "defaultValue": "live",
  "options": [
    { "value": "live",    "label": "🌍 Live",    "variables": { "BASE_URL": "https://api.example.com/{{selector.version}}" } },
    { "value": "staging", "label": "🧪 Staging", "variables": { "BASE_URL": "https://staging.example.com/{{selector.version}}" } }
  ]
}

A variable can reference anything a request can: another selector, {{secrets.<KEY>}}, {{script.<function>()}}. Chains of any length are followed. A reference that leads back to itself is left unresolved.

5. Scripts — dynamic values & automation

Built-in functions

Always available, no setup. Usable in any template field.

Arguments are literal text separated by commas; a value containing a comma is split into two arguments. To pass a resolved value as an argument, nest the template: {{script.sign({{var.payload}},{{secrets.SIGNING_KEY}})}}.

Script lines (pre-request and post-response extraction)

A request holds two script-line lists with the same syntax: preScriptLines runs before the send, postScriptLines after the response arrives.

Every line is a function call:

Lines starting with // or # are comments.

Breaking change: older versions used NAME = source.path and run:name. These lines no longer run. Each one fails with an error that shows the line in the current form, e.g. saveVariable("NAME", source.path) or runScript("name.kts").

The body path is a plain dot-separated key walk, not JSONPath. Wildcards, $, and filters are not supported.

Pre-request (preScriptLines)

A variable set here is substituted into the same request's {{script.VAR}} templates (URL, headers, query and path params, body, auth fields) before it is sent.

Post-response (postScriptLines)

Values captured here become session variables for later requests.

Failure behavior

Example abort message:

Pre-request script cannot read "response.body.token": there is no response yet —
move "saveVariable("TOKEN", response.body.token)" to the post-request script.

Session variables and clearScriptVariables()

Captured variables are kept in memory for the session and discarded when Synapse closes. They can also be reviewed and cleared inside Synapse.

A line clearScriptVariables() discards all variables at that point: variables captured above it are dropped, lines below it are kept. It is valid in both lists and runs before that phase's runScript(...) scripts.

Custom Kotlin scripts (.kts)

Script lines only read what the request and response already contain. A .kts script in scripts/ can run any code: call another API, run a command-line tool, read a file, query a database, sign or decode a token. Trigger it with runScript("<name>.kts") from either script-line list. Every entry the script writes into result becomes a {{script.KEY}} value.

Scripts are not sandboxed. They run with the same permissions as Synapse itself. Only run scripts you trust.

A script used in both phases should branch on context.phase.

Example: decode a JWT and extract the user ID.

scripts/parse-token.kts

import java.util.Base64

val token = context.variables["TOKEN"] ?: error("TOKEN not set — send Login first")
val payloadJson = String(Base64.getUrlDecoder().decode(token.split(".")[1]))

val idMatch = """"id"\s*:\s*(\d+)""".toRegex().find(payloadJson)
result["JWT_USER_ID"] = idMatch?.groupValues?.get(1) ?: ""

Trigger in a request's postScriptLines:

saveVariable("TOKEN", response.body.accessToken)
runScript("parse-token.kts")

After Login, {{script.JWT_USER_ID}} is available in every request.

6. Secrets — encrypted local credentials

API keys, tokens, and passwords are kept in an encrypted, device-local vault saved outside the workspace and outside any repository. They never appear in collection files.

Import from a .env file

API_KEY=sk-live-abc123
DB_PASSWORD=hunter2
WEBHOOK_SECRET=whsec_xyz

Synapse reads the file, encrypts each value, and saves the result in its local config folder. The .env file itself is not copied into the workspace. Keep it outside the repository.

Manage secrets

Secrets can be added, edited, and removed one at a time. Export writes all current secrets to a plain <workspace>_secrets.env file for backup or another machine. Store it outside the repository.

Use them in any request

Reference a secret with {{secrets.KEY}} wherever templates work. The value is decrypted at send time.

{
  "headers": {
    "Authorization": "Bearer {{secrets.API_KEY}}"
  }
}

7. Tips & recipes

8. Importing and creating workspaces with AI

Let an AI write your collections

Every file is structured JSON in a predictable path. Any LLM can generate collections/ and selectors/ files from a description of the API. Secrets stay encrypted and out of the files.

Import an existing collection

Three skills, built on the agent-skill standard, work with any compatible AI coding assistant.

All three are one download in the download section. Unpack it into your assistant's skills folder and keep the three skills side by side.