OpenAI-compatible.
Explicit by design.

List, select, run.

Install the OpenAI Python SDK, keep your key in the environment, then select an exact ID from the live catalog. Do not hard-code a model name that the catalog did not return.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://newtons.dev/api/v1",
    api_key=os.environ["NEWTONS_API_KEY"],
)

catalog = client.models.list()
if not catalog.data:
    raise RuntimeError("No models published.")

model_id = catalog.data[0].id
completion = client.chat.completions.create(
    model=model_id,
    messages=[{"role": "user", "content": "Reply exactly: Newton's connected"}],
    max_tokens=32,
)

print(completion.choices[0].message.content)
print("resolved model:", completion.model)

Expected application result: a normal Chat Completion whose model matches the selected published ID. The JSON response also contains a newtons receipt object. Keep the key out of source code, chat, logs, screenshots, and committed files.

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "<published-model-id>",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "Newton's connected" } }],
  "usage": { "prompt_tokens": 12, "completion_tokens": 4, "total_tokens": 16 },
  "newtons": {
    "request_id": "…",
    "requested_model": "<published-model-id>",
    "resolved_model": "<published-model-id>",
    "fallback_used": false,
    "cost_usd": "…",
    "balance_usd": "…",
    "cost_estimated": false
  }
}

Focused surface.

Use https://newtons.dev/api/v1 as the SDK base URL. All routes require Authorization: Bearer $NEWTONS_API_KEY.

Read through the final receipt.

Set stream=True and consume the stream until [DONE]. Newton’s appends a terminal chunk with empty choices and the settled newtons receipt before the done sentinel.

stream = client.chat.completions.create(
    model=model_id,
    messages=[{"role": "user", "content": "Explain inertia in one sentence."}],
    max_tokens=80,
    stream=True,
)

receipt = None
for chunk in stream:
    if chunk.choices:
        text = chunk.choices[0].delta.content
        if text:
            print(text, end="", flush=True)
    extra = getattr(chunk, "model_extra", None) or {}
    receipt = extra.get("newtons") or receipt

print("\\nreceipt:", receipt)

The HTTP receipt headers at stream start are an authorization estimate. The terminal receipt is the settled result. If the stream emits an error event, treat it as terminal and do not execute tool side effects from an incomplete response.

Retry by class, not by instinct.

A retry can create a second billable completion if the first request finished upstream but its response was lost. Retry only operations your application can safely repeat, and never retry a completed tool side effect merely because its reporting request failed.

Known envelopes.

Capacity, safety, fraud, balance, and model-availability controls also apply. A rate or concurrency response uses 429 and includes Retry-After.

Every accepted call accounts for itself.

x-newtons-request-cost-usd
x-newtons-balance-usd
x-newtons-cost-estimated
x-newtons-request-id
x-newtons-requested-model
x-newtons-resolved-model
x-newtons-fallback-used
x-newtons-rpm-limit
x-newtons-concurrency-limit

Usage is reserved before inference, reconciled against returned usage, and settled in integer micro-USD internally. Receipts are accounting metadata, not cryptographic attestations. Save the request ID—not the prompt or API key—when asking for support.

Pinned means no silent swap.

A published model ID remains pinned to that route. Newton’s requires the upstream-reported ID to match; mismatched or unconfirmed responses fail closed. If you explicitly provide documented fallback_models, Newton’s may try up to three of those published IDs in the order supplied and reports whether a fallback was used.

Automatic model routing is not currently part of the public API.

Know what is—and is not—implemented.