SumWise Compute private alpha

REST developer documentation

Integrate with SumWise-hosted deterministic computation through one documented HTTPS operation. Send one mathematical expression and receive a closed integer, rational, or finite approximate-real result.

Check the current API access terms and confirm that your calculation is supported before payment. Compute exposes Evaluate only; there is no public Convert endpoint.

HTTPS endpoint and authentication

POST https://api.sumwisecalc.com/v1/evaluate

• HTTPS is required. No HTTP endpoint or HTTP-to-HTTPS redirect is promised.
• The path and method are case-sensitive, and the query string must be empty.
• Send Content-Type: application/json, optionally with the sole unquoted parameter charset=utf-8.
• Send one complete UTF-8 body with one valid Content-Length. Transfer-encoded requests are not accepted.
• Success uses application/json; deliverable errors use application/problem+json.

Put the issued opaque key in exactly one header:

Authorization: Bearer <api-key>

Treat the key as a secret. Keep it in a server-side secret store or environment variable, never in a URL, request body, browser application, log, or source file. Missing, malformed, unknown, disabled, revoked, and expired keys all produce HTTP 401 with authentication_required.

Request schema

{"expression":"mean(10,20,30)"}

The body is a closed JSON object with exactly one case-sensitive member. expression is required and must be a string. Duplicate, additional, misspelled, escaped-name, and wrong-case members are rejected. After JSON escape decoding, the expression must remain ASCII and must satisfy the grammar below.

Expression grammar

expression     := additive
additive       := multiplicative ( ("+" | "-") multiplicative )*
multiplicative := unary ( ("*" | "/") unary )*
unary          := ("+" | "-") unary | primary
primary        := number | constant | function-call | "(" expression ")"
function-call  := function-name "(" expression ("," expression)* ")"

Addition/subtraction and multiplication/division evaluate left to right; parentheses override precedence. Function arguments are comma-separated expressions and may nest admitted calls.

(digits ["." [digits]] | "." digits) ["e" ["+" | "-"] digits]

Examples are 12, 12.34, .5, 1., 1e6, and 3.2e-5. A leading sign is a unary operator. Lowercase e is the supported exponent marker. Integer tokens are exact; decimal-point and scientific tokens are approximate binary64 inputs.

The case-sensitive constants pi, e, tau, and phi produce approximate reals. Space, tab, carriage return, and line feed may separate tokens. Explicit * is required; exact rationals use expressions such as 7/6. Variables, assignments, implicit multiplication, user functions, data containers, complex results, and symbolic results are unavailable.

Current supported functions

Names are case-sensitive and have no aliases. Only the following eleven functions are admitted.

Each argument must evaluate to an admitted scalar integer, rational, or finite approximate real. For example, median(3,1,2) returns exact integer 2, median(1,2) returns exact rational 3/2, and range(1/3,5/6) returns exact rational 1/2. Function names not listed above are not part of this profile.

Exactness, precision, and rendering

• Arithmetic over exact integers and rationals stays exact. Results are canonical integers or reduced rationals with a positive denominator.
• mean(1,2) returns exact rational 3/2, not a floating approximation.
• Decimal/scientific literals and approximate constants introduce IEEE-754 binary64 provenance. Approximate results remain approximate even when they look integral.
• min and max compare exact values exactly; approximate participation uses the finite-real comparison path while preserving the selected argument's family.
• With all-exact inputs, median remains exact: an odd count returns the middle value, and an even count returns the exact arithmetic mean of the two middle values. Any approximate argument makes the result approximate; exactness is not recovered.
• range returns maximum minus minimum. All-exact inputs produce an exact nonnegative result, including exact zero for one argument. Any approximate argument makes the result approximate; exactness is not recovered.
• The five scalar utilities preserve exact input and approximate provenance. They normalize an approximate zero result to positive zero.
• Successful approximate results are finite; NaN and infinity are not successful result values.

The API does not provide selectable decimal precision, currency rounding, or a configurable rounding mode. Approximate text is locale-independent, uses a dot decimal separator and lowercase e, and round-trips to the same binary64 value in the qualified build. Positive zero is "0" and negative zero is ordinarily "-0". Cross-toolchain byte-for-byte equality of approximate text is not frozen.

Result schemas

Every success body is closed to ok, api_version, operation, engine_version, and result. Numeric values are strings, not JSON number tokens.

Integer

{"type":"integer","text":"55","exactness":"exact","value":"55"}

Rational

{"type":"rational","text":"3/2","exactness":"exact","value":{"numerator":"3","denominator":"2"}}

Approximate real

{"type":"real","text":"3.141592653589793","exactness":"approximate","value":"3.141592653589793"}

Public limits

A durably accepted request consumes one rate attempt and is not later refunded. Additional expression, token, node, nesting, work, time, and result limits fail closed; their numeric values are not external contract values. Limit exhaustion never returns a truncated success.

Errors and retries

Deliverable service problems are closed to type, title, status, detail, and code. Compute evaluation problems additionally include "api_version":"v1" and "operation":"evaluate". Branch on stable status/code pairs rather than message text.

Complete responses carry Cache-Control: no-store, X-Content-Type-Options: nosniff, and an opaque X-Request-Id. HTTP 405 includes Allow: POST; HTTP 401 includes WWW-Authenticate: Bearer realm="SumWise Compute". A transport failure is not necessarily a serialized service problem.

• Correct request, authentication, expression, domain, or limit errors before retrying.
• For rate_limit_exceeded and quota_exhausted, wait at least the returned positive Retry-After delta-seconds.
• Serialize work for a key instead of retrying concurrent_request_limit_exceeded while another request remains active.
• Bounded backoff may be used for service-busy/unavailable or transient transport failure, but no retry schedule or availability guarantee exists.
• Every explicit retry is a new attempt; there is no idempotency-key contract.

Use a bounded client timeout. The service's exact processing-time limit is not a public numeric contract. Preserve X-Request-Id for support and reconciliation, but treat it as opaque.

Key revocation and evaluation expiration

Private-alpha credentials may be non-expiring or provisioned with a native UTC expiration time. A time-limited credential can authenticate only before its provisioned expiration time; at that time or later, new requests fail authentication. A request authenticated immediately before expiration may complete normally. Exact lifetimes and evaluation terms are communicated separately during provisioning.

Dedicated keys may also be revoked or disabled earlier, including at evaluator request. Missing, malformed, unknown, disabled, revoked, and expired credentials remain externally indistinguishable: authentication fails with HTTP 401 and authentication_required, without a lifecycle reason. Rejection of an expired credential does not consume accepted-request quota or a billable unit. An expired credential is not reactivated; a new credential is issued instead.

Privacy and proprietary implementation

Expressions and results necessarily reach the hosted service and exist transiently while a request is processed. The durable application/accounting contract does not persist the expression, raw request body, result body, Authorization header, or plaintext API key.

Durable operational/accounting records may retain opaque request, customer, key, and usage identifiers; timestamps; outcome/status; byte counts; quota/billable units; delivery disposition; and service/profile metadata. This is not a promise of anonymity, zero transient memory, zero operating-system or network-provider logging, or a particular retention duration.

All SumWise implementation remains private and proprietary. This page and the linked machine-readable files disclose the interoperable REST contract only. Integration requires no access to SumWise implementation source.

Engine-version labeling

engine_version is an immutable process-level strict-SemVer behavior identity. Record it for reconciliation, but do not hard-code one observed value unless SumWise explicitly qualifies that dependency.

A label such as 0.1.0-dev.1+untrusted.local is a development/pre-release identity. Its build-metadata suffix describes local build provenance; it does not characterize a customer's expression or result.

Language-neutral examples

These examples make one request, use normal TLS verification, and add no automatic retry. The 30-second client timeout is an example client choice, not a service-level promise.

One request, an exact rational result

For an authorized private-alpha client, send POST /v1/evaluate with the Bearer authentication and JSON headers described above. This is the same published rational example, not an additional endpoint.

{"expression":"1/3 + 5/6"}

Representative success body; the engine identity is illustrative and build-specific:

{
  "ok": true,
  "api_version": "v1",
  "operation": "evaluate",
  "engine_version": "0.1.0-dev.1+git.0123456789abcdef0123456789abcdef01234567.eval1",
  "result": {
    "type": "rational", "text": "7/6", "exactness": "exact",
    "value": {"numerator": "7", "denominator": "6"}
  }
}

Use the numerator and denominator strings when a workflow must retain the exact fraction rather than round it to a decimal. This example does not establish public API availability or a service-level guarantee.

cURL

curl --request POST \
  --max-time 30 \
  --header "Authorization: Bearer ${SUMWISE_API_KEY}" \
  --header "Content-Type: application/json" \
  --data-binary '{"expression":"sum(12,18,25)"}' \
  https://api.sumwisecalc.com/v1/evaluate

Generic Python REST call

import http.client
import json
import os
import ssl

api_key = os.environ["SUMWISE_API_KEY"]
body = json.dumps({"expression": "abs(-7/3)"}, separators=(",", ":"))
connection = http.client.HTTPSConnection(
    "api.sumwisecalc.com", 443, timeout=30, context=ssl.create_default_context()
)
try:
    connection.request(
        "POST", "/v1/evaluate", body=body.encode("utf-8"),
        headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
    )
    response = connection.getresponse()
    response_body = response.read()
    print(response.status, response.getheader("X-Request-Id"))
    print(json.loads(response_body))
finally:
    connection.close()

Server-side JavaScript

Never put an API key in browser-delivered JavaScript.

const response = await fetch("https://api.sumwisecalc.com/v1/evaluate", {
  method: "POST",
  redirect: "error",
  signal: AbortSignal.timeout(30_000),
  headers: {
    Authorization: `Bearer ${process.env.SUMWISE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ expression: "ceil(7/3)" }),
});

const requestId = response.headers.get("x-request-id");
const payload = await response.json();
console.log(response.status, requestId, payload);

C# HttpClient

using System;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("SUMWISE_API_KEY")
    ?? throw new InvalidOperationException("SUMWISE_API_KEY is required.");
using var handler = new HttpClientHandler { AllowAutoRedirect = false };
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
using var request = new HttpRequestMessage(
    HttpMethod.Post, "https://api.sumwisecalc.com/v1/evaluate");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent(
    "{\"expression\":\"mean(10,20,30)\"}", Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
var requestId = response.Headers.TryGetValues("X-Request-Id", out var values)
    ? values.SingleOrDefault() : null;
var payload = await response.Content.ReadAsStringAsync();
Console.WriteLine($"{(int)response.StatusCode} {requestId} {payload}");

n8n HTTP Request node

• Method: POST
• URL: https://api.sumwisecalc.com/v1/evaluate
• Authentication: stored Header Auth, header Authorization, value Bearer <api-key>
• Body: {"expression":"max(4,9/2,8)"}
• Response format: JSON
• Retry on fail: disabled
• Timeout: a bounded workflow value, for example 30,000 ms

Store the key in n8n's credential store; do not hard-code it in workflow or expression data.

Machine-readable contract

The OpenAPI document covers the HTTPS operation, opaque Bearer authentication, statuses, media types, response headers, examples, and body-schema references. The JSON Schema covers the closed request, three-way success union, and deliverable problem bodies.