Embed
Use the OpenAI-compatible /v1/embeddings shape with bge-small or model="auto".
Retrieval infrastructure first
OpenAI-compatible embeddings, ready now.
Bay Run is a free OpenAI-compatible embeddings API and model-routing service at the canonical URL https://run.huggingbay.xyz/. Send an OpenAI-format request to POST https://run.huggingbay.xyz/v1/embeddings, rerank the retrieved documents, and verify the signed receipt. The public launch tier costs USD 0.00 and requires no card.
The bake-off lab sits on top of that retrieval box. It compares only warm models in the detected family; an underfilled field returns no_specialists, and a weak field makes no best-model, badge, or author-claim offer.
Free during launch. Mint a durable email-free key with a published 500-task/day quota.
The retrieval box
Embed, rerank, and verify on one API origin.
Use the working retrieval primitives directly. No evaluation claim is required to create vectors or reorder a candidate set.
Rerank
Send a query and documents to /v1/rerank; omitted models default to the honest auto route.
Verify
Check the signed provenance receipt without claiming that integrity proves quality, truth, or model-weight identity.
The model lab on top
Labeled examples become an honest field result.
Bay Run turns specialist selection into a bounded warm-family evaluation and says when the field is too small or too weak to support a winner claim.
Label 3–10 examples
Send only a task description and string input/expected pairs. No task kind, model IDs, or evaluation schema.
Measure the eligible field
Bay Run detects one task family and scores only models in both its family map and resident warm pool.
Read the outcome honestly
Follow a ready next call after a strong field; otherwise use the weak-field evidence or no_specialists catalog suggestions.
Clear system boundary
Catalog and execution are different jobs.
The two products work together without asking an agent to understand the internal architecture.
Catalog and provenance layer
Hugging Bay catalogs specialist artifacts, mirrors eligible models, and records provenance and verification evidence.
Browse Hugging Bay when you need artifact discovery or provenance detail.
Decision, execution, and payment layer
Bay Run receives a task and constraints, selects a qualifying route, executes it, handles authorized payment, and returns a verifiable result.
Use the task contract when you need an outcome, not a list of models.
Live one-call bake-off
Describe the task. Paste labels. Get an honest field result.
This form sends exactly the public /v1/bakeoff contract. Bay Run compares only resident models in the detected family. If fewer than two qualify, it returns no_specialists with catalog suggestions and does not spend bake-off quota.
Recurring task operations
Keep the route that works.
Authenticate with a durable bearer, save a recurring task, reuse its preferred route, run bounded executions, and verify the receipt. This console uses the existing authenticated task, policy, usage, and billing routes.
One-time quotes and free execution accept a durable OAuth or appropriately scoped developer bearer. Raw-retaining profiles, labeled private evaluations, and durable memory require purpose-specific developer keys issued after operator-attested human-owner enrollment; they are never demo or default agent grants. Profile-bound delegation to an ordinary agent is not yet offered. Checkout, policy, and approval require a separate billing:write management key. Stripe agent execution uses only billing:spend + inference:invoke. These billing scopes cannot share one developer key. Never place unrelated owner credentials in an agent harness.
A confidential OAuth client establishes a durable private principal but does not prove human approval. Public demo OAuth identities are ephemeral. Owner-management and private-state keys require explicit operator-attested enrollment. Use separate credentials for raw profiles, private evaluations, durable memory, deletion, billing management, and autonomous spend. Give an agent only the scopes required by its assigned task.
Create a recurring task profile
Save the task specification and its preferred route with the existing quote contract. Raw-retaining profile creation requires the human owner's dedicated task_profile:owner_write scope. Examples are used for evaluation; the hard price and latency limits travel with the task.
Set spending boundaries
The human owner first establishes a durable private principal with a confidential OAuth client, then completes explicit operator-attested enrollment for a billing-eligible billing:write management key. That key replaces policy through /v1/task/policy. Keep OAuth and management keys out of agent harnesses; agents receive only billing:spend + inference:invoke. A developer key cannot combine the management and spend billing scopes.
{
"status": "waiting",
"next": "Authenticate, then read or save a production policy"
}
See candidate evidence
The quote response is the evaluation record: candidate evidence, expected quality, estimated latency, price, and qualifying alternatives. Values are measured only when the response says they are.
{
"status": "waiting",
"next": "Evaluate a task to compare specialists"
}
Reuse or inspect the preferred route
After a recurring quote, Bay Run returns a task profile ID. Use that ID to retrieve the saved route through the existing profile read route.
{
"status": "waiting",
"next": "Save a recurring task to receive a profile ID"
}
Run the quoted route
Execution requires the quote ID, a hard maximum at or below the quote, and an idempotency key. The result stays in the response until you leave the page.
{
"status": "waiting",
"next": "A successful run returns an execution_id"
}
Verify execution evidence
Verify the durable execution, hashes, price ceiling, route, and receipt with the existing verification endpoint.
{
"status": "waiting",
"next": "Run a task, then verify its execution ID"
}
Inspect authenticated usage
These controls call the existing usage and prepaid-credit reads. Checkout remains a POST-only API operation and is documented in OpenAPI.
{
"status": "waiting",
"next": "Authenticate, then read usage or billing"
}
Use the same operations from code
These are the live machine-readable surfaces. No dashboard-only endpoint is implied.
- OpenAPI contract
/openapi.json - MCP server card
/.well-known/mcp/server-card.json - OAuth metadata
/.well-known/oauth-authorization-server - Pricing
/.well-known/pricing - Readiness
/health
Built for agents and developers
Use the same contract over HTTP or MCP.
The OpenAI-compatible retrieval routes are the front door. The focused MCP lab adds run_bakeoff, followed by get_task_quote, run_task, and verify_result for recurring work. Advanced specialist tools remain available for explicit workflows.
Run a bake-off with no model IDs
# First lab result: one anonymous request, with no model IDs or token.
# The honest outcome may be no_specialists, a weak field, or a strong field.
curl -sS -X POST "https://run.huggingbay.xyz/v1/bakeoff" \
-H "Content-Type: application/json" \
-d '{
"task_description": "Classify support tickets as access_issue, billing_issue, delivery_issue, account_update, or fulfillment_issue",
"examples": [
{
"input": "Cannot sign in",
"expected": "access_issue"
},
{
"input": "Refund the invoice",
"expected": "billing_issue"
},
{
"input": "Shipment is late",
"expected": "delivery_issue"
},
{
"input": "Setup is complete",
"expected": "account_update"
},
{
"input": "Order is damaged",
"expected": "fulfillment_issue"
}
]
}'
# After success, mint the optional durable 500-task/day key returned in the offer.
BAY_RUN_KEY=$(curl -sS -X POST "https://run.huggingbay.xyz/v1/keys/free" | jq -r .key)Discover the same task contract
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","scope":"mcp:demo","resource":"https://run.huggingbay.xyz/mcp/"}' | jq -r .access_token)
curl -sS -X POST "https://run.huggingbay.xyz/mcp/" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {"name": "run_bakeoff", "arguments": {
"task_description": "Classify support tickets as access_issue, billing_issue, delivery_issue, account_update, or fulfillment_issue",
"examples": [
{
"input": "Cannot sign in",
"expected": "access_issue"
},
{
"input": "Refund the invoice",
"expected": "billing_issue"
},
{
"input": "Shipment is late",
"expected": "delivery_issue"
},
{
"input": "Setup is complete",
"expected": "account_update"
},
{
"input": "Order is damaged",
"expected": "fulfillment_issue"
}
]
}}
}Follow each next_call
Use the binding paths exactly as returned: raw MCP results bind through result.structuredContent; REST results bind from the top-level response.
{
"schema": "bay-run.activation-sequence.v1",
"steps": [
{
"body": {
"grant_type": "urn:bay-run:grant-type:demo",
"resource": "https://run.huggingbay.xyz/mcp/",
"scope": "mcp:demo"
},
"headers": {
"Accept": "application/json",
"Content-Type": "application/json"
},
"method": "POST",
"name": "oauth_token",
"on_success": {
"next_step": "run_bakeoff",
"transport": "mcp"
},
"path": "/oauth/token",
"save_response_field": "access_token",
"schema": "bay-run.next-call.v1",
"step": "token_mint",
"transport": "rest",
"url": "https://run.huggingbay.xyz/oauth/token"
},
{
"body": {
"id": "bay-run-bakeoff",
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"examples": [
{
"expected": "access_issue",
"input": "Cannot sign in"
},
{
"expected": "billing_issue",
"input": "Refund the invoice"
},
{
"expected": "delivery_issue",
"input": "Shipment is late"
},
{
"expected": "account_update",
"input": "Setup is complete"
},
{
"expected": "fulfillment_issue",
"input": "Order is damaged"
}
],
"task_description": "Classify support tickets by workflow"
},
"name": "run_bakeoff"
}
},
"headers": {
"Accept": "application/json",
"Authorization": "Bearer <access_token>",
"Content-Type": "application/json"
},
"method": "POST",
"name": "run_bakeoff",
"on_success": {
"bind": {
"next_call": "$response.result.structuredContent.next_call",
"public_url": "$response.result.structuredContent.public_url",
"winner": "$response.result.structuredContent.winner"
},
"next_step": "follow_response_next_call"
},
"path": "/mcp/",
"schema": "bay-run.next-call.v1",
"step": "run_bakeoff",
"transport": "mcp",
"url": "https://run.huggingbay.xyz/mcp/"
},
{
"body": {
"id": "bay-run-get-task-quote",
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"quote_ttl_seconds": 900,
"task_spec": {
"constraints": {
"max_latency_ms": 20000,
"max_price_usd": "0.01",
"minimum_quality": 0.8
},
"data_policy": {
"allowed_regions": [
"us-central1"
],
"external_apis_allowed": false,
"open_source_required": true,
"retention": "execution_metadata",
"use_for_training": false
},
"environment": "production",
"examples": [
{
"label": "access_issue",
"text": "Cannot sign in"
},
{
"label": "billing_issue",
"text": "Refund the invoice"
},
{
"label": "delivery_issue",
"text": "Shipment is late"
},
{
"label": "account_update",
"text": "Setup is complete"
},
{
"label": "fulfillment_issue",
"text": "Order is damaged"
}
],
"frequency": "one_time",
"input_schema": {
"properties": {
"text": {
"type": "string"
}
},
"required": [
"text"
],
"type": "object"
},
"kind": "classification",
"output_schema": {
"properties": {
"label": {
"type": "string"
}
},
"required": [
"label"
],
"type": "object"
},
"route_switch_policy": "approval_required",
"task": "Classify support tickets as access_issue, billing_issue, delivery_issue, account_update, or fulfillment_issue"
}
},
"name": "get_task_quote"
}
},
"headers": {
"Accept": "application/json",
"Authorization": "Bearer <access_token>",
"Content-Type": "application/json"
},
"method": "POST",
"name": "get_task_quote",
"on_success": {
"bind": {
"authorized_ceiling_usd": "$response.result.structuredContent.authorized_ceiling_usd",
"quote_id": "$response.result.structuredContent.quote_id"
},
"next_step": "run_task"
},
"path": "/mcp/",
"schema": "bay-run.next-call.v1",
"step": "get_task_quote",
"transport": "mcp",
"url": "https://run.huggingbay.xyz/mcp/"
},
{
"body": {
"id": "bay-run-run-task",
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"idempotency_key": "<unique-idempotency-key>",
"input": {
"text": "A customer cannot sign in."
},
"max_price_usd": "$response.result.structuredContent.authorized_ceiling_usd",
"payment_mode": "demo",
"quote_id": "$response.result.structuredContent.quote_id"
},
"name": "run_task"
}
},
"headers": {
"Accept": "application/json",
"Authorization": "Bearer <access_token>",
"Content-Type": "application/json"
},
"method": "POST",
"name": "run_task",
"on_success": {
"bind": {
"execution_id": "$response.result.structuredContent.execution_id"
},
"next_step": "verify_result"
},
"path": "/mcp/",
"schema": "bay-run.next-call.v1",
"step": "run_task",
"transport": "mcp",
"url": "https://run.huggingbay.xyz/mcp/"
},
{
"body": {
"id": "bay-run-verify-result",
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"execution_id": "$response.result.structuredContent.execution_id",
"output": "$response.result.structuredContent.output",
"receipt": "$response.result.structuredContent.execution_receipt"
},
"name": "verify_result"
}
},
"headers": {
"Accept": "application/json",
"Authorization": "Bearer <access_token>",
"Content-Type": "application/json"
},
"method": "POST",
"name": "verify_result",
"path": "/mcp/",
"schema": "bay-run.next-call.v1",
"step": "verify_result",
"terminal": true,
"transport": "mcp",
"url": "https://run.huggingbay.xyz/mcp/"
}
]
}Controls before convenience
The human authorizes the boundary. The agent operates inside it.
Before data is sent, the owner can inspect the processing region, external-provider rule, retention mode, spending ceiling, and evidence limits. Bay Run makes those constraints machine-readable so an agent can explain why a task is or is not suitable.
Authorize only what the task allows
- Hard max priceReject any route or fallback that exceeds the quoted absolute USD ceiling.
- Quote expiration and idempotencyPrevent stale or duplicate executions from becoming an unexpected charge.
- Payment choiceUse x402 for one-off machine payments or Stripe and prepaid credits for an account budget.
Make data handling part of the route
- Policy constraintsSpecify provider, region, external API, and retention requirements before execution.
- No training by defaultCustomer inputs are not used for training or cross-tenant learning under the published policy.
- Owner-controlled retentionDefault to no raw task retention or metadata-only receipts; durable profiles, private evaluations, and memory require operator-attested purpose-specific scopes.
- Bounded durable memoryMemory is principal-scoped, exportable, deletable, TTL-aware, and never a public OAuth grant. Automatic memory expires after the published default.
- Verifiable receiptInspect execution identity, hashes, amount, timestamp, route, and fallback information.
- No universal safety claimQuality, latency, and controls are stated precisely; the owner decides whether they satisfy a regulated or contract-restricted workload.
- OpenAI-compatible embeddings landing
- Model-lab quickstart (including weak and underfilled outcomes)
- Public bake-off field results
- Public service status
- OpenAPI specification
- llms.txt
- MCP server card
- Pricing discovery
- Data policy and deletion controls
- Assurance evidence and standards mapping
- Security reporting and limitations
- Health