Developers | Bay Run

01 / Authentication

Start anonymous. Keep identity only when you need it.

Never place owner-management, spend, or operator credentials in a general agent harness.

Demo bearer

Zero secret, short-lived

Rate-limited and isolated by token/IP. The same anonymous mcp:demo credential class works on both public REST and MCP. This example pre-binds the REST resource (and the token response’s next_call) for convenience; privileged, billing, and owner credentials remain strictly audience-bound. Mint it:

curl -sS -X POST 'https://run.huggingbay.xyz/oauth/token' -H 'content-type: application/json' -d '{"grant_type":"urn:bay-run:grant-type:demo","scope":"mcp:demo","resource":"https://run.huggingbay.xyz"}' | jq -er .access_token

Durable free key

No email, card, or signup

The secret is displayed once and can revoke only itself. This is the same mint request exercised by MCP recipe 2.

curl -sS -X POST 'https://run.huggingbay.xyz/v1/keys/free' | jq -er .key

OAuth

Durable machine identity

Register client_secret_post, store the secret outside the agent, and remint short-lived access tokens. Public OAuth is not human-owner authority.

Authorization-server metadata →

02 / Task workspace

Quote → run → verify, without leaving the page.

The bearer stays only in this tab's memory; it is never persisted. The console calls the same quote, run, and verify routes exposed by the advanced API contract.

Demo, free, OAuth, or scoped developer bearer Quote body

{
  "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"
  },
  "quote_ttl_seconds": 900
}

No request sent.

{"status":"waiting"}

03 / Compatibility

Advanced REST operations.

These compatibility routes stay outside the default three-tool MCP surface. Expand them only when coprocessor, a direct run_pin alias, or solve_task is not enough.

Browse 102 advanced REST operations

401 recovery for owner management: Do not retry with a demo or OAuth bearer. Open /account, complete the operator-enabled magic-link flow on the exact Bay Run Origin, then retry the same request once with the owner-session cookie or X-Owner-Session. For /v1/owner/pins, retry the same request once with the same durable owner key because that principal defines key-owned Pins; make no further automatic retry.

Start & identity

6 operations

Service discovery, free credentials, and caller identity.

Browse 6 operations

GET/v1

Service Root

Public — No credential is required.

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
url = f"https://run.huggingbay.xyz/v1"
headers = {}
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1`;
const headers = {};
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/demo/task

Public Task Demo

Public — No credential is required.

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())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/demo/task`;
const headers = {};
headers["Content-Type"] = "application/json";
const 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"
    }
  ]
};
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());

GET/v1/identity

Caller Identity

Bearer — Use a demo, durable free, OAuth, or appropriately scoped developer bearer.

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/identity" \
  -H "Authorization: Bearer ${BAY_RUN_API_KEY:?set BAY_RUN_API_KEY}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_API_KEY"]
url = f"https://run.huggingbay.xyz/v1/identity"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/identity`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_API_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/keys/free

Create Free Key Route

Public — No credential is required.

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/keys/free"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
url = f"https://run.huggingbay.xyz/v1/keys/free"
headers = {}
response = requests.request("POST", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/keys/free`;
const headers = {};
const response = await fetch(url, { method: "POST", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

DELETE/v1/keys/free/{key_id}

Revoke Free Key Route

Free key self-revocation — Use the same bay_live_ key named by key_id.

curl --fail-with-body --silent --show-error -X DELETE \
  "https://run.huggingbay.xyz/v1/keys/free/${FREE_KEY_ID:-bfk_00000000000000000000000000000000}" \
  -H "Authorization: Bearer ${BAY_RUN_FREE_KEY:?set BAY_RUN_FREE_KEY}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_FREE_KEY"]
url = f"https://run.huggingbay.xyz/v1/keys/free/{env('FREE_KEY_ID', 'bfk_00000000000000000000000000000000')}"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("DELETE", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/keys/free/${env("FREE_KEY_ID", "bfk_00000000000000000000000000000000")}`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_FREE_KEY}`;
const response = await fetch(url, { method: "DELETE", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

GET/v1/quickstart

Serve Quickstart

Public — No credential is required.

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/quickstart"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
url = f"https://run.huggingbay.xyz/v1/quickstart"
headers = {}
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/quickstart`;
const headers = {};
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

Inference & documents

11 operations

OpenAI-compatible inference and bounded document tools.

Browse 11 operations

POST/v1/chat/completions

Chat Completions

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/chat/completions" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"model\":\"auto\",\"messages\":[{\"role\":\"user\",\"content\":\"In one sentence, why verify AI receipts?\"}],\"max_tokens\":48,\"temperature\":0}"

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/chat/completions"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'model': 'auto', 'messages': [{'role': 'user', 'content': 'In one sentence, why verify AI receipts?'}], 'max_tokens': 48, 'temperature': 0}
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/chat/completions`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "model": "auto",
  "messages": [
    {
      "role": "user",
      "content": "In one sentence, why verify AI receipts?"
    }
  ],
  "max_tokens": 48,
  "temperature": 0
};
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());

POST/v1/classify

Classify Route

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/classify" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"model\":\"distilbert/distilbert-base-uncased-finetuned-sst-2-english\",\"input\":[\"The setup was quick.\",\"The checkout is broken.\"],\"top_k\":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/classify"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'model': 'distilbert/distilbert-base-uncased-finetuned-sst-2-english', 'input': ['The setup was quick.', 'The checkout is broken.'], 'top_k': 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/classify`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "model": "distilbert/distilbert-base-uncased-finetuned-sst-2-english",
  "input": [
    "The setup was quick.",
    "The checkout is broken."
  ],
  "top_k": 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());

POST/v1/document/extract

Document Extract Route

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/document/extract" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"content\":\"title,owner\\nDeveloper portal,Bay Run\\nReceipts,Operators\\n\",\"mime_type\":\"text/csv\",\"filename\":\"developer-example.csv\",\"max_rows\":10}"

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/document/extract"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'content': 'title,owner\nDeveloper portal,Bay Run\nReceipts,Operators\n', 'mime_type': 'text/csv', 'filename': 'developer-example.csv', 'max_rows': 10}
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/document/extract`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "content": "title,owner\nDeveloper portal,Bay Run\nReceipts,Operators\n",
  "mime_type": "text/csv",
  "filename": "developer-example.csv",
  "max_rows": 10
};
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());

POST/v1/embeddings

Create Embeddings

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/embeddings" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"model\":\"BAAI/bge-small-en-v1.5\",\"input\":[\"Bay Run returns verifiable specialist-model results.\"]}"

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/embeddings"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'model': 'BAAI/bge-small-en-v1.5', 'input': ['Bay Run returns verifiable specialist-model results.']}
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/embeddings`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "model": "BAAI/bge-small-en-v1.5",
  "input": [
    "Bay Run returns verifiable specialist-model results."
  ]
};
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());

POST/v1/guard

Guard Route

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/guard" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"input\":\"Please summarize the invoice for the owner.\",\"channel\":\"user\"}"

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/guard"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'input': 'Please summarize the invoice for the owner.', 'channel': 'user'}
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/guard`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "input": "Please summarize the invoice for the owner.",
  "channel": "user"
};
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());

POST/v1/pdf/extract

Pdf Extract Route

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/pdf/extract" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"pdf_base64\":\"JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCA2OCA+PgpzdHJlYW0KQlQgL0YxIDE0IFRmIDcyIDcyMCBUZCAoQmF5IFJ1biBkZXZlbG9wZXIgcG9ydGFsIGxpdmUgZXhhbXBsZSkgVGogRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzNTkgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjkKJSVFT0YK\",\"max_pages\":1,\"max_chars\":2000}"

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/pdf/extract"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'pdf_base64': 'JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCA2OCA+PgpzdHJlYW0KQlQgL0YxIDE0IFRmIDcyIDcyMCBUZCAoQmF5IFJ1biBkZXZlbG9wZXIgcG9ydGFsIGxpdmUgZXhhbXBsZSkgVGogRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzNTkgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjkKJSVFT0YK', 'max_pages': 1, 'max_chars': 2000}
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/pdf/extract`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "pdf_base64": "JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCA2OCA+PgpzdHJlYW0KQlQgL0YxIDE0IFRmIDcyIDcyMCBUZCAoQmF5IFJ1biBkZXZlbG9wZXIgcG9ydGFsIGxpdmUgZXhhbXBsZSkgVGogRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzNTkgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjkKJSVFT0YK",
  "max_pages": 1,
  "max_chars": 2000
};
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());

POST/v1/pdf/extract/upload

Upload and extract a bounded PDF

Developer key — Required scopes: inference:invoke.

inference:invoke

PDF_BASE64='JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCA2OCA+PgpzdHJlYW0KQlQgL0YxIDE0IFRmIDcyIDcyMCBUZCAoQmF5IFJ1biBkZXZlbG9wZXIgcG9ydGFsIGxpdmUgZXhhbXBsZSkgVGogRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzNTkgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjkKJSVFT0YK'
printf '%s' "$PDF_BASE64" | base64 --decode > /tmp/bay-run-developer-example.pdf
curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/pdf/extract/upload" \
  -H 'Content-Type: application/pdf' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data-binary '@/tmp/bay-run-developer-example.pdf'

import os
import base64
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/pdf/extract/upload"
headers = {'Content-Type': 'application/pdf'}
headers["Authorization"] = f"Bearer {token}"
body = base64.b64decode('JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCA2OCA+PgpzdHJlYW0KQlQgL0YxIDE0IFRmIDcyIDcyMCBUZCAoQmF5IFJ1biBkZXZlbG9wZXIgcG9ydGFsIGxpdmUgZXhhbXBsZSkgVGogRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzNTkgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjkKJSVFT0YK')
response = requests.request("POST", url, headers=headers, data=body, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/pdf/extract/upload`;
const headers = {};
headers["Content-Type"] = "application/pdf";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const body = Buffer.from("JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCA2OCA+PgpzdHJlYW0KQlQgL0YxIDE0IFRmIDcyIDcyMCBUZCAoQmF5IFJ1biBkZXZlbG9wZXIgcG9ydGFsIGxpdmUgZXhhbXBsZSkgVGogRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzNTkgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MjkKJSVFT0YK", "base64");
const response = await fetch(url, { method: "POST", headers, body });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/policy

Policy Route

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/policy" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"proposed_action\":\"summarize_record(invoice_id=1)\",\"user_request\":\"Summarize the invoice.\",\"owner_rules\":[]}"

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/policy"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'proposed_action': 'summarize_record(invoice_id=1)', 'user_request': 'Summarize the invoice.', 'owner_rules': []}
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/policy`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "proposed_action": "summarize_record(invoice_id=1)",
  "user_request": "Summarize the invoice.",
  "owner_rules": []
};
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());

POST/v1/rag

Rag Route

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/rag" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"query\":\"What does receipt verification prove?\",\"documents\":[\"Receipt verification checks stored hashes, route facts, and charge evidence.\",\"It does not prove answer truth or model-weight identity.\"],\"top_k\":2,\"answer\":false}"

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/rag"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'query': 'What does receipt verification prove?', 'documents': ['Receipt verification checks stored hashes, route facts, and charge evidence.', 'It does not prove answer truth or model-weight identity.'], 'top_k': 2, 'answer': False}
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/rag`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "query": "What does receipt verification prove?",
  "documents": [
    "Receipt verification checks stored hashes, route facts, and charge evidence.",
    "It does not prove answer truth or model-weight identity."
  ],
  "top_k": 2,
  "answer": false
};
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());

POST/v1/rerank

Rerank Route

Developer key — Required scopes: inference:invoke.

inference:invoke

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());

POST/v1/summarize

Summarize Route

Developer key — Required scopes: inference:invoke.

inference:invoke

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

31 operations

Discover, compare, route, solve, and evaluate specialists.

Browse 31 operations

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}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_API_KEY"]
url = f"https://run.huggingbay.xyz/v1/bakeoff"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'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}
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/bakeoff`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_API_KEY}`;
const payload = {
  "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
};
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());

POST/v1/bakeoffs/{bakeoff_id}/claim

Claim Public Bakeoff

Public — No credential is required.

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/bakeoffs/${BAKEOFF_ID:-bo_00000000000000000000000000000000}/claim" \
  -H 'Content-Type: application/json' \
  --data "{\"hf_repo_id\":\"${BAKEOFF_WINNER:-BAAI/bge-small-en-v1.5}\"}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
url = f"https://run.huggingbay.xyz/v1/bakeoffs/{env('BAKEOFF_ID', 'bo_00000000000000000000000000000000')}/claim"
headers = {'Content-Type': 'application/json'}
payload = {'hf_repo_id': env("BAKEOFF_WINNER", "BAAI/bge-small-en-v1.5")}
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/bakeoffs/${env("BAKEOFF_ID", "bo_00000000000000000000000000000000")}/claim`;
const headers = {};
headers["Content-Type"] = "application/json";
const payload = {
  "hf_repo_id": env("BAKEOFF_WINNER", "BAAI/bge-small-en-v1.5")
};
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());

GET/v1/cache

Cache Status

Developer key — Required scopes: models:read.

models:read

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/cache" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/cache"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/cache`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/coprocessor

Coprocessor Route

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/coprocessor" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"user_text\":\"How do I reset a password?\",\"documents\":[\"Open Settings and choose Reset password.\",\"Invoices are available under Billing.\"]}"

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/coprocessor"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'user_text': 'How do I reset a password?', 'documents': ['Open Settings and choose Reset password.', 'Invoices are available under Billing.']}
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/coprocessor`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "user_text": "How do I reset a password?",
  "documents": [
    "Open Settings and choose Reset password.",
    "Invoices are available under Billing."
  ]
};
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());

POST/v1/discover

Discover

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/discover" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"query\":\"small English embedding model for semantic search\",\"kind\":\"embedding\",\"limit\":3,\"prefer_warm\":true}"

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/discover"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'query': 'small English embedding model for semantic search', 'kind': 'embedding', 'limit': 3, 'prefer_warm': True}
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/discover`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "query": "small English embedding model for semantic search",
  "kind": "embedding",
  "limit": 3,
  "prefer_warm": true
};
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());

POST/v1/eval

Evaluate

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/eval" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"task\":\"embedding\",\"models\":[\"sentence-transformers/all-MiniLM-L6-v2\",\"BAAI/bge-small-en-v1.5\"],\"dataset\":[{\"query\":\"receipt verification\",\"positive\":\"verify stored hashes and route evidence\",\"negatives\":[\"today's weather\"]}],\"k\":1,\"prefer_warm\":true}"

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/eval"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'task': 'embedding', 'models': ['sentence-transformers/all-MiniLM-L6-v2', 'BAAI/bge-small-en-v1.5'], 'dataset': [{'query': 'receipt verification', 'positive': 'verify stored hashes and route evidence', 'negatives': ["today's weather"]}], 'k': 1, 'prefer_warm': True}
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/eval`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "task": "embedding",
  "models": [
    "sentence-transformers/all-MiniLM-L6-v2",
    "BAAI/bge-small-en-v1.5"
  ],
  "dataset": [
    {
      "query": "receipt verification",
      "positive": "verify stored hashes and route evidence",
      "negatives": [
        "today's weather"
      ]
    }
  ],
  "k": 1,
  "prefer_warm": true
};
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());

DELETE/v1/eval/namespaces/{namespace}

Delete Private Evaluation Namespace

Developer key — Required scopes: data:delete.

data:delete

curl --fail-with-body --silent --show-error -X DELETE \
  "https://run.huggingbay.xyz/v1/eval/namespaces/${EVALUATION_NAMESPACE:-developers-portal-test}" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/eval/namespaces/{env('EVALUATION_NAMESPACE', 'developers-portal-test')}"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("DELETE", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/eval/namespaces/${env("EVALUATION_NAMESPACE", "developers-portal-test")}`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "DELETE", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/find_specialist

Find Specialist

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/find_specialist" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"task\":\"Classify short customer messages by sentiment\",\"my_examples\":[{\"text\":\"Great setup\",\"label\":\"positive\"},{\"text\":\"Broken checkout\",\"label\":\"negative\"}],\"kind\":\"classification\",\"n_candidates\":2,\"k\":1}"

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/find_specialist"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'task': 'Classify short customer messages by sentiment', 'my_examples': [{'text': 'Great setup', 'label': 'positive'}, {'text': 'Broken checkout', 'label': 'negative'}], 'kind': 'classification', 'n_candidates': 2, 'k': 1}
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/find_specialist`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "task": "Classify short customer messages by sentiment",
  "my_examples": [
    {
      "text": "Great setup",
      "label": "positive"
    },
    {
      "text": "Broken checkout",
      "label": "negative"
    }
  ],
  "kind": "classification",
  "n_candidates": 2,
  "k": 1
};
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());

GET/v1/models

List Models

Developer key — Required scopes: models:read.

models:read

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/models" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/models"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/models`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/owner/auth/magic-link

Request Owner Magic Link

Operator-gated owner sign-in — No bearer is accepted. Request a magic link at /account when the operator-enabled owner surface is available.

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/owner/auth/magic-link" \
  -H 'Content-Type: application/json' \
  --data "{\"email\":\"owner@example.test\"}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
url = f"https://run.huggingbay.xyz/v1/owner/auth/magic-link"
headers = {'Content-Type': 'application/json'}
payload = {'email': 'owner@example.test'}
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/owner/auth/magic-link`;
const headers = {};
headers["Content-Type"] = "application/json";
const payload = {
  "email": "owner@example.test"
};
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());

POST/v1/owner/auth/magic-link/consume

Consume Owner Magic Link

Operator-gated owner sign-in — Consume the one-time magic token on the exact Bay Run Origin; request a fresh link at /account if it fails.

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/owner/auth/magic-link/consume" \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://run.huggingbay.xyz' \
  --data "{\"token\":\"owner_magic_link_token_redacted\"}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
url = f"https://run.huggingbay.xyz/v1/owner/auth/magic-link/consume"
headers = {'Content-Type': 'application/json', 'Origin': 'https://run.huggingbay.xyz'}
payload = {'token': 'owner_magic_link_token_redacted'}
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/owner/auth/magic-link/consume`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Origin"] = "https://run.huggingbay.xyz";
const payload = {
  "token": "owner_magic_link_token_redacted"
};
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());

GET/v1/owner/keys

List Owner Keys

Owner session — Private and operator-gated. On 401, open /account, request and consume a magic link on the exact Bay Run Origin, then retry the same request once with the session cookie or X-Owner-Session; do not mint a demo or OAuth bearer or retry again automatically.

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/owner/keys" \
  -H "X-Owner-Session: ${BAY_RUN_OWNER_SESSION:?set BAY_RUN_OWNER_SESSION}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_OWNER_SESSION"]
url = f"https://run.huggingbay.xyz/v1/owner/keys"
headers = {}
headers['X-Owner-Session'] = token
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/owner/keys`;
const headers = {};
headers["X-Owner-Session"] = `${process.env.BAY_RUN_OWNER_SESSION}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/owner/keys

Create Owner Key

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/owner/keys" \
  -H 'Content-Type: application/json' \
  -H "X-Owner-Session: ${BAY_RUN_OWNER_SESSION:?set BAY_RUN_OWNER_SESSION}" \
  -H 'Origin: https://run.huggingbay.xyz' \
  --data "{\"name\":\"developers-portal-owner-key\",\"scopes\":[\"inference:invoke\"],\"ceiling_usd\":\"0.00\",\"key_type\":\"recovery_reader\",\"retention_policy\":\"none\"}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_OWNER_SESSION"]
url = f"https://run.huggingbay.xyz/v1/owner/keys"
headers = {'Content-Type': 'application/json', 'Origin': 'https://run.huggingbay.xyz'}
headers['X-Owner-Session'] = token
payload = {'name': 'developers-portal-owner-key', 'scopes': ['inference:invoke'], 'ceiling_usd': '0.00', 'key_type': 'recovery_reader', 'retention_policy': 'none'}
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/owner/keys`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["X-Owner-Session"] = `${process.env.BAY_RUN_OWNER_SESSION}`;
headers["Origin"] = "https://run.huggingbay.xyz";
const payload = {
  "name": "developers-portal-owner-key",
  "scopes": [
    "inference:invoke"
  ],
  "ceiling_usd": "0.00",
  "key_type": "recovery_reader",
  "retention_policy": "none"
};
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());

POST/v1/owner/keys/{key_id}/revoke

Revoke Owner Key

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/owner/keys/${FREE_KEY_ID:-bfk_00000000000000000000000000000000}/revoke" \
  -H "X-Owner-Session: ${BAY_RUN_OWNER_SESSION:?set BAY_RUN_OWNER_SESSION}" \
  -H 'Origin: https://run.huggingbay.xyz'

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_OWNER_SESSION"]
url = f"https://run.huggingbay.xyz/v1/owner/keys/{env('FREE_KEY_ID', 'bfk_00000000000000000000000000000000')}/revoke"
headers = {'Origin': 'https://run.huggingbay.xyz'}
headers['X-Owner-Session'] = token
response = requests.request("POST", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/owner/keys/${env("FREE_KEY_ID", "bfk_00000000000000000000000000000000")}/revoke`;
const headers = {};
headers["X-Owner-Session"] = `${process.env.BAY_RUN_OWNER_SESSION}`;
headers["Origin"] = "https://run.huggingbay.xyz";
const response = await fetch(url, { method: "POST", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

GET/v1/owner/pins

List Owner Pins

Owner key or session — Private. On 401, retry the same request once with the same owning principal; do not switch to a newly issued key or principal or retry again automatically. An operator-gated session from /account accesses only the separately account-owned view; it does not recover key-owned Pins.

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/owner/pins" \
  -H "Authorization: Bearer ${BAY_RUN_OWNER_KEY:?set BAY_RUN_OWNER_KEY}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_OWNER_KEY"]
url = f"https://run.huggingbay.xyz/v1/owner/pins"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/owner/pins`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_OWNER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/owner/pins/{pin_id}/promote

Promote Owner Pin

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/owner/pins/${PIN_ID:-guard}/promote" \
  -H 'Content-Type: application/json' \
  -H "X-Owner-Session: ${BAY_RUN_OWNER_SESSION:?set BAY_RUN_OWNER_SESSION}" \
  --data "{\"content\":{\"family\":\"classification\",\"task\":\"Classify support tickets as access, billing, or delivery\",\"model\":\"cross-encoder/nli-deberta-v3-xsmall\",\"candidate_labels\":[\"access_issue\",\"billing_issue\",\"delivery_issue\"],\"max_price_usd\":0.01,\"lane_state\":\"warm\"},\"expected_revision\":1,\"idempotency_key\":\"developers-portal-pin-promote-v2\"}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_OWNER_SESSION"]
url = f"https://run.huggingbay.xyz/v1/owner/pins/{env('PIN_ID', 'guard')}/promote"
headers = {'Content-Type': 'application/json'}
headers['X-Owner-Session'] = token
payload = {'content': {'family': 'classification', 'task': 'Classify support tickets as access, billing, or delivery', 'model': 'cross-encoder/nli-deberta-v3-xsmall', 'candidate_labels': ['access_issue', 'billing_issue', 'delivery_issue'], 'max_price_usd': 0.01, 'lane_state': 'warm'}, 'expected_revision': 1, 'idempotency_key': 'developers-portal-pin-promote-v2'}
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/owner/pins/${env("PIN_ID", "guard")}/promote`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["X-Owner-Session"] = `${process.env.BAY_RUN_OWNER_SESSION}`;
const payload = {
  "content": {
    "family": "classification",
    "task": "Classify support tickets as access, billing, or delivery",
    "model": "cross-encoder/nli-deberta-v3-xsmall",
    "candidate_labels": [
      "access_issue",
      "billing_issue",
      "delivery_issue"
    ],
    "max_price_usd": 0.01,
    "lane_state": "warm"
  },
  "expected_revision": 1,
  "idempotency_key": "developers-portal-pin-promote-v2"
};
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());

GET/v1/owner/pins/{pin_id}/revisions

List Owner Pin Revisions

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/owner/pins/${PIN_ID:-guard}/revisions" \
  -H "X-Owner-Session: ${BAY_RUN_OWNER_SESSION:?set BAY_RUN_OWNER_SESSION}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_OWNER_SESSION"]
url = f"https://run.huggingbay.xyz/v1/owner/pins/{env('PIN_ID', 'guard')}/revisions"
headers = {}
headers['X-Owner-Session'] = token
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/owner/pins/${env("PIN_ID", "guard")}/revisions`;
const headers = {};
headers["X-Owner-Session"] = `${process.env.BAY_RUN_OWNER_SESSION}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/owner/pins/{pin_id}/rollback

Rollback Owner Pin

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/owner/pins/${PIN_ID:-guard}/rollback" \
  -H 'Content-Type: application/json' \
  -H "X-Owner-Session: ${BAY_RUN_OWNER_SESSION:?set BAY_RUN_OWNER_SESSION}" \
  --data "{\"target_revision\":1,\"expected_revision\":2,\"idempotency_key\":\"developers-portal-pin-rollback-v1\"}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_OWNER_SESSION"]
url = f"https://run.huggingbay.xyz/v1/owner/pins/{env('PIN_ID', 'guard')}/rollback"
headers = {'Content-Type': 'application/json'}
headers['X-Owner-Session'] = token
payload = {'target_revision': 1, 'expected_revision': 2, 'idempotency_key': 'developers-portal-pin-rollback-v1'}
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/owner/pins/${env("PIN_ID", "guard")}/rollback`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["X-Owner-Session"] = `${process.env.BAY_RUN_OWNER_SESSION}`;
const payload = {
  "target_revision": 1,
  "expected_revision": 2,
  "idempotency_key": "developers-portal-pin-rollback-v1"
};
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());

GET/v1/owner/receipts

List Owner Receipts

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/owner/receipts" \
  -H "X-Owner-Session: ${BAY_RUN_OWNER_SESSION:?set BAY_RUN_OWNER_SESSION}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_OWNER_SESSION"]
url = f"https://run.huggingbay.xyz/v1/owner/receipts"
headers = {}
headers['X-Owner-Session'] = token
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/owner/receipts`;
const headers = {};
headers["X-Owner-Session"] = `${process.env.BAY_RUN_OWNER_SESSION}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

GET/v1/owner/session

Owner Session Info

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/owner/session" \
  -H "X-Owner-Session: ${BAY_RUN_OWNER_SESSION:?set BAY_RUN_OWNER_SESSION}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_OWNER_SESSION"]
url = f"https://run.huggingbay.xyz/v1/owner/session"
headers = {}
headers['X-Owner-Session'] = token
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/owner/session`;
const headers = {};
headers["X-Owner-Session"] = `${process.env.BAY_RUN_OWNER_SESSION}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/pin

Mint Pin Route

Public — No credential is required.

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/pin" \
  -H 'Content-Type: application/json' \
  --data "{\"task\":\"Classify support messages by urgency\",\"model\":\"org/specialist\",\"family\":\"binary_sentiment\",\"quote_id\":\"quote_0123456789abcdef\"}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
url = f"https://run.huggingbay.xyz/v1/pin"
headers = {'Content-Type': 'application/json'}
payload = {'task': 'Classify support messages by urgency', 'model': 'org/specialist', 'family': 'binary_sentiment', 'quote_id': 'quote_0123456789abcdef'}
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/pin`;
const headers = {};
headers["Content-Type"] = "application/json";
const payload = {
  "task": "Classify support messages by urgency",
  "model": "org/specialist",
  "family": "binary_sentiment",
  "quote_id": "quote_0123456789abcdef"
};
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());

POST/v1/pin/measured

Mint Measured Pin Route

Public — No credential is required.

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/pin/measured" \
  -H 'Content-Type: application/json' \
  --data "{\"task\":\"Developer sample only: classify support tickets. Caller-supplied rows are not production evidence, and this example claims no measured result.\",\"paste\":\"{\\\"input\\\":\\\"I cannot log into my account.\\\",\\\"expected\\\":\\\"access_issue\\\"}\\n{\\\"input\\\":\\\"The password reset link has expired.\\\",\\\"expected\\\":\\\"access_issue\\\"}\\n{\\\"input\\\":\\\"My account is locked after too many attempts.\\\",\\\"expected\\\":\\\"access_issue\\\"}\\n{\\\"input\\\":\\\"I need to change the email address on my account.\\\",\\\"expected\\\":\\\"access_issue\\\"}\\n{\\\"input\\\":\\\"The sign-in code never arrived.\\\",\\\"expected\\\":\\\"access_issue\\\"}\\n{\\\"input\\\":\\\"I cannot update my password.\\\",\\\"expected\\\":\\\"access_issue\\\"}\\n{\\\"input\\\":\\\"Two-factor authentication is blocking my login.\\\",\\\"expected\\\":\\\"access_issue\\\"}\\n{\\\"input\\\":\\\"The invitation link says I do not have access.\\\",\\\"expected\\\":\\\"access_issue\\\"}\\n{\\\"input\\\":\\\"I cannot open the account dashboard.\\\",\\\"expected\\\":\\\"access_issue\\\"}\\n{\\\"input\\\":\\\"Login keeps sending me back to the sign-in page.\\\",\\\"expected\\\":\\\"access_issue\\\"}\\n{\\\"input\\\":\\\"Please refund this invoice.\\\",\\\"expected\\\":\\\"billing_issue\\\"}\\n{\\\"input\\\":\\\"I was charged twice for the same order.\\\",\\\"expected\\\":\\\"billing_issue\\\"}\\n{\\\"input\\\":\\\"Where can I update my payment method?\\\",\\\"expected\\\":\\\"billing_issue\\\"}\\n{\\\"input\\\":\\\"The amount on my invoice is incorrect.\\\",\\\"expected\\\":\\\"billing_issue\\\"}\\n{\\\"input\\\":\\\"I want to cancel my subscription.\\\",\\\"expected\\\":\\\"billing_issue\\\"}\\n{\\\"input\\\":\\\"Please send me a receipt for my payment.\\\",\\\"expected\\\":\\\"billing_issue\\\"}\\n{\\\"input\\\":\\\"My card was declined at checkout.\\\",\\\"expected\\\":\\\"billing_issue\\\"}\\n{\\\"input\\\":\\\"I do not recognize this charge.\\\",\\\"expected\\\":\\\"billing_issue\\\"}\\n{\\\"input\\\":\\\"Can you update the billing address on my account?\\\",\\\"expected\\\":\\\"billing_issue\\\"}\\n{\\\"input\\\":\\\"What is the status of my refund?\\\",\\\"expected\\\":\\\"billing_issue\\\"}\\n{\\\"input\\\":\\\"I was charged for a renewal I did not expect.\\\",\\\"expected\\\":\\\"billing_issue\\\"}\\n{\\\"input\\\":\\\"How do I change to a different pricing plan?\\\",\\\"expected\\\":\\\"billing_issue\\\"}\\n{\\\"input\\\":\\\"My payment has been pending since yesterday.\\\",\\\"expected\\\":\\\"billing_issue\\\"}\\n{\\\"input\\\":\\\"My shipment is late and has not arrived.\\\",\\\"expected\\\":\\\"delivery_issue\\\"}\\n{\\\"input\\\":\\\"The package was marked delivered but is missing.\\\",\\\"expected\\\":\\\"delivery_issue\\\"}\\n{\\\"input\\\":\\\"I need to change the delivery address.\\\",\\\"expected\\\":\\\"delivery_issue\\\"}\\n{\\\"input\\\":\\\"The tracking information has not updated.\\\",\\\"expected\\\":\\\"delivery_issue\\\"}\\n{\\\"input\\\":\\\"The order arrived with the wrong item.\\\",\\\"expected\\\":\\\"delivery_issue\\\"}\\n{\\\"input\\\":\\\"The parcel arrived damaged.\\\",\\\"expected\\\":\\\"delivery_issue\\\"}\\n{\\\"input\\\":\\\"When should I expect my delivery?\\\",\\\"expected\\\":\\\"delivery_issue\\\"}\\n{\\\"input\\\":\\\"Only part of my shipment arrived.\\\",\\\"expected\\\":\\\"delivery_issue\\\"}\\n{\\\"input\\\":\\\"My pickup order is not ready.\\\",\\\"expected\\\":\\\"delivery_issue\\\"}\",\"family\":\"classification\"}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
url = f"https://run.huggingbay.xyz/v1/pin/measured"
headers = {'Content-Type': 'application/json'}
payload = {'task': 'Developer sample only: classify support tickets. Caller-supplied rows are not production evidence, and this example claims no measured result.', 'paste': '{"input":"I cannot log into my account.","expected":"access_issue"}\n{"input":"The password reset link has expired.","expected":"access_issue"}\n{"input":"My account is locked after too many attempts.","expected":"access_issue"}\n{"input":"I need to change the email address on my account.","expected":"access_issue"}\n{"input":"The sign-in code never arrived.","expected":"access_issue"}\n{"input":"I cannot update my password.","expected":"access_issue"}\n{"input":"Two-factor authentication is blocking my login.","expected":"access_issue"}\n{"input":"The invitation link says I do not have access.","expected":"access_issue"}\n{"input":"I cannot open the account dashboard.","expected":"access_issue"}\n{"input":"Login keeps sending me back to the sign-in page.","expected":"access_issue"}\n{"input":"Please refund this invoice.","expected":"billing_issue"}\n{"input":"I was charged twice for the same order.","expected":"billing_issue"}\n{"input":"Where can I update my payment method?","expected":"billing_issue"}\n{"input":"The amount on my invoice is incorrect.","expected":"billing_issue"}\n{"input":"I want to cancel my subscription.","expected":"billing_issue"}\n{"input":"Please send me a receipt for my payment.","expected":"billing_issue"}\n{"input":"My card was declined at checkout.","expected":"billing_issue"}\n{"input":"I do not recognize this charge.","expected":"billing_issue"}\n{"input":"Can you update the billing address on my account?","expected":"billing_issue"}\n{"input":"What is the status of my refund?","expected":"billing_issue"}\n{"input":"I was charged for a renewal I did not expect.","expected":"billing_issue"}\n{"input":"How do I change to a different pricing plan?","expected":"billing_issue"}\n{"input":"My payment has been pending since yesterday.","expected":"billing_issue"}\n{"input":"My shipment is late and has not arrived.","expected":"delivery_issue"}\n{"input":"The package was marked delivered but is missing.","expected":"delivery_issue"}\n{"input":"I need to change the delivery address.","expected":"delivery_issue"}\n{"input":"The tracking information has not updated.","expected":"delivery_issue"}\n{"input":"The order arrived with the wrong item.","expected":"delivery_issue"}\n{"input":"The parcel arrived damaged.","expected":"delivery_issue"}\n{"input":"When should I expect my delivery?","expected":"delivery_issue"}\n{"input":"Only part of my shipment arrived.","expected":"delivery_issue"}\n{"input":"My pickup order is not ready.","expected":"delivery_issue"}', 'family': 'classification'}
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/pin/measured`;
const headers = {};
headers["Content-Type"] = "application/json";
const payload = {
  "task": "Developer sample only: classify support tickets. Caller-supplied rows are not production evidence, and this example claims no measured result.",
  "paste": "{\"input\":\"I cannot log into my account.\",\"expected\":\"access_issue\"}\n{\"input\":\"The password reset link has expired.\",\"expected\":\"access_issue\"}\n{\"input\":\"My account is locked after too many attempts.\",\"expected\":\"access_issue\"}\n{\"input\":\"I need to change the email address on my account.\",\"expected\":\"access_issue\"}\n{\"input\":\"The sign-in code never arrived.\",\"expected\":\"access_issue\"}\n{\"input\":\"I cannot update my password.\",\"expected\":\"access_issue\"}\n{\"input\":\"Two-factor authentication is blocking my login.\",\"expected\":\"access_issue\"}\n{\"input\":\"The invitation link says I do not have access.\",\"expected\":\"access_issue\"}\n{\"input\":\"I cannot open the account dashboard.\",\"expected\":\"access_issue\"}\n{\"input\":\"Login keeps sending me back to the sign-in page.\",\"expected\":\"access_issue\"}\n{\"input\":\"Please refund this invoice.\",\"expected\":\"billing_issue\"}\n{\"input\":\"I was charged twice for the same order.\",\"expected\":\"billing_issue\"}\n{\"input\":\"Where can I update my payment method?\",\"expected\":\"billing_issue\"}\n{\"input\":\"The amount on my invoice is incorrect.\",\"expected\":\"billing_issue\"}\n{\"input\":\"I want to cancel my subscription.\",\"expected\":\"billing_issue\"}\n{\"input\":\"Please send me a receipt for my payment.\",\"expected\":\"billing_issue\"}\n{\"input\":\"My card was declined at checkout.\",\"expected\":\"billing_issue\"}\n{\"input\":\"I do not recognize this charge.\",\"expected\":\"billing_issue\"}\n{\"input\":\"Can you update the billing address on my account?\",\"expected\":\"billing_issue\"}\n{\"input\":\"What is the status of my refund?\",\"expected\":\"billing_issue\"}\n{\"input\":\"I was charged for a renewal I did not expect.\",\"expected\":\"billing_issue\"}\n{\"input\":\"How do I change to a different pricing plan?\",\"expected\":\"billing_issue\"}\n{\"input\":\"My payment has been pending since yesterday.\",\"expected\":\"billing_issue\"}\n{\"input\":\"My shipment is late and has not arrived.\",\"expected\":\"delivery_issue\"}\n{\"input\":\"The package was marked delivered but is missing.\",\"expected\":\"delivery_issue\"}\n{\"input\":\"I need to change the delivery address.\",\"expected\":\"delivery_issue\"}\n{\"input\":\"The tracking information has not updated.\",\"expected\":\"delivery_issue\"}\n{\"input\":\"The order arrived with the wrong item.\",\"expected\":\"delivery_issue\"}\n{\"input\":\"The parcel arrived damaged.\",\"expected\":\"delivery_issue\"}\n{\"input\":\"When should I expect my delivery?\",\"expected\":\"delivery_issue\"}\n{\"input\":\"Only part of my shipment arrived.\",\"expected\":\"delivery_issue\"}\n{\"input\":\"My pickup order is not ready.\",\"expected\":\"delivery_issue\"}",
  "family": "classification"
};
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());

GET/v1/pins

List Pin Catalog Route

Public — No credential is required.

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/pins"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
url = f"https://run.huggingbay.xyz/v1/pins"
headers = {}
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/pins`;
const headers = {};
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/prove

Prove Route

Public — No credential is required.

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/prove" \
  -H 'Content-Type: application/json' \
  --data "{\"task\":\"Classify support messages by urgency\",\"paste\":\"{\\\"input\\\":\\\"Refund requested\\\",\\\"expected\\\":\\\"billing\\\"}\\n{\\\"input\\\":\\\"Password reset\\\",\\\"expected\\\":\\\"access\\\"}\",\"incumbent_model\":\"org/incumbent-model\"}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
url = f"https://run.huggingbay.xyz/v1/prove"
headers = {'Content-Type': 'application/json'}
payload = {'task': 'Classify support messages by urgency', 'paste': '{"input":"Refund requested","expected":"billing"}\n{"input":"Password reset","expected":"access"}', 'incumbent_model': 'org/incumbent-model'}
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/prove`;
const headers = {};
headers["Content-Type"] = "application/json";
const payload = {
  "task": "Classify support messages by urgency",
  "paste": "{\"input\":\"Refund requested\",\"expected\":\"billing\"}\n{\"input\":\"Password reset\",\"expected\":\"access\"}",
  "incumbent_model": "org/incumbent-model"
};
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());

GET/v1/provenance/keys

Provenance Keys Route

Public — No credential is required.

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/provenance/keys"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
url = f"https://run.huggingbay.xyz/v1/provenance/keys"
headers = {}
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/provenance/keys`;
const headers = {};
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/request_specialist

Request Specialist Route

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/request_specialist" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"task\":\"English semantic search over support articles\",\"kind\":\"embedding\",\"n_candidates\":3}"

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/request_specialist"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'task': 'English semantic search over support articles', 'kind': 'embedding', 'n_candidates': 3}
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/request_specialist`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "task": "English semantic search over support articles",
  "kind": "embedding",
  "n_candidates": 3
};
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());

POST/v1/route

Route Endpoint

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/route" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"kind\":\"embedding\",\"input\":\"A short document for semantic search\",\"serve\":false,\"prefer_warm\":true}"

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/route"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'kind': 'embedding', 'input': 'A short document for semantic search', 'serve': False, 'prefer_warm': True}
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/route`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "kind": "embedding",
  "input": "A short document for semantic search",
  "serve": false,
  "prefer_warm": true
};
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());

POST/v1/route/run

Run Pinned Route

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/route/run" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"route_id\":\"route_<32_hex_route_id>\",\"input\":{\"text\":\"Refund requested\"},\"max_price_usd\":0,\"idempotency_key\":\"developers-portal-route-retry-v1\"}"

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/route/run"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'route_id': 'route_<32_hex_route_id>', 'input': {'text': 'Refund requested'}, 'max_price_usd': 0, 'idempotency_key': 'developers-portal-route-retry-v1'}
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/route/run`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "route_id": "route_<32_hex_route_id>",
  "input": {
    "text": "Refund requested"
  },
  "max_price_usd": 0,
  "idempotency_key": "developers-portal-route-retry-v1"
};
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());

POST/v1/run/{pin_id}

Run Pin Http

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/run/${PIN_ID:-guard}" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"input\":{\"text\":\"Refund requested\"},\"max_price_usd\":0,\"idempotency_key\":\"developers-portal-pin-retry-v1\"}"

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/run/{env('PIN_ID', 'guard')}"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'input': {'text': 'Refund requested'}, 'max_price_usd': 0, 'idempotency_key': 'developers-portal-pin-retry-v1'}
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/run/${env("PIN_ID", "guard")}`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "input": {
    "text": "Refund requested"
  },
  "max_price_usd": 0,
  "idempotency_key": "developers-portal-pin-retry-v1"
};
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());

POST/v1/solve

Solve Task Route

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/solve" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"task_description\":\"Classify customer feedback by sentiment\",\"input\":\"The checkout was fast and helpful.\"}"

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/solve"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'task_description': 'Classify customer feedback by sentiment', 'input': 'The checkout was fast and helpful.'}
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/solve`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "task_description": "Classify customer feedback by sentiment",
  "input": "The checkout was fast and helpful."
};
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());

POST/v1/speed-test

Speed Test Route

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/speed-test" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/speed-test"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("POST", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/speed-test`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "POST", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

Tasks, policies & receipts

10 operations

Quote, execute, verify, and manage recurring task controls.

Browse 10 operations

POST/v1/task/approvalTEST-MODE SHAPE

Task Owner Approval Post

Owner management key — Operator-attested billing:write key; test-mode request only.

billing:write

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/task/approval" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_TEST_MANAGEMENT_KEY:?set BAY_RUN_TEST_MANAGEMENT_KEY}" \
  --data "{\"quote_id\":\"${QUOTE_ID:-quote_developers_portal_test}\",\"hard_max_price_usd\":0.01,\"idempotency_key\":\"developers-portal-approval-test-v1\",\"expires_in_seconds\":300}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_TEST_MANAGEMENT_KEY"]
url = f"https://run.huggingbay.xyz/v1/task/approval"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'quote_id': env("QUOTE_ID", "quote_developers_portal_test"), 'hard_max_price_usd': 0.01, 'idempotency_key': 'developers-portal-approval-test-v1', 'expires_in_seconds': 300}
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/task/approval`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_TEST_MANAGEMENT_KEY}`;
const payload = {
  "quote_id": env("QUOTE_ID", "quote_developers_portal_test"),
  "hard_max_price_usd": 0.01,
  "idempotency_key": "developers-portal-approval-test-v1",
  "expires_in_seconds": 300
};
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());

POST/v1/task/feedback

Task Feedback Route

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/task/feedback" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"execution_id\":\"${EXECUTION_ID:-exec_developers_portal_test}\",\"outcome\":\"accepted\",\"rating\":5,\"reason_code\":\"developer_portal_example\"}"

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/task/feedback"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'execution_id': env("EXECUTION_ID", "exec_developers_portal_test"), 'outcome': 'accepted', 'rating': 5, 'reason_code': 'developer_portal_example'}
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/task/feedback`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "execution_id": env("EXECUTION_ID", "exec_developers_portal_test"),
  "outcome": "accepted",
  "rating": 5,
  "reason_code": "developer_portal_example"
};
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());

GET/v1/task/policy

Task Spending Policy Get

Developer key — Required scopes: billing:read.

billing:read

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/task/policy?environment=dev" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/task/policy?environment=dev"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/task/policy?environment=dev`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

PUT/v1/task/policyTEST-MODE SHAPE

Task Spending Policy Put

Owner management key — Operator-attested billing:write key; test-mode request only.

billing:write

curl --fail-with-body --silent --show-error -X PUT \
  "https://run.huggingbay.xyz/v1/task/policy" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_TEST_MANAGEMENT_KEY:?set BAY_RUN_TEST_MANAGEMENT_KEY}" \
  --data "{\"environment\":\"dev\",\"per_call_max_usd\":0.01,\"daily_limit_usd\":1,\"active\":true}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_TEST_MANAGEMENT_KEY"]
url = f"https://run.huggingbay.xyz/v1/task/policy"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'environment': 'dev', 'per_call_max_usd': 0.01, 'daily_limit_usd': 1, 'active': True}
response = requests.request("PUT", 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/task/policy`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_TEST_MANAGEMENT_KEY}`;
const payload = {
  "environment": "dev",
  "per_call_max_usd": 0.01,
  "daily_limit_usd": 1,
  "active": true
};
const response = await fetch(url, { method: "PUT", headers, body: JSON.stringify(payload) });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

GET/v1/task/profiles/{profile_id}

Task Profile Route

Developer key — Required scopes: inference:invoke, task_profile:owner_write.

inference:invoketask_profile:owner_write

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/task/profiles/${PROFILE_ID:-profile_developers_portal_test}" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/task/profiles/{env('PROFILE_ID', 'profile_developers_portal_test')}"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/task/profiles/${env("PROFILE_ID", "profile_developers_portal_test")}`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

DELETE/v1/task/profiles/{profile_id}

Task Profile Delete Route

Developer key — Required scopes: data:delete.

data:delete

curl --fail-with-body --silent --show-error -X DELETE \
  "https://run.huggingbay.xyz/v1/task/profiles/${PROFILE_ID:-profile_developers_portal_test}" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/task/profiles/{env('PROFILE_ID', 'profile_developers_portal_test')}"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("DELETE", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/task/profiles/${env("PROFILE_ID", "profile_developers_portal_test")}`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "DELETE", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

PUT/v1/task/profiles/{profile_id}/learning

Task Profile Learning Route

Developer key — Required scopes: task_profile:owner_write.

task_profile:owner_write

curl --fail-with-body --silent --show-error -X PUT \
  "https://run.huggingbay.xyz/v1/task/profiles/${PROFILE_ID:-profile_developers_portal_test}/learning" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"enabled\":false,\"auto_record_platform_outcomes\":false,\"route_change_mode\":\"propose\",\"min_observations\":10,\"min_failures\":3}"

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/task/profiles/{env('PROFILE_ID', 'profile_developers_portal_test')}/learning"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'enabled': False, 'auto_record_platform_outcomes': False, 'route_change_mode': 'propose', 'min_observations': 10, 'min_failures': 3}
response = requests.request("PUT", 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/task/profiles/${env("PROFILE_ID", "profile_developers_portal_test")}/learning`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "enabled": false,
  "auto_record_platform_outcomes": false,
  "route_change_mode": "propose",
  "min_observations": 10,
  "min_failures": 3
};
const response = await fetch(url, { method: "PUT", headers, body: JSON.stringify(payload) });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/task/quote

Task Quote Route

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/task/quote" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"task_description\":\"Classify customer feedback by sentiment\",\"input\":\"The checkout was fast and helpful.\",\"max_price_usd\":0.01}"

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/task/quote"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'task_description': 'Classify customer feedback by sentiment', 'input': 'The checkout was fast and helpful.', 'max_price_usd': 0.01}
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/task/quote`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "task_description": "Classify customer feedback by sentiment",
  "input": "The checkout was fast and helpful.",
  "max_price_usd": 0.01
};
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());

POST/v1/task/run

Task Run Route

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/task/run" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"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 login link keeps expiring.\"},\"max_price_usd\":0.01,\"idempotency_key\":\"${BAY_RUN_EXECUTION_IDEMPOTENCY_KEY:-developers-portal-run-v1}\",\"payment_mode\":\"demo\"}"

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/task/run"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'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 login link keeps expiring.'}, 'max_price_usd': 0.01, 'idempotency_key': env("BAY_RUN_EXECUTION_IDEMPOTENCY_KEY", "developers-portal-run-v1"), 'payment_mode': 'demo'}
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/task/run`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "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 login link keeps expiring."
  },
  "max_price_usd": 0.01,
  "idempotency_key": env("BAY_RUN_EXECUTION_IDEMPOTENCY_KEY", "developers-portal-run-v1"),
  "payment_mode": "demo"
};
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());

POST/v1/task/verify

Task Verify Route

Developer key — Required scopes: provenance:verify.

provenance:verify

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/task/verify" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"execution_id\":\"${EXECUTION_ID:-exec_developers_portal_test}\"}"

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/task/verify"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'execution_id': env("EXECUTION_ID", "exec_developers_portal_test")}
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/task/verify`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "execution_id": env("EXECUTION_ID", "exec_developers_portal_test")
};
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());

Jobs & callbacks

11 operations

Durable bounded batches and signed callback delivery.

Browse 11 operations

GET/v1/job-callbacks

List Job Callbacks Route

Developer key — Required scopes: jobs:read.

jobs:read

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/job-callbacks" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/job-callbacks"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/job-callbacks`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/job-callbacks

Register Job Callback Route

Developer key — Required scopes: jobs:write.

jobs:write

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/job-callbacks" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"url\":\"https://example.com/bay-run-developers-portal-test\",\"secret\":\"developers-portal-test-secret-0001\"}"

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/job-callbacks"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'url': 'https://example.com/bay-run-developers-portal-test', 'secret': 'developers-portal-test-secret-0001'}
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/job-callbacks`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "url": "https://example.com/bay-run-developers-portal-test",
  "secret": "developers-portal-test-secret-0001"
};
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());

GET/v1/job-callbacks/{callback_id}

Get Job Callback Registration Route

Developer key — Required scopes: jobs:read.

jobs:read

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/job-callbacks/${CALLBACK_ID:-00000000-0000-4000-8000-000000000000}" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/job-callbacks/{env('CALLBACK_ID', '00000000-0000-4000-8000-000000000000')}"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/job-callbacks/${env("CALLBACK_ID", "00000000-0000-4000-8000-000000000000")}`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

DELETE/v1/job-callbacks/{callback_id}

Revoke Job Callback Route

Developer key — Required scopes: jobs:write.

jobs:write

curl --fail-with-body --silent --show-error -X DELETE \
  "https://run.huggingbay.xyz/v1/job-callbacks/${CALLBACK_ID:-00000000-0000-4000-8000-000000000000}" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/job-callbacks/{env('CALLBACK_ID', '00000000-0000-4000-8000-000000000000')}"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("DELETE", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/job-callbacks/${env("CALLBACK_ID", "00000000-0000-4000-8000-000000000000")}`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "DELETE", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/jobs

Submit Job Route

Developer key — Required scopes: jobs:write.

jobs:write

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/jobs" \
  -H 'Idempotency-Key: developers-portal-job-v1' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"items\":[{\"id\":\"calculate-1\",\"operation\":\"calculate\",\"arguments\":{\"expression\":\"8 * 9\"}}]}"

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/jobs"
headers = {'Idempotency-Key': 'developers-portal-job-v1', 'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'items': [{'id': 'calculate-1', 'operation': 'calculate', 'arguments': {'expression': '8 * 9'}}]}
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/jobs`;
const headers = {};
headers["Idempotency-Key"] = "developers-portal-job-v1";
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "items": [
    {
      "id": "calculate-1",
      "operation": "calculate",
      "arguments": {
        "expression": "8 * 9"
      }
    }
  ]
};
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());

GET/v1/jobs/{job_id}

Get Job Route

Developer key — Required scopes: jobs:read.

jobs:read

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/jobs/${JOB_ID:-00000000-0000-4000-8000-000000000000}" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/jobs/{env('JOB_ID', '00000000-0000-4000-8000-000000000000')}"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/jobs/${env("JOB_ID", "00000000-0000-4000-8000-000000000000")}`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

GET/v1/jobs/{job_id}/callback

Get Job Callback Route

Developer key — Required scopes: jobs:read.

jobs:read

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/jobs/${JOB_ID:-00000000-0000-4000-8000-000000000000}/callback" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/jobs/{env('JOB_ID', '00000000-0000-4000-8000-000000000000')}/callback"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/jobs/${env("JOB_ID", "00000000-0000-4000-8000-000000000000")}/callback`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/jobs/{job_id}/callback/abandon

Abandon Job Callback Route

Developer key — Required scopes: jobs:write.

jobs:write

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/jobs/${JOB_ID:-00000000-0000-4000-8000-000000000000}/callback/abandon" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/jobs/{env('JOB_ID', '00000000-0000-4000-8000-000000000000')}/callback/abandon"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("POST", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/jobs/${env("JOB_ID", "00000000-0000-4000-8000-000000000000")}/callback/abandon`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "POST", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/jobs/{job_id}/callback/retry

Retry Job Callback Route

Developer key — Required scopes: jobs:write.

jobs:write

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/jobs/${JOB_ID:-00000000-0000-4000-8000-000000000000}/callback/retry" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/jobs/{env('JOB_ID', '00000000-0000-4000-8000-000000000000')}/callback/retry"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("POST", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/jobs/${env("JOB_ID", "00000000-0000-4000-8000-000000000000")}/callback/retry`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "POST", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/jobs/{job_id}/cancel

Cancel Job Route

Developer key — Required scopes: jobs:write.

jobs:write

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/jobs/${JOB_ID:-00000000-0000-4000-8000-000000000000}/cancel" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/jobs/{env('JOB_ID', '00000000-0000-4000-8000-000000000000')}/cancel"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("POST", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/jobs/${env("JOB_ID", "00000000-0000-4000-8000-000000000000")}/cancel`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "POST", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

GET/v1/jobs/{job_id}/result

Get Job Result Route

Developer key — Required scopes: jobs:read.

jobs:read

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/jobs/${JOB_ID:-00000000-0000-4000-8000-000000000000}/result" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/jobs/{env('JOB_ID', '00000000-0000-4000-8000-000000000000')}/result"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/jobs/${env("JOB_ID", "00000000-0000-4000-8000-000000000000")}/result`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

Catalog requests & radar

6 operations

Request candidates and inspect principal-scoped status.

Browse 6 operations

POST/v1/feature-requests

Create Feature Catalog Request

Developer key — Required scopes: requests:write.

requests:write

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/feature-requests" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"title\":\"Stable SDK response examples\",\"description\":\"Publish bounded response examples for developer contract tests.\",\"category\":\"api\"}"

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/feature-requests"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'title': 'Stable SDK response examples', 'description': 'Publish bounded response examples for developer contract tests.', 'category': 'api'}
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/feature-requests`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "title": "Stable SDK response examples",
  "description": "Publish bounded response examples for developer contract tests.",
  "category": "api"
};
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());

POST/v1/mirror-requests

Create Mirror Catalog Request

Developer key — Required scopes: requests:write.

requests:write

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/mirror-requests" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"artifact_id\":\"developers-portal-smoke-artifact\",\"use_case\":\"Documentation request-shape verification\",\"target_tool\":\"developer-portal\"}"

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/mirror-requests"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'artifact_id': 'developers-portal-smoke-artifact', 'use_case': 'Documentation request-shape verification', 'target_tool': 'developer-portal'}
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/mirror-requests`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "artifact_id": "developers-portal-smoke-artifact",
  "use_case": "Documentation request-shape verification",
  "target_tool": "developer-portal"
};
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());

GET/v1/open-source-radar

Open Source Radar Route

Developer key — Required scopes: requests:read.

requests:read

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/open-source-radar?limit=5" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/open-source-radar?limit=5"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/open-source-radar?limit=5`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

GET/v1/request-status

List Catalog Request Status

Developer key — Required scopes: requests:read.

requests:read

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/request-status?limit=10" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/request-status?limit=10"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/request-status?limit=10`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

GET/v1/request-status/{request_id}

Get Catalog Request Status

Developer key — Required scopes: requests:read.

requests:read

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/request-status/${REQUEST_ID:-brr_0000000000000000}" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/request-status/{env('REQUEST_ID', 'brr_0000000000000000')}"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/request-status/${env("REQUEST_ID", "brr_0000000000000000")}`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/source-requests

Create Source Catalog Request

Developer key — Required scopes: requests:write.

requests:write

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/source-requests" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"source\":\"huggingface\",\"repo\":\"BAAI/bge-small-en-v1.5\",\"repo_type\":\"model\",\"use_case\":\"Developer portal example\"}"

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/source-requests"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'source': 'huggingface', 'repo': 'BAAI/bge-small-en-v1.5', 'repo_type': 'model', 'use_case': 'Developer portal example'}
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/source-requests`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "source": "huggingface",
  "repo": "BAAI/bge-small-en-v1.5",
  "repo_type": "model",
  "use_case": "Developer portal example"
};
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());

Developer credentials

5 operations

Create, rotate, revoke, and audit scoped developer keys.

Browse 5 operations

GET/v1/developer/credentials

List Developer Credentials

Confidential OAuth — Signed access token from a client_secret_post client.

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/developer/credentials?limit=10" \
  -H "Authorization: Bearer ${BAY_RUN_OAUTH_TOKEN:?set BAY_RUN_OAUTH_TOKEN}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_OAUTH_TOKEN"]
url = f"https://run.huggingbay.xyz/v1/developer/credentials?limit=10"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/developer/credentials?limit=10`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_OAUTH_TOKEN}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/developer/credentials

Create Developer Credential

Confidential OAuth — Signed access token from a client_secret_post client.

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/developer/credentials" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_OAUTH_TOKEN:?set BAY_RUN_OAUTH_TOKEN}" \
  --data "{\"name\":\"developers-portal-live-smoke\",\"scopes\":[\"models:read\"]}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_OAUTH_TOKEN"]
url = f"https://run.huggingbay.xyz/v1/developer/credentials"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'name': 'developers-portal-live-smoke', 'scopes': ['models:read']}
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/developer/credentials`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_OAUTH_TOKEN}`;
const payload = {
  "name": "developers-portal-live-smoke",
  "scopes": [
    "models:read"
  ]
};
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());

DELETE/v1/developer/credentials/{credential_id}

Revoke Developer Credential

Confidential OAuth — Signed access token from a client_secret_post client.

curl --fail-with-body --silent --show-error -X DELETE \
  "https://run.huggingbay.xyz/v1/developer/credentials/${CREDENTIAL_ID:-brc_00000000000000000000000000000000}" \
  -H "Authorization: Bearer ${BAY_RUN_OAUTH_TOKEN:?set BAY_RUN_OAUTH_TOKEN}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_OAUTH_TOKEN"]
url = f"https://run.huggingbay.xyz/v1/developer/credentials/{env('CREDENTIAL_ID', 'brc_00000000000000000000000000000000')}"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("DELETE", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/developer/credentials/${env("CREDENTIAL_ID", "brc_00000000000000000000000000000000")}`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_OAUTH_TOKEN}`;
const response = await fetch(url, { method: "DELETE", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

GET/v1/developer/credentials/{credential_id}/receipts

List Developer Credential Receipts

Confidential OAuth — Signed access token from a client_secret_post client.

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/developer/credentials/${CREDENTIAL_ID:-brc_00000000000000000000000000000000}/receipts?limit=10" \
  -H "Authorization: Bearer ${BAY_RUN_OAUTH_TOKEN:?set BAY_RUN_OAUTH_TOKEN}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_OAUTH_TOKEN"]
url = f"https://run.huggingbay.xyz/v1/developer/credentials/{env('CREDENTIAL_ID', 'brc_00000000000000000000000000000000')}/receipts?limit=10"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/developer/credentials/${env("CREDENTIAL_ID", "brc_00000000000000000000000000000000")}/receipts?limit=10`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_OAUTH_TOKEN}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/developer/credentials/{credential_id}/rotate

Rotate Developer Credential

Confidential OAuth — Signed access token from a client_secret_post client.

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/developer/credentials/${CREDENTIAL_ID:-brc_00000000000000000000000000000000}/rotate" \
  -H "Authorization: Bearer ${BAY_RUN_OAUTH_TOKEN:?set BAY_RUN_OAUTH_TOKEN}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_OAUTH_TOKEN"]
url = f"https://run.huggingbay.xyz/v1/developer/credentials/{env('CREDENTIAL_ID', 'brc_00000000000000000000000000000000')}/rotate"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("POST", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/developer/credentials/${env("CREDENTIAL_ID", "brc_00000000000000000000000000000000")}/rotate`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_OAUTH_TOKEN}`;
const response = await fetch(url, { method: "POST", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

Durable memory

10 operations

Owner-authorized private memory lifecycle and portable context packs.

Browse 10 operations

GET/v1/memory

Memory Read

Developer key — Required scopes: memory:read.

memory:read

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/memory?namespace=developers-portal-test&limit=10" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/memory?namespace=developers-portal-test&limit=10"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/memory?namespace=developers-portal-test&limit=10`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/memory

Memory Write

Developer key — Required scopes: memory:write.

memory:write

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/memory" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"namespace\":\"developers-portal-test\",\"key\":\"last_example\",\"value\":{\"route\":\"developers\"},\"ttl\":300}"

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/memory"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'namespace': 'developers-portal-test', 'key': 'last_example', 'value': {'route': 'developers'}, 'ttl': 300}
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/memory`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "namespace": "developers-portal-test",
  "key": "last_example",
  "value": {
    "route": "developers"
  },
  "ttl": 300
};
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());

PATCH/v1/memory

Memory Set Ttl

Developer key — Required scopes: memory:write.

memory:write

curl --fail-with-body --silent --show-error -X PATCH \
  "https://run.huggingbay.xyz/v1/memory" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"namespace\":\"developers-portal-test\",\"key\":\"last_example\",\"ttl\":600}"

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/memory"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'namespace': 'developers-portal-test', 'key': 'last_example', 'ttl': 600}
response = requests.request("PATCH", 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/memory`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "namespace": "developers-portal-test",
  "key": "last_example",
  "ttl": 600
};
const response = await fetch(url, { method: "PATCH", headers, body: JSON.stringify(payload) });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

DELETE/v1/memory

Memory Delete

Developer key — Required scopes: data:delete.

data:delete

curl --fail-with-body --silent --show-error -X DELETE \
  "https://run.huggingbay.xyz/v1/memory?namespace=developers-portal-test&key=last_example" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/memory?namespace=developers-portal-test&key=last_example"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("DELETE", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/memory?namespace=developers-portal-test&key=last_example`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "DELETE", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/memory/context

Memory Context Route

Developer key — Required scopes: memory:read, memory:write.

memory:readmemory:write

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/memory/context" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"namespace\":\"developers-portal-test\",\"updates\":{\"last_example\":{\"route\":\"developers\"}},\"ttl\":300}"

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/memory/context"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'namespace': 'developers-portal-test', 'updates': {'last_example': {'route': 'developers'}}, 'ttl': 300}
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/memory/context`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "namespace": "developers-portal-test",
  "updates": {
    "last_example": {
      "route": "developers"
    }
  },
  "ttl": 300
};
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());

GET/v1/memory/context-pack

Memory Context Pack Export

Developer key — Required scopes: memory:read.

memory:read

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/memory/context-pack?namespace=developers-portal-test&limit=10" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/memory/context-pack?namespace=developers-portal-test&limit=10"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/memory/context-pack?namespace=developers-portal-test&limit=10`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/memory/context-pack

Memory Context Pack Import

Developer key — Required scopes: memory:write.

memory:write

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/memory/context-pack" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"pack\":{\"schema\":\"bay-run.memory-context-pack.v1\",\"version\":1,\"items\":[]},\"namespace\":\"developers-portal-test\"}"

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/memory/context-pack"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'pack': {'schema': 'bay-run.memory-context-pack.v1', 'version': 1, 'items': []}, 'namespace': 'developers-portal-test'}
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/memory/context-pack`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "pack": {
    "schema": "bay-run.memory-context-pack.v1",
    "version": 1,
    "items": []
  },
  "namespace": "developers-portal-test"
};
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());

GET/v1/memory/export

Memory Export

Developer key — Required scopes: memory:read.

memory:read

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/memory/export?namespace=developers-portal-test&limit=10" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/memory/export?namespace=developers-portal-test&limit=10"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/memory/export?namespace=developers-portal-test&limit=10`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

PATCH/v1/memory/importance

Memory Set Importance

Developer key — Required scopes: memory:write.

memory:write

curl --fail-with-body --silent --show-error -X PATCH \
  "https://run.huggingbay.xyz/v1/memory/importance" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"namespace\":\"developers-portal-test\",\"key\":\"last_example\",\"importance\":80}"

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/memory/importance"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'namespace': 'developers-portal-test', 'key': 'last_example', 'importance': 80}
response = requests.request("PATCH", 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/memory/importance`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "namespace": "developers-portal-test",
  "key": "last_example",
  "importance": 80
};
const response = await fetch(url, { method: "PATCH", headers, body: JSON.stringify(payload) });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/memory/search

Memory Search Private Body

Developer key — Required scopes: memory:read.

memory:read

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/memory/search" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"query\":\"developer route\",\"namespace\":\"developers-portal-test\",\"limit\":10,\"semantic\":false}"

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/memory/search"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'query': 'developer route', 'namespace': 'developers-portal-test', 'limit': 10, 'semantic': False}
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/memory/search`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "query": "developer route",
  "namespace": "developers-portal-test",
  "limit": 10,
  "semantic": false
};
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());

Usage & billing

8 operations

Usage reads, test-only payment shapes, and operator readbacks.

Browse 8 operations

GET/v1/billingOPERATOR ONLY

Billing Readback

Operator only — Platform operator credential; never place it in an agent harness.

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/billing?limit=5" \
  -H "Authorization: Bearer ${BAY_RUN_OPERATOR_TOKEN:?set BAY_RUN_OPERATOR_TOKEN}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_OPERATOR_TOKEN"]
url = f"https://run.huggingbay.xyz/v1/billing?limit=5"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/billing?limit=5`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_OPERATOR_TOKEN}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

GET/v1/billing/balance

Stripe Credit Balance

Developer key — Required scopes: billing:read.

billing:read

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/billing/balance" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/billing/balance"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/billing/balance`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/billing/stripe/checkout-sessionTEST-MODE SHAPE

Stripe Checkout Session

Owner management key — Operator-attested billing:write key; test-mode request only.

billing:write

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/billing/stripe/checkout-session" \
  -H 'Idempotency-Key: developers-portal-payment-test-v1' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_TEST_MANAGEMENT_KEY:?set BAY_RUN_TEST_MANAGEMENT_KEY}" \
  --data "{\"pack_code\":\"starter_1000\"}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_TEST_MANAGEMENT_KEY"]
url = f"https://run.huggingbay.xyz/v1/billing/stripe/checkout-session"
headers = {'Idempotency-Key': 'developers-portal-payment-test-v1', 'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'pack_code': 'starter_1000'}
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/billing/stripe/checkout-session`;
const headers = {};
headers["Idempotency-Key"] = "developers-portal-payment-test-v1";
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_TEST_MANAGEMENT_KEY}`;
const payload = {
  "pack_code": "starter_1000"
};
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());

GET/v1/billing/usage

Stripe Credit Usage

Developer key — Required scopes: billing:read.

billing:read

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/billing/usage?limit=10&format=json" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/billing/usage?limit=10&format=json"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/billing/usage?limit=10&format=json`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

POST/v1/credits/chat/completionsTEST-MODE SHAPE

Stripe Credit Chat Completions

Agent spend key — billing:spend + inference:invoke; test-mode request only.

billing:spendinference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/credits/chat/completions" \
  -H 'Idempotency-Key: developers-portal-payment-test-v1' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_TEST_SPEND_KEY:?set BAY_RUN_TEST_SPEND_KEY}" \
  --data "{\"model\":\"auto\",\"messages\":[{\"role\":\"user\",\"content\":\"Say test mode in two words.\"}],\"max_tokens\":8}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_TEST_SPEND_KEY"]
url = f"https://run.huggingbay.xyz/v1/credits/chat/completions"
headers = {'Idempotency-Key': 'developers-portal-payment-test-v1', 'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'model': 'auto', 'messages': [{'role': 'user', 'content': 'Say test mode in two words.'}], 'max_tokens': 8}
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/credits/chat/completions`;
const headers = {};
headers["Idempotency-Key"] = "developers-portal-payment-test-v1";
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_TEST_SPEND_KEY}`;
const payload = {
  "model": "auto",
  "messages": [
    {
      "role": "user",
      "content": "Say test mode in two words."
    }
  ],
  "max_tokens": 8
};
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());

POST/v1/credits/tasks/runTEST-MODE SHAPE

Stripe Credit Task Run Route

Agent spend key — billing:spend + inference:invoke; test-mode request only.

billing:spendinference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/credits/tasks/run" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_TEST_SPEND_KEY:?set BAY_RUN_TEST_SPEND_KEY}" \
  --data "{\"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-stripe-test-v1\",\"payment_mode\":\"stripe_credits\"}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_TEST_SPEND_KEY"]
url = f"https://run.huggingbay.xyz/v1/credits/tasks/run"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'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-stripe-test-v1', 'payment_mode': 'stripe_credits'}
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/credits/tasks/run`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_TEST_SPEND_KEY}`;
const payload = {
  "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-stripe-test-v1",
  "payment_mode": "stripe_credits"
};
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());

GET/v1/demandOPERATOR ONLY

Demand Readback

Operator only — Platform operator credential; never place it in an agent harness.

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/demand?limit=5" \
  -H "Authorization: Bearer ${BAY_RUN_OPERATOR_TOKEN:?set BAY_RUN_OPERATOR_TOKEN}"

import os
import requests

env = lambda name, fallback: os.environ.get(name, fallback)
token = os.environ["BAY_RUN_OPERATOR_TOKEN"]
url = f"https://run.huggingbay.xyz/v1/demand?limit=5"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/demand?limit=5`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_OPERATOR_TOKEN}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

GET/v1/usage

Usage Status

Developer key — Required scopes: billing:read.

billing:read

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1/usage" \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}"

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/usage"
headers = {}
headers["Authorization"] = f"Bearer {token}"
response = requests.request("GET", url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

const env = (name, fallback) => process.env[name] || fallback;
const url = `https://run.huggingbay.xyz/v1/usage`;
const headers = {};
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const response = await fetch(url, { method: "GET", headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

Utilities

4 operations

Deterministic calculation, JSON validation, links, and provenance.

Browse 4 operations

POST/v1/calculate

Calculate Route

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/calculate" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"expression\":\"8 * 9\"}"

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/calculate"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'expression': '8 * 9'}
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/calculate`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "expression": "8 * 9"
};
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());

POST/v1/provenance/verify

Verify Provenance Route

Developer key — Required scopes: provenance:verify.

provenance:verify

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/provenance/verify" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"receipt\":{}}"

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/provenance/verify"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'receipt': {}}
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/provenance/verify`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "receipt": {}
};
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());

POST/v1/resolve_link

Resolve Link Route

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/resolve_link" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"url\":\"https://run.huggingbay.xyz/status.json\"}"

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/resolve_link"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'url': 'https://run.huggingbay.xyz/status.json'}
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/resolve_link`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "url": "https://run.huggingbay.xyz/status.json"
};
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());

POST/v1/validate_json

Validate Json Route

Developer key — Required scopes: inference:invoke.

inference:invoke

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/validate_json" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_DEVELOPER_KEY:?set BAY_RUN_DEVELOPER_KEY}" \
  --data "{\"data\":{\"answer\":72},\"schema\":{\"type\":\"object\",\"properties\":{\"answer\":{\"type\":\"integer\"}},\"required\":[\"answer\"]}}"

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/validate_json"
headers = {'Content-Type': 'application/json'}
headers["Authorization"] = f"Bearer {token}"
payload = {'data': {'answer': 72}, 'schema': {'type': 'object', 'properties': {'answer': {'type': 'integer'}}, 'required': ['answer']}}
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/validate_json`;
const headers = {};
headers["Content-Type"] = "application/json";
headers["Authorization"] = `Bearer ${process.env.BAY_RUN_DEVELOPER_KEY}`;
const payload = {
  "data": {
    "answer": 72
  },
  "schema": {
    "type": "object",
    "properties": {
      "answer": {
        "type": "integer"
      }
    },
    "required": [
      "answer"
    ]
  }
};
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());

Open the complete machine-readable OpenAPI contract →

04 / MCP

Three focused tools: `coprocessor`, `run_pin`, `solve_task`.

Start with coprocessor for one bounded Guard-first call with optional post-SAFE reranking; it never generates or executes tools. Use run_pin as the direct alias for a matching canonical Pin, and solve_task only as the open-ended fallback.

The compact response keeps top-level action, reason, guard, rerank, evidence, and next_call; guard has pin_id,label,score,action, and rerank has pin_id,results,score_type,signal,abstention or is null. REST POST /v1/coprocessor exposes the full receipt-bound stage result, decision, decision_evidence, and receipt. MCP exposes a bounded redacted projection: source document text and raw result payloads are omitted, while bounded decision, decision_evidence, receipt, and no-spend fields remain. Signed decision/receipt metadata does not let a caller independently recompute an omitted raw-result hash from the projection. Callers read the Guard receipt at evidence.guard.receipt, and Rerank evidence may be null. Guard is English prompt-injection classification only, not universal safety; Rerank orders only supplied documents and is not a correctness verdict. Ticket call-time abstention is top label score <0.80; the separate 30-row rule is an evidence/publication gate only. Rerank returns no_signal when max relevance_score <0.05 and accepts 1-64 nonblank documents. Choose one of four mint recipes. For the anonymous mcp:demo recipe, the MCP resource is a convenience pre-binding and the same demo credential class works on public REST; confidential, billing-capable, and owner-authorized credentials must use the exact MCP resource https://run.huggingbay.xyz/mcp/. The anonymous class also works when the other public resource is selected. Discovery and tools/list are public; protected tools/call requests use a bearer.

Zero-secret demo

BAY_RUN_TOKEN=$(curl --fail-with-body -sS -X POST 'https://run.huggingbay.xyz/oauth/token' -H 'content-type: application/json' -d '{"grant_type":"urn:bay-run:grant-type:demo","scope":"mcp:demo","resource":"https://run.huggingbay.xyz/mcp/"}' | jq -er .access_token)
export BAY_RUN_TOKEN

Durable free key

BAY_RUN_TOKEN=$(curl --fail-with-body -sS -X POST 'https://run.huggingbay.xyz/v1/keys/free' | jq -er .key)
export BAY_RUN_TOKEN

Confidential client

CLIENT=$(curl --fail-with-body -sS -X POST 'https://run.huggingbay.xyz/oauth/register' \
  -H 'content-type: application/json' -d '{"token_endpoint_auth_method":"client_secret_post","client_name":"bay-run-agent"}')
CLIENT_ID=$(jq -er .client_id <<<"$CLIENT")
CLIENT_SECRET=$(jq -er .client_secret <<<"$CLIENT")
BAY_RUN_TOKEN=$(jq -n --arg id "$CLIENT_ID" --arg secret "$CLIENT_SECRET" \
  --arg resource 'https://run.huggingbay.xyz/mcp/' \
  '{grant_type:"client_credentials",client_id:$id,client_secret:$secret,scope:"mcp:demo",resource:$resource}' | \
  curl --fail-with-body -sS -X POST 'https://run.huggingbay.xyz/oauth/token' \
    -H 'content-type: application/json' --data-binary @- | jq -er .access_token)
export BAY_RUN_TOKEN

Authorization code + PKCE

REDIRECT_URI='http://127.0.0.1:8765/callback'
STATE=$(openssl rand -hex 12)
VERIFIER=$(openssl rand -base64 64 | tr '+/' '-_' | tr -d '=' | head -c 64)
CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary | \
  openssl base64 -A | tr '+/' '-_' | tr -d '=')
CLIENT=$(curl --fail-with-body -sS -X POST 'https://run.huggingbay.xyz/oauth/register' \
  -H 'content-type: application/json' -d '{"token_endpoint_auth_method":"none","redirect_uris":["http://127.0.0.1:8765/callback"],"client_name":"bay-run-native-client"}')
CLIENT_ID=$(jq -er .client_id <<<"$CLIENT")
HEADERS=$(curl --fail-with-body -sS -G 'https://run.huggingbay.xyz/oauth/authorize' \
  --dump-header - --output /dev/null \
  --data-urlencode response_type=code --data-urlencode client_id="$CLIENT_ID" \
  --data-urlencode redirect_uri="$REDIRECT_URI" --data-urlencode scope=mcp:demo \
  --data-urlencode resource='https://run.huggingbay.xyz/mcp/' --data-urlencode state="$STATE" \
  --data-urlencode code_challenge="$CHALLENGE" \
  --data-urlencode code_challenge_method=S256)
CALLBACK_URL=$(awk 'tolower($1)=="location:" {print $2}' <<<"$HEADERS" | tr -d '\r')
CODE=$(sed -E 's/.*[?&]code=([^&]+).*/\1/' <<<"$CALLBACK_URL")
test "$(sed -E 's/.*[?&]state=([^&]+).*/\1/' <<<"$CALLBACK_URL")" = "$STATE"
BAY_RUN_TOKEN=$(jq -n --arg code "$CODE" --arg verifier "$VERIFIER" \
  --arg client_id "$CLIENT_ID" --arg redirect_uri "$REDIRECT_URI" \
  --arg resource 'https://run.huggingbay.xyz/mcp/' \
  '{grant_type:"authorization_code",code:$code,code_verifier:$verifier,client_id:$client_id,redirect_uri:$redirect_uri,resource:$resource}' | \
  curl --fail-with-body -sS -X POST 'https://run.huggingbay.xyz/oauth/token' \
    -H 'content-type: application/json' --data-binary @- | jq -er .access_token)
export BAY_RUN_TOKEN

GROK CONNECTOR

Use the active coprocessor / run_pin / solve_task profile

Create a Custom MCP connector at grok.com/connectors, enter the server URL, and complete OAuth. The default tools/list surface exposes exactly these three focused tools in this order: coprocessor, run_pin, and solve_task. Start with coprocessor for one bounded Guard-first call with optional post-SAFE reranking; use run_pin for a known canonical Pin and solve_task only when no Pin fits. Advanced tools remain separately disclosed.

{
  "type": "mcp",
  "server_url": "https://run.huggingbay.xyz/mcp/",
  "server_label": "bay_run",
  "allowed_tools": [
    "coprocessor",
    "run_pin",
    "solve_task"
  ],
  "authorization": "$BAY_RUN_TOKEN"
}

Live Grok manifest → · Advanced MCP tools → · xAI Remote MCP docs →

05 / Receipts

Verify evidence without rerunning the task.

Use a stable idempotency_key only for the same principal, route, and unchanged request; a different request is an idempotency conflict, not a new execution. The receipt proves the stored execution evidence and declared commitments only. It does not prove answer correctness, 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 login link keeps expiring."},"max_price_usd":0.01,"idempotency_key":"developers-portal-receipt-walkthrough-v1"}')

# 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 .

ExecutionID, status, timestamp, input/output hashes

Routeprovider, model, latency, fallback facts

Money & policyamount, hard ceiling, quoted restrictions

06 / Runtime limits

Read from this process's live config.

Responses are authoritative: inspect RateLimit-* and Retry-After. Per-instance IP guardrails are not represented as distributed account quotas.

Tier	Limit	Window	Keying / note
Anonymous demo	60	minute	Per IP, per active instance
Anonymous demo	1500	day	Per IP, per active instance
Identified agent	120	minute	OAuth client or durable key
Identified agent	5000	day	OAuth client or durable key
Durable free key	500	tasks/day	Exact cross-instance key quota
Free-key mint	2	minute	Per IP
Free-key mint	15	day	Per IP
Bake-off	15	day	Per principal
Public trial	30	minute	Fixed/anonymous activation
Public trial	200	day	Fixed/anonymous activation
OAuth pre-auth	60	minute	Registration and token issuance per IP

07 / Data & trust

Make the service boundary explicit.

Review how Bay Run handles data, authentication, receipts, privacy, and security before connecting an agent.

Data policyRetention, training, and provider handling.Read policy ↗AssuranceAuthentication, receipts, and control boundaries.Read policy ↗PrivacyPrivacy rights and deletion policy.Read policy ↗SecuritySecurity controls and vulnerability reporting.Read policy ↗

07 / SDKs

Use raw HTTP everywhere; use compatible SDKs where they help.

OpenAI PythonOpenAI-compatible embeddings and chatOfficial docs ↗OpenAI JavaScriptOpenAI-compatible embeddings and chatOfficial docs ↗MCP PythonStreamable HTTP MCP clientsOfficial docs ↗MCP TypeScriptStreamable HTTP MCP clientsOfficial docs ↗

08 / Public examples

First-task examples.

MIT-scoped examples. The public archive contains standalone Python and TypeScript clients. Supply an authorized bearer through the BAY_RUN_TOKEN environment variable; the examples do not automatically post to a board. Their synthetic fixtures and offline checks are not proof of model quality, correctness, or live service availability.

Python examplesStandalone Python client examples in the public archive.Open artifact ↗TypeScript examplesStandalone TypeScript client examples in the public archive.Open artifact ↗Public releaseMIT release notes, source context, and archive provenance.Open artifact ↗MANIFEST.jsonArchive manifest for the published first-task bundle.Open artifact ↗SHA256SUMSChecksums for the published archive and manifest.Open artifact ↗

Run the specialist. Skip model selection.

Choose a Pin

Minimal calls

Connect / MCP

Cursor

Unlisted task

Start anonymous. Keep identity only when you need it.

Zero secret, short-lived

No email, card, or signup

Durable machine identity

Quote → run → verify, without leaving the page.

Advanced REST operations.

Service Root

Public Task Demo

Caller Identity

Create Free Key Route

Revoke Free Key Route

Serve Quickstart

Chat Completions

Classify Route

Document Extract Route

Create Embeddings

Guard Route

Pdf Extract Route

Upload and extract a bounded PDF

Policy Route

Rag Route

Rerank Route

Summarize Route

Run Bakeoff Route

Claim Public Bakeoff

Cache Status

Coprocessor Route

Discover

Evaluate

Delete Private Evaluation Namespace

Find Specialist

List Models

Request Owner Magic Link

Consume Owner Magic Link

List Owner Keys

Create Owner Key

Revoke Owner Key

List Owner Pins

Promote Owner Pin

List Owner Pin Revisions

Rollback Owner Pin

List Owner Receipts

Owner Session Info

Mint Pin Route

Mint Measured Pin Route

List Pin Catalog Route

Prove Route

Provenance Keys Route

Request Specialist Route

Route Endpoint

Run Pinned Route

Run Pin Http

Solve Task Route

Speed Test Route

Task Owner Approval Post

Task Feedback Route

Task Spending Policy Get

Task Spending Policy Put

Task Profile Route

Task Profile Delete Route

Task Profile Learning Route

Task Quote Route

Task Run Route

Task Verify Route

List Job Callbacks Route

Register Job Callback Route

Get Job Callback Registration Route

Revoke Job Callback Route

Submit Job Route

Get Job Route

Get Job Callback Route

Abandon Job Callback Route

Retry Job Callback Route

Cancel Job Route

Three focused tools: `coprocessor`, `run_pin`, `solve_task`.