# URL query merge

`url-query-merge` · version 1.0.0 · URLs & IP addresses · free, no key needed

Merge query pairs into an absolute URL. No fetching.

**Use when you need to: url query merge · merge search params · update url query.**

## Supported

- url query merge
- merge search params
- update url query

## Not supported

- fetch
- sort params as security

## Behavior

- url is an absolute URL. pairs is a non-empty ordered list of {name,value}.
- mode is append (default), replace_names, or replace_all.
- append: keep existing pairs then add pairs.
- replace_names: for each distinct name in pairs, drop existing params of that name, then append the supplied pairs in given order (other existing names kept in original order).
- replace_all: drop existing query, use pairs only.
- Fragment is preserved. Return { url }. Max 512 pairs after merge.

## Input

- `url` (string, required): min length 1; max length 8192
- `pairs` (array of object, required): min items 1; max items 512
- `mode` (one of "append", "replace_names", "replace_all", optional)

## Output

- `url` (string, required)

## Limits

- max url bytes: 8192
- max query pairs: 512

## Example

Request input:

```json
{
  "url": "https://example.com/p?a=1&b=2",
  "pairs": [
    {
      "name": "a",
      "value": "9"
    }
  ],
  "mode": "replace_names"
}
```

Response:

```json
{
  "result": {
    "url": "https://example.com/p?b=2&a=9"
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "url-query-merge",
  "version": "1.0.0",
  "input": {
    "url": "https://example.com/p?a=1&b=2",
    "pairs": [
      {
        "name": "a",
        "value": "9"
      }
    ],
    "mode": "replace_names"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/url-query-merge/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/p?a=1&b=2","pairs":[{"name":"a","value":"9"}],"mode":"replace_names"}'
```

The machine-readable contract is at [/v1/tools/url-query-merge/versions/1.0.0](/v1/tools/url-query-merge/versions/1.0.0).

### CLI

```sh
node cli.mjs run url-query-merge 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [URL query build](/tools/url-query-build): Build a query string or replace an absolute URL query from ordered pairs. No fetching.
- [URL query parse](/tools/url-query-parse): Parse query pairs and fragment from an absolute URL. Parse only; no fetching.
- [IPv4 CIDR aggregate](/tools/ipv4-cidr-aggregate): Merge a list of IPv4 CIDR blocks into the minimal equivalent list of non-overlapping CIDR blocks.
- [IPv6 CIDR aggregate](/tools/ipv6-cidr-aggregate): Merge a list of IPv6 CIDR blocks into the minimal equivalent list of non-overlapping CIDR blocks.
- [URL normalize](/tools/url-normalize): Normalize an absolute http or https URL via WHATWG parse. No DNS, fetch, or security-equivalence claim.
- [URL resolve](/tools/url-resolve): Resolve a URL against an absolute http(s) base using WHATWG. No fetching. Result must be http(s).