Authentication, 81 public /v1 operations, real curl/Python/JavaScript examples, MCP, receipts, runtime limits, SDKs, and payment request shapes—on one page.
The bearer stays only in this tab's memory; it is never persisted. The console calls the same documented routes shown below.
No request sent.
{"status":"waiting"}
03 / REST API
Every public /v1 operation.
Examples are generated from one request spec per operation and rendered in curl, Python, and JavaScript. Credential and scope badges come from OpenAPI.
81 operations81 shown
Start & identity
7 operations
Service discovery, free credentials, and caller identity.
GET/v1
Service Root
Public — No credential is required.
curl --fail-with-body --silent --show-error -X GET \
"https://run.huggingbay.xyz/v1"
curl --fail-with-body --silent --show-error -X POST \
"https://run.huggingbay.xyz/v1/demo/task" \
-H 'Content-Type: application/json' \
--data "{\"task\":\"Classify support messages by intent\",\"examples\":[{\"input\":\"Cannot log in => access\"},{\"input\":\"Refund please => billing\"},{\"input\":\"Order is late => delivery\"},{\"input\":\"Account is ready => account\"},{\"input\":\"Item is broken => fulfillment\"}]}"
import os
import requests
env = lambda name, fallback: os.environ.get(name, fallback)
url = f"https://run.huggingbay.xyz/v1/demo/task"
headers = {'Content-Type': 'application/json'}
payload = {'task': 'Classify support messages by intent', 'examples': [{'input': 'Cannot log in => access'}, {'input': 'Refund please => billing'}, {'input': 'Order is late => delivery'}, {'input': 'Account is ready => account'}, {'input': 'Item is broken => fulfillment'}]}
response = requests.request("POST", url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
print(response.json())
curl --fail-with-body --silent --show-error -X POST \
"https://run.huggingbay.xyz/v1/rerank" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
--data "{\"model\":\"cross-encoder/ms-marco-TinyBERT-L2-v2\",\"query\":\"How do I verify a receipt?\",\"documents\":[\"Call the receipt verification endpoint with the returned receipt.\",\"Warm models are listed by the status endpoint.\"],\"top_n\":2}"
import os
import requests
env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_DEVELOPER_KEY"]
url = f"https://run.huggingbay.xyz/v1/rerank"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'model': 'cross-encoder/ms-marco-TinyBERT-L2-v2', 'query': 'How do I verify a receipt?', 'documents': ['Call the receipt verification endpoint with the returned receipt.', 'Warm models are listed by the status endpoint.'], 'top_n': 2}
response = requests.request("POST", url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
print(response.json())
const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/rerank`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
"model": "cross-encoder/ms-marco-TinyBERT-L2-v2",
"query": "How do I verify a receipt?",
"documents": [
"Call the receipt verification endpoint with the returned receipt.",
"Warm models are listed by the status endpoint."
],
"top_n": 2
};
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify(payload) });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());
curl --fail-with-body --silent --show-error -X POST \
"https://run.huggingbay.xyz/v1/summarize" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
--data "{\"text\":\"Bay Run routes a task to a bounded specialist. It returns route evidence and a receipt. The receipt can be checked without rerunning the task.\",\"max_sentences\":2}"
import os
import requests
env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_DEVELOPER_KEY"]
url = f"https://run.huggingbay.xyz/v1/summarize"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'text': 'Bay Run routes a task to a bounded specialist. It returns route evidence and a receipt. The receipt can be checked without rerunning the task.', 'max_sentences': 2}
response = requests.request("POST", url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
print(response.json())
const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/summarize`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
"text": "Bay Run routes a task to a bounded specialist. It returns route evidence and a receipt. The receipt can be checked without rerunning the task.",
"max_sentences": 2
};
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify(payload) });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());
Routing & evaluation
12 operations
Discover, compare, route, solve, and evaluate specialists.
POST/v1/bakeoff
Run Bakeoff Route
Optional bearer — Anonymous is supported; a bearer gives a stable principal and isolated quota.
curl --fail-with-body --silent --show-error -X POST \
"https://run.huggingbay.xyz/v1/bakeoff" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer ${BAY_RUN_API_KEY:?set BAY_RUN_API_KEY}" \
--data "{\"task_description\":\"Classify customer feedback by sentiment\",\"examples\":[{\"input\":\"Setup works perfectly.\",\"expected\":\"positive\"},{\"input\":\"Checkout is broken.\",\"expected\":\"negative\"},{\"input\":\"Search feels fast.\",\"expected\":\"positive\"}],\"public\":false}"
Use the MCP resource audience exactly: https://run.huggingbay.xyz/mcp/. Discovery and tools/list are public; protected tools/call requests use a bearer.
Integrity proves the stored commitments and execution evidence named by the receipt. It does not prove answer truth, model quality, or cryptographic model-weight identity at serve time.
# 1. Run a task and keep the complete response.
RUN=$(curl -sS -X POST "https://run.huggingbay.xyz/v1/task/run" \
-H "Authorization: Bearer $BAY_RUN_API_KEY" \
-H 'content-type: application/json' \
-d '{"task":{"task":"Classify short support messages by workflow","kind":"classification","input_schema":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]},"output_schema":{"type":"object","properties":{"label":{"type":"string"}},"required":["label"]},"examples":[{"text":"Cannot sign in","label":"access_issue"},{"text":"Refund the invoice","label":"billing_issue"},{"text":"Shipment is late","label":"delivery_issue"}],"constraints":{"minimum_quality":0.5,"max_latency_ms":20000,"max_price_usd":0.01},"data_policy":{"retention":"none","external_apis_allowed":false,"use_for_training":false},"environment":"development"},"input":{"text":"The checkout keeps rejecting my card."},"max_price_usd":0.01,"idempotency_key":"developers-portal-receipt-walkthrough-v1","payment_mode":"demo"}')
# 2. Bind the execution ID and receipt from that exact response.
VERIFY=$(jq '{execution_id:.execution_id,receipt:.execution_receipt,output:.output}' <<<"$RUN")
# 3. Verify stored execution, hashes, route, amount, and policy compliance.
curl -sS -X POST "https://run.huggingbay.xyz/v1/task/verify" \
-H "Authorization: Bearer $BAY_RUN_API_KEY" \
-H 'content-type: application/json' --data "$VERIFY" | jq .
No wallet signature, checkout session, charge, or settlement is created by these docs tests.
Production discovery currently describes Base mainnet. Configuration is not settlement evidence. Use a separately configured test deployment for real Stripe test-mode or Base testnet exercises.
x402 challenge shape
# REQUEST-SHAPE TEST ONLY — no PAYMENT-SIGNATURE, so no settlement occurs.
curl -i -X POST "https://run.huggingbay.xyz/x402/tasks/run" \
-H 'content-type: application/json' \
-d '{"task":{"task":"Classify short support messages by workflow","kind":"classification","input_schema":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]},"output_schema":{"type":"object","properties":{"label":{"type":"string"}},"required":["label"]},"examples":[{"text":"Cannot sign in","label":"access_issue"},{"text":"Refund the invoice","label":"billing_issue"},{"text":"Shipment is late","label":"delivery_issue"}],"constraints":{"minimum_quality":0.5,"max_latency_ms":20000,"max_price_usd":0.01},"data_policy":{"retention":"none","external_apis_allowed":false,"use_for_training":false},"environment":"development"},"input":{"text":"test-mode shape"},"max_price_usd":0.005,"idempotency_key":"developers-portal-x402-test-v1"}'
# Expect HTTP 402 and inspect PAYMENT-REQUIRED. Do not add a wallet signature in docs tests.
# TEST-MODE SHAPE ONLY — use a test deployment + Stripe test key.
curl -i -X POST "https://run.huggingbay.xyz/v1/billing/stripe/checkout-session" \
-H "Authorization: Bearer $BAY_RUN_TEST_MANAGEMENT_KEY" \
-H 'Idempotency-Key: developers-portal-stripe-test-v1' \
-H 'content-type: application/json' -d '{"pack_code":"starter_1000"}'
# Portal acceptance supplies no owner key, so production rejects this before Stripe.