The interface that exists today.

import json
import os
from urllib.error import HTTPError, URLError
from urllib.request import Request, urlopen

# Use only an authorised private API and a scoped credential.
base = os.environ["SOVREG_API_BASE"].rstrip("/")
token = os.environ["SOVREG_API_TOKEN"]

def request(path, payload=None):
    data = None if payload is None else json.dumps(payload).encode("utf-8")
    req = Request(
        base + path,
        data=data,
        headers={
            "Authorization": "Bearer " + token,
            "Content-Type": "application/json",
        },
    )
    try:
        with urlopen(req, timeout=10) as response:
            return json.load(response)
    except HTTPError as error:
        raise RuntimeError(f"API returned HTTP {error.code}") from None
    except (URLError, TimeoutError):
        raise RuntimeError("Private API is unavailable") from None

catalogue = request("/api/v1/models")
print([item["model_id"] for item in catalogue["items"]])

estimate = request(
    "/api/v1/models/mock-extractive-v1/estimate",
    {"text": "First second third", "max_output_tokens": 2},
)
assert estimate["financial_quote"] is False
assert estimate["estimate"]["simulated"] is True
print(estimate["estimate"])

{
  "text": "First second third",
  "max_output_tokens": 2
}

{
  "model_id": "mock-extractive-v1",
  "estimate": {
    "input_tokens_upper_bound": 3,
    "output_tokens_cap": 2,
    "additional_cost_cap": "0",
    "estimation_method": "mock_whitespace_words",
    "simulated": true
  },
  "financial_quote": false
}

// Trusted Node.js code in a private application, never a browser component.
import {
  createPrivateGatewayClient,
  GatewayClientError,
} from "@/lib/private-gateway/client";

const baseUrl = process.env.SOVREG_API_BASE;
if (!baseUrl) throw new Error("Private API origin is not configured");

const client = createPrivateGatewayClient({
  baseUrl,
  timeoutMs: 5000,
  getCredential: () => {
    const value = process.env.SOVREG_API_TOKEN;
    if (!value) throw new Error("Scoped credential is unavailable");
    return value;
  },
});

try {
  const catalogue = await client.listModels();
  const model = await client.getModel("mock-extractive-v1");
  const result = await client.estimateUsage(model.model_id, {
    text: "First second third",
    max_output_tokens: 2,
  });
  // result.financial_quote is false; result.estimate.simulated is true.
  console.log(catalogue.items.length, result.estimate.input_tokens_upper_bound);
} catch (error) {
  if (error instanceof GatewayClientError) {
    // Only normalised fields, never credentials, prompt or raw response.
    console.error(error.code, error.status);
  } else {
    throw error;
  }
}