Documentation sections

Provenance

Every result says how it was computed: each calculator result, each batch item and each job result carries one provenance object with the same nine members. The values beside it are unchanged by it.

The nine members

Provenance members
Member	Type	Description
`method`	string	What computed the values: calculator:<slug>, or a job handler's method.
`version`	string	The engine that computed them, <component>@<revision>: api@…, worker@…, mcp@…, web@…. A build that cannot tell its revision says so (api@dev).
`formulaRef`	string \| null	The published source of the formula, or null where none is named.
`assumptions`	{code, text}[]	What the method assumes. Empty means none is stated, not that there are none.
`validRange`	object	status (inside, outside or unknown), the bounds of every input with its unit, the inputs outside them, and a fitted model's validated range and worst-case error where there is one.
`computedAt`	string	When, ISO-8601 in UTC with milliseconds.
`inputs`	object	The inputs the values were computed from, after defaults were applied.
`seed`	integer \| null	The seed of a randomised computation; null for every calculator.
`elapsedSeconds`	number	How long the computation took.

Inputs outside the stated range

An input outside the range a calculator is stated for is still computed. validRange.status reads outside, validRange.outside names the input, and a warning naming the input and the bound is added to warnings. Where a calculator uses a fitted model, validRange.model gives the model's validated range and its worst-case error, and whether the inputs were inside it.

Older results

A result stored before September 2026 carries only method, version, seed, inputs and elapsedSeconds: read an absent member as unknown, not as empty. New members may be added; none is renamed or removed.

curl -X POST https://rftools.io/api/py/v1/calculate \
  -H "X-API-Key: $RFTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "vswr-return-loss",
    "inputs": {
      "vswr": 150
    }
  }'

import rftools

client = rftools.Client()  # reads RFTOOLS_API_KEY, or the key `rftools login` saved

result = client.calculate("vswr-return-loss", {"vswr": 150})
print(result.values)
print(result.warnings, result.provenance.formula_ref)

const response = await fetch("https://rftools.io/api/py/v1/calculate", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.RFTOOLS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "slug": "vswr-return-loss",
    "inputs": {
      "vswr": 150
    }
  }),
});
console.log(response.status, await response.json());

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "slug": "vswr-return-loss",
	  "inputs": {
	    "vswr": 150
	  }
	}`)
	req, err := http.NewRequest("POST", "https://rftools.io/api/py/v1/calculate", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("RFTOOLS_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

application/json

{
  "slug": "vswr-return-loss",
  "values": {
    "gamma": 0.9867549668874173,
    "returnLoss": 0.11581357761790759,
    "mismatchLoss": 15.798026442026972,
    "reflectedPct": 97.3685364676988,
    "transmittedPct": 2.6314635323012037
  },
  "warnings": [
    "Input 'vswr' = 150 is outside the range this calculator is stated for (1 to 100 :1); the result is extrapolated."
  ],
  "errors": [],
  "provenance": {
    "method": "calculator:vswr-return-loss",
    "version": "api@3f2c1a9b04de",
    "formulaRef": "Pozar, \"Microwave Engineering\" 4th ed., Chapter 2",
    "assumptions": [],
    "validRange": {
      "status": "outside",
      "bounds": {
        "vswr": {
          "min": 1,
          "max": 100,
          "unit": ":1"
        }
      },
      "outside": [
        "vswr"
      ],
      "model": null
    },
    "computedAt": "2026-09-24T14:05:11.003Z",
    "inputs": {
      "vswr": 150
    },
    "seed": null,
    "elapsedSeconds": 0.003
  }
}

Computed, flagged in validRange.outside, with a warning.

{
  "slug": "vswr-return-loss",
  "values": {
    "gamma": 0.3333333333333333,
    "returnLoss": 9.54242509439325,
    "mismatchLoss": 0.5115252244738131,
    "reflectedPct": 11.11111111111111,
    "transmittedPct": 88.88888888888889
  },
  "warnings": [],
  "errors": [],
  "provenance": {
    "method": "calculator:vswr-return-loss",
    "version": "api@3f2c1a9b04de",
    "formulaRef": "Pozar, \"Microwave Engineering\" 4th ed., Chapter 2",
    "assumptions": [],
    "validRange": {
      "status": "inside",
      "bounds": {
        "vswr": {
          "min": 1,
          "max": 100,
          "unit": ":1"
        }
      },
      "outside": [],
      "model": null
    },
    "computedAt": "2026-09-24T14:05:11.003Z",
    "inputs": {
      "vswr": 2
    },
    "seed": null,
    "elapsedSeconds": 0.003
  }
}