Bay Run developer portal

Ship against the whole contract.

Authentication, 81 public /v1 operations, real curl/Python/JavaScript examples, MCP, receipts, runtime limits, SDKs, and payment request shapes—on one page.

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. Mint a REST-audience token:

curl -sS -X POST 'https://run.huggingbay.xyz/oauth/token' -H 'content-type: application/json' -d '{"grant_type":"urn:bay-run:grant-type: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 / Operator 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 documented routes shown below.

No request sent.

{"status":"waiting"}

03 / REST API

Every public /v1 operation.

Examples are generated from one request spec per operation and rendered in curl, Python, and JavaScript. Credential and scope badges come from OpenAPI.

81 operations81 shown

Start & identity

7 operations

Service discovery, free credentials, and caller identity.

GET/v1

Service Root

Public — No credential is required.

curl --fail-with-body --silent --show-error -X GET \
  "https://run.huggingbay.xyz/v1"
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\"}]}"
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}"
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"
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}"
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"
GET/v1/try

Try Bay Run Route

Public — No credential is required.

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

Inference & documents

9 operations

OpenAI-compatible inference and bounded document tools.

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\":\"Qwen/Qwen3-4B\",\"messages\":[{\"role\":\"user\",\"content\":\"In one sentence, why verify AI receipts?\"}],\"max_tokens\":48,\"temperature\":0}"
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}"
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}"
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.\"]}"
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}"
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'
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}"
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}"
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}"

Routing & evaluation

12 operations

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

POST/v1/bakeoff

Run Bakeoff Route

Optional bearer — Anonymous is supported; a bearer gives a stable principal and isolated quota.

curl --fail-with-body --silent --show-error -X POST \
  "https://run.huggingbay.xyz/v1/bakeoff" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${BAY_RUN_API_KEY:?set BAY_RUN_API_KEY}" \
  --data "{\"task_description\":\"Classify customer feedback by sentiment\",\"examples\":[{\"input\":\"Setup works perfectly.\",\"expected\":\"positive\"},{\"input\":\"Checkout is broken.\",\"expected\":\"negative\"},{\"input\":\"Search feels fast.\",\"expected\":\"positive\"}],\"public\":false}"
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}\"}"
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}"
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}"
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}"
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}"
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}"
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}"
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}"
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}"
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.\"}"
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}"

Tasks, policies & receipts

9 operations

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

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}"
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\"}"
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}"
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}"
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}"
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}"
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\":{\"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,\"idempotency_key\":\"${BAY_RUN_QUOTE_IDEMPOTENCY_KEY:-developers-portal-quote-v1}\"}"
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 checkout keeps rejecting my card.\"},\"max_price_usd\":0.01,\"idempotency_key\":\"${BAY_RUN_EXECUTION_IDEMPOTENCY_KEY:-developers-portal-run-v1}\",\"payment_mode\":\"demo\"}"
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}\"}"

Jobs & callbacks

11 operations

Durable bounded batches and signed callback delivery.

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}"
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\"}"
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}"
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}"
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\":\"6 * 7\"}}]}"
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}"
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}"
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}"
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}"
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}"
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}"

Catalog requests & radar

6 operations

Request candidates and inspect principal-scoped status.

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

Developer credentials

5 operations

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

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

Durable memory

10 operations

Owner-authorized private memory lifecycle and portable context packs.

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

Usage & billing

8 operations

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

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}"
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}"
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\"}"
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}"
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\":\"Qwen/Qwen3-4B\",\"messages\":[{\"role\":\"user\",\"content\":\"Say test mode in two words.\"}],\"max_tokens\":8}"
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\"}"
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}"
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}"

Utilities

4 operations

Deterministic calculation, JSON validation, links, and provenance.

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\":\"6 * 7\"}"
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\":{}}"
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\"}"
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\":42},\"schema\":{\"type\":\"object\",\"properties\":{\"answer\":{\"type\":\"integer\"}},\"required\":[\"answer\"]}}"

04 / MCP

One Streamable HTTP server, four mint recipes.

Use the MCP resource audience exactly: https://run.huggingbay.xyz/mcp/. Discovery and tools/list are public; protected tools/call requests use a bearer.

1

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
2

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
3

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
4

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

Keep Grok focused on five primary tools

Create a Custom MCP connector at grok.com/connectors, enter the server URL, and complete OAuth. For xAI Remote MCP use:

{
  "type": "mcp",
  "server_url": "https://run.huggingbay.xyz/mcp/",
  "server_label": "bay_run",
  "allowed_tools": [
    "solve_task",
    "run_bakeoff",
    "get_task_quote",
    "run_task",
    "verify_result"
  ],
  "authorization": "$BAY_RUN_TOKEN"
}

Live Grok manifest → · xAI Remote MCP docs →

05 / Receipts

Verify evidence without rerunning the task.

Integrity proves the stored commitments and execution evidence named by the receipt. It does not prove answer truth, model quality, or cryptographic model-weight identity at serve time.

# 1. Run a task and keep the complete response.
RUN=$(curl -sS -X POST "https://run.huggingbay.xyz/v1/task/run" \
  -H "Authorization: Bearer $BAY_RUN_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"task":{"task":"Classify short support messages by workflow","kind":"classification","input_schema":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]},"output_schema":{"type":"object","properties":{"label":{"type":"string"}},"required":["label"]},"examples":[{"text":"Cannot sign in","label":"access_issue"},{"text":"Refund the invoice","label":"billing_issue"},{"text":"Shipment is late","label":"delivery_issue"}],"constraints":{"minimum_quality":0.5,"max_latency_ms":20000,"max_price_usd":0.01},"data_policy":{"retention":"none","external_apis_allowed":false,"use_for_training":false},"environment":"development"},"input":{"text":"The checkout keeps rejecting my card."},"max_price_usd":0.01,"idempotency_key":"developers-portal-receipt-walkthrough-v1","payment_mode":"demo"}')

# 2. Bind the execution ID and receipt from that exact response.
VERIFY=$(jq '{execution_id:.execution_id,receipt:.execution_receipt,output:.output}' <<<"$RUN")

# 3. Verify stored execution, hashes, route, amount, and policy compliance.
curl -sS -X POST "https://run.huggingbay.xyz/v1/task/verify" \
  -H "Authorization: Bearer $BAY_RUN_API_KEY" \
  -H 'content-type: application/json' --data "$VERIFY" | jq .
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.

TierLimitWindowKeying / note
Anonymous demo60minutePer IP, per active instance
Anonymous demo1500dayPer IP, per active instance
Identified agent120minuteOAuth client or durable key
Identified agent5000dayOAuth client or durable key
Durable free key500tasks/dayExact cross-instance key quota
Free-key mint2minutePer IP
Free-key mint15dayPer IP
Bake-off15dayPer principal
Public trial30minuteFixed/anonymous activation
Public trial200dayFixed/anonymous activation
OAuth pre-auth60minuteRegistration and token issuance per IP

07 / SDKs

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

TEST MODE ONLY

No wallet signature, checkout session, charge, or settlement is created by these docs tests.

Production discovery currently describes Base mainnet. Configuration is not settlement evidence. Use a separately configured test deployment for real Stripe test-mode or Base testnet exercises.

x402 challenge shape

# REQUEST-SHAPE TEST ONLY — no PAYMENT-SIGNATURE, so no settlement occurs.
curl -i -X POST "https://run.huggingbay.xyz/x402/tasks/run" \
  -H 'content-type: application/json' \
  -d '{"task":{"task":"Classify short support messages by workflow","kind":"classification","input_schema":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]},"output_schema":{"type":"object","properties":{"label":{"type":"string"}},"required":["label"]},"examples":[{"text":"Cannot sign in","label":"access_issue"},{"text":"Refund the invoice","label":"billing_issue"},{"text":"Shipment is late","label":"delivery_issue"}],"constraints":{"minimum_quality":0.5,"max_latency_ms":20000,"max_price_usd":0.01},"data_policy":{"retention":"none","external_apis_allowed":false,"use_for_training":false},"environment":"development"},"input":{"text":"test-mode shape"},"max_price_usd":0.005,"idempotency_key":"developers-portal-x402-test-v1"}'
# Expect HTTP 402 and inspect PAYMENT-REQUIRED. Do not add a wallet signature in docs tests.
Live payment discovery →

Stripe checkout shape

# TEST-MODE SHAPE ONLY — use a test deployment + Stripe test key.
curl -i -X POST "https://run.huggingbay.xyz/v1/billing/stripe/checkout-session" \
  -H "Authorization: Bearer $BAY_RUN_TEST_MANAGEMENT_KEY" \
  -H 'Idempotency-Key: developers-portal-stripe-test-v1' \
  -H 'content-type: application/json' -d '{"pack_code":"starter_1000"}'
# Portal acceptance supplies no owner key, so production rejects this before Stripe.
Live pricing discovery →