# URL query build

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

Build a query string or replace an absolute URL query from ordered pairs. No fetching.

**Use when you need to: url query build · build query string · encode search params.**

## Supported

- url query build
- build query string
- encode search params

## Not supported

- fetch
- form multipart

## Behavior

- pairs is an ordered list of {name,value} strings, max 512. Names and values are strings; encode via WHATWG URLSearchParams.
- If url is omitted, return { query } without a leading ? (empty pairs -> empty string).
- If url is present, it must be an absolute URL; replace its search with the pairs and optionally set fragment (without #). Return { url: href }.
- fragment optional string without #. If omitted and url present, keep existing fragment unless fragment is provided as empty string (strip).

## Input

- `pairs` (array of object, required): max items 512
- `url` (string, optional): max length 8192
- `fragment` (string, optional): max length 8192

## Output

- `query` (string, optional)
- `url` (string, optional)

## Limits

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

## Example

Request input:

```json
{
  "pairs": [
    {
      "name": "a",
      "value": "1"
    },
    {
      "name": "b",
      "value": "x y"
    }
  ]
}
```

Response:

```json
{
  "result": {
    "query": "a=1&b=x+y"
  }
}
```

## How to call it

### MCP

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

```json
{
  "id": "url-query-build",
  "version": "1.0.0",
  "input": {
    "pairs": [
      {
        "name": "a",
        "value": "1"
      },
      {
        "name": "b",
        "value": "x y"
      }
    ]
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/url-query-build/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"pairs":[{"name":"a","value":"1"},{"name":"b","value":"x y"}]}'
```

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

### CLI

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

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

## Related tools

- [URL query parse](/tools/url-query-parse): Parse query pairs and fragment from an absolute URL. Parse only; no fetching.
- [URL query merge](/tools/url-query-merge): Merge query pairs into an absolute URL. No fetching.
- [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).
- [IPv4 address classify](/tools/ipv4-address-classify): Classify an IPv4 address against the static IANA IPv4 special-purpose address registry.
- [IPv4 address compare](/tools/ipv4-address-compare): Compare two canonical IPv4 addresses by their numeric uint32 value.