Quick runs and endpoints: stateless and stateful

The quick run

One pass, one full bundle, nothing kept. It suits agents, pipelines, and one-shot analysis. Data is used transiently and nothing is registered.

curl -X POST 'https://api.example.com/v2/run' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tables": [{"name": "orders", "rows": [{"id": 1, "amount": 42.5}]}]}'

import os, requests

r = requests.post(
    "https://api.example.com/v2/run",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"tables": [{"name": "orders", "rows": [{"id": 1, "amount": 42.5}]}]},
)
print(r.json()["sector"])

The endpoint

A persistent object that bundles a base model, pinned data snapshots, configuration, and a held-out report, exposed at a stable URL. The ID and URL never change, even when the name does.

Three independent versions

An endpoint's state has three parts that change on their own schedules: the base model generation, the data snapshot, and the configuration revision. Every change is additive, and the endpoint keeps serving while it happens.

Lifecycle

1. Create. Returns a job straight away. The endpoint goes live within minutes. Check the held-out report before sharing results.
2. Serve. Score request rows against the pinned state.
3. Refresh. Re-sync the data into a new snapshot and re-score on a fresh split.
4. Upgrade. Re-run the same pinned data on a newer base and report the score change.

Two rules that keep it safe

• Every mutating operation mints a report. Create, refresh, and upgrade each leave a record of what changed and how the score moved.
• One mutating job at a time per endpoint. A second request gets a clear conflict, not a race.