Docs

Quickstart: your first P34 call Beta

P34 is one REST API: send the options in front of you and the history behind them, get back what to take, how many, and the profit to expect. Here is the whole loop — validate, submit, poll.

Base URL https://api.hyperc.com/v1 · Auth Authorization: Bearer $P34_API_KEY · Format JSON records or base64 Parquet · Status GET /health

Before you start

You need	For
Nothing at all	`GET /`, `GET /health` and `POST /validate`
An API key — register free and choose pay-as-you-go	input tests (free) and actual fits (tokens)
curl, Python 3.8+ or Node 18+	the samples below; any HTTP client works
A request — or our sample	300 generated offers from a made-up reseller, for learning the format

1 · Check the service

The root is open. It lists the model versions on offer and every endpoint.

Terminal

curl -s https://api.hyperc.com/v1/
# → {"service": "P34 PARML model API", "models": ["default", "rc012.2", …], "endpoints": [ … ]}

2 · Validate a request — free, no key

POST /validate runs the structural checks — columns, the menu-0 / T=0 rules, volume floors — and returns what it counted. Nothing is queued or charged. Iterate here until ok is true and errors is empty.

# the sample request: 300 generated offers from a made-up reseller
curl -sO https://hyperc.com/lp/sample/p34-sample-request-v1.json

# validate it: free, no key, nothing queued or charged
curl -s -X POST https://api.hyperc.com/v1/validate \
  -H "Content-Type: application/json" \
  --data @p34-sample-request-v1.json

import requests

API = "https://api.hyperc.com/v1"
req = requests.get("https://hyperc.com/lp/sample/p34-sample-request-v1.json").json()

# validate: free, no key, nothing queued or charged
v = requests.post(f"{API}/validate", json=req).json()
print(v["ok"], v["errors"], v["counts"])

// Node 18+, saved as validate.mjs
const API = "https://api.hyperc.com/v1";
const req = await (await fetch("https://hyperc.com/lp/sample/p34-sample-request-v1.json")).json();

// validate: free, no key, nothing queued or charged
const v = await (await fetch(`${API}/validate`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(req),
})).json();
console.log(v.ok, v.errors, v.counts);

Response (abridged)

{
  "ok": true,
  "errors": [],
  "counts": {
    "menus_rows": 1800, "menus_keys": 300, "t0_rows": 900,
    "history_rows": 900, "menus": 13, "sales_rows": 450
  },
  "estimate": {
    "pricing_mode": "runtime",
    "note": "an estimate from row counts alone; …"
  },
  "checked": "structure, columns, menu-0/T=0 rules, volume floors. …"
}

3 · Submit a fit

Start with an input test: the same call with "mock": true runs every input check a real fit runs and returns a result in the real shape, filled with placeholders and marked "mock": true. It is free on every key. Then send your own records without mock: that is an actual fit, and it spends tokens.

# input test first: "mock": true checks everything a fit checks, free
jq '. + {mock: true}' p34-sample-request-v1.json |
curl -s -X POST https://api.hyperc.com/v1/fit \
  -H "Authorization: Bearer $P34_API_KEY" \
  -H "Content-Type: application/json" \
  --data @-
# → {"session_id": "…", "status": "queued", "mock": true, …}

# an actual fit: your own request, without "mock"
curl -s -X POST https://api.hyperc.com/v1/fit \
  -H "Authorization: Bearer $P34_API_KEY" \
  -H "Content-Type: application/json" \
  --data @my-request.json

import os, requests

API = "https://api.hyperc.com/v1"
H = {"Authorization": f"Bearer {os.environ['P34_API_KEY']}"}  # never in code or URLs

# input test first: mock=True checks everything a fit checks, free
sid = requests.post(f"{API}/fit", headers=H, json={**req, "mock": True}).json()["session_id"]

# an actual fit is the same call on YOUR records, without "mock":
# sid = requests.post(f"{API}/fit", headers=H, json=my_request).json()["session_id"]

const API = "https://api.hyperc.com/v1";
const H = {
  "Authorization": `Bearer ${process.env.P34_API_KEY}`,  // never in code or URLs
  "Content-Type": "application/json",
};

// input test first: mock: true checks everything a fit checks, free
const { session_id } = await (await fetch(`${API}/fit`, {
  method: "POST", headers: H, body: JSON.stringify({ ...req, mock: true }),
})).json();

// an actual fit is the same call on YOUR records, without mock

The response arrives in seconds with a session_id. A fit on new data starts in grounding: P34 compiles your business description into the economics that value your history.

Sample data

The sample request is generated data. An actual fit on it would spend tokens on numbers that mean nothing — use it for /validate and input tests only.

4 · Poll for the result

Poll GET /result/{session_id} until the status is done or failed. Statuses run grounding → queued → processing → done. A fit takes minutes; every 30 seconds is plenty.

# poll every 30 s until "done" or "failed"
curl -s https://api.hyperc.com/v1/result/$SESSION_ID \
  -H "Authorization: Bearer $P34_API_KEY"

import time

while True:
    res = requests.get(f"{API}/result/{sid}", headers=H).json()
    if res["status"] in ("done", "failed"):
        break
    time.sleep(30)          # grounding → queued → processing → done | failed

plan = [row for row in res.get("menu", []) if row["qty"] > 0]
print(res["status"], len(plan), "options to take,", res.get("predicted_profit_sum"), "predicted")

let res;
do {
  await new Promise((r) => setTimeout(r, 30_000));   // grounding → queued → processing → done | failed
  res = await (await fetch(`${API}/result/${session_id}`, { headers: H })).json();
} while (!["done", "failed"].includes(res.status));

const plan = (res.menu ?? []).filter((row) => row.qty > 0);
console.log(res.status, plan.length, "options to take,", res.predicted_profit_sum, "predicted");

A done result

{
  "status": "done",
  "menu": [
    {"key": "A001", "menu": 0, "T": 0, "qty": 3.0, "profit": 42.7},
    {"key": "A002", "menu": 0, "T": 0, "qty": 0.0, "profit": -1.2}
  ],
  "n_selected": 1,
  "predicted_profit_sum": 42.7,
  "confidence_correction": 0.0,
  "confidence_sweep": [
    {"correction": -0.1, "applied": false, "n_keys_positive": 66, "total_predicted_profit": 205.7},
    {"correction": 0.0, "applied": true, "...": "one entry per correction"}
  ]
}

Rows with qty > 0 are the plan; 0 means pass, and any key missing from menu means pass too. Read the result explains every field.

Or run the whole loop in one file

p34_quickstart.py is standard-library Python: it validates, input-tests, polls and saves the plan as CSV. It never places an order, and it refuses an actual fit on the sample.

Terminal

curl -O https://hyperc.com/lp/sample/p34_quickstart.py
python3 p34_quickstart.py                    # 1 · validate the sample: free, no key

export P34_API_KEY=…                         # from your environment, never from code
python3 p34_quickstart.py                    # 2 · input test (mock: true) → p34-out/result-mock.json

python3 p34_quickstart.py --input my-request.json --real   # 3 · an actual fit on your records
python3 p34_quickstart.py --resume SESSION_ID               # keep polling a running fit

Next steps

How P34 decidesWhat the model does with your request, and when it is the right tool. Prepare your dataMenus, the sales tape and the business description, without the jargon. Offer list → purchase planThe most common job, end to end. Add P34 to an AI agentSkills, a paste-in instruction and guardrails. Models & pricingVersions, what is free, and what a fit costs. Full reference on GitHubEvery field, error and rule, with runnable examples.

The authoritative contract is the live API root, api.hyperc.com/v1/; field-by-field reference in P34-API-DOCS. Docs checked against the service on 6 October 2026.