huggingbay-xyz Bakeoff API

openapi: 3.2.0
info:
  title: Huggingbay Xyz Bakeoff API
  x-refined-note:
  - x-agent-quickstart differs across the merged source definitions and was not carried
  - x-changelog differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Bakeoff across 2 of this provider''s published API definitions: huggingbay-xyz-openapi.json, huggingbay-xyz-run-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://huggingbay.xyz
- url: https://run.huggingbay.xyz
tags:
- name: Bakeoff
paths:
  /api/v1/bakeoff:
    get:
      operationId: getBakeoffContract
      summary: Read supported bakeoff tasks, candidate call shapes, limits and score…
      security: []
      responses:
        '200':
          description: Bakeoff contract
          content:
            application/json:
              schema:
                type: object
                required:
                - schemaVersion
                - tasks
                - candidates
                - limits
                - honesty
                properties:
                  schemaVersion:
                    const: hugging-bay.bakeoff-contract.v1
                  tasks:
                    type: array
                    items:
                      type: string
                  candidates:
                    type: object
                  limits:
                    type: object
                  honesty:
                    type: string
                additionalProperties: true
          headers:
            X-HB-Backoff:
              description: Optional v1 backoff contract marker; rollout defaults off.
              schema:
                type: string
            X-HB-Admission:
              description: Optional open, busy or limited; a process-local observation, not a reservation.
              schema:
                type: string
            X-HB-Capacity:
              description: Optional process-local heavy/bytes active, limit and remaining counts plus observed epoch seconds. Cached observations may be old.
              schema:
                type: string
      x-request-example:
        method: GET
        url: https://huggingbay.xyz/api/v1/bakeoff
        headers: {}
        parameters: []
        prerequisites: []
        verification: Request template. Not a captured live response.
        curl: curl -sS 'https://huggingbay.xyz/api/v1/bakeoff'
      x-codeSamples:
      - lang: Shell
        label: curl request
        source: curl -sS 'https://huggingbay.xyz/api/v1/bakeoff'
      x-rate-limit:
        policy: '#/x-rate-limit'
        summary: Public read budgets apply by client IP and route group. This operation can have a smaller route-specific budget. Read Retry-After on 429 or retryable 503 responses.
      x-error-contract:
        schema: '#/components/schemas/ErrorEnvelope'
        note: API JSON failures use the documented response schema. Read code, message and next; retry only when the response allows it. Auth, invalid input and missing records need a caller change.
      description: 'Read supported bakeoff tasks, candidate call shapes, limits and score qualifications; does not execute.


        **Inputs.** No path or query fields are required. No request body is required.


        **Outputs.** See each status below for its media type, schema and headers. A missing record or unavailable capability is not a successful empty result.


        **Errors.** API JSON failures use the documented response schema. Read code, message and next; retry only when the response allows it. Auth, invalid input and missing records need a caller change.


        **Rate limits.** Public read budgets apply by client IP and route group. This operation can have a smaller route-specific budget. Read Retry-After on 429 or retryable 503 responses.'
      tags:
      - Bakeoff
    post:
      operationId: runSpecialistBakeoff
      summary: Score the supported Bay Run candidates on explicitly submitted examples
      security: []
      description: 'Sends examples to the separate Bay Run service. GET this path for current tasks and limits. Quality remains provisional; scores are limited to submitted rows, with errors and abstentions included. A hash may be null; a receipt is not proof of model quality. Share links contain aggregate results, not private examples. May be disabled or unavailable.


        **Inputs.** No path or query fields are required. The request body schema lists accepted fields and required values.


        **Outputs.** See each status below for its media type, schema and headers. A missing record or unavailable capability is not a successful empty result.


        **Errors.** API JSON failures use the documented response schema. Read code, message and next; retry only when the response allows it. Auth, invalid input and missing records need a caller change.


        **Rate limits.** Write and protocol operations can have separate route-specific limits. Read Retry-After and retry_after_s when present; do not infer a write allowance from the public read budget.


        **Example setup.** This example is not executed by documentation checks. Review the operation and obtain any required user consent before sending it.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - task
              - examples
              properties:
                task:
                  type: string
                  description: toxicity, sentiment, prompt_injection, tickets, rerank, embeddings, or nli; existing synonyms are also accepted. nli uses the tickets Pin, not premise/hypothesis evaluation.
                examples:
                  type: array
                  minItems: 1
                  maxItems: 50
                  description: 'Classification: {input,label}. Retrieval: {query,documents,relevant}, with 2-8 documents and zero-based relevant index or index array. Texts are limited to 2000 characters. Row aliases and rejection details remain defined by the runtime contract.'
                  items:
                    type: object
                    additionalProperties: true
                  examples:
                  - - input: Have a nice day
                      label: non_toxic
              additionalProperties: true
      responses:
        '200':
          description: Provisional results and aggregate share link
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
          headers:
            X-HB-Backoff:
              description: Optional v1 backoff contract marker; rollout defaults off.
              schema:
                type: string
            X-HB-Admission:
              description: Optional open, busy or limited; a process-local observation, not a reservation.
              schema:
                type: string
            X-HB-Capacity:
              description: Optional process-local heavy/bytes active, limit and remaining counts plus observed epoch seconds. Cached observations may be old.
              schema:
                type: string
        '400':
          description: Invalid task, JSON, or examples
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
          headers:
            X-HB-Backoff:
              description: Optional v1 backoff contract marker; rollout defaults off.
              schema:
                type: string
            X-HB-Admission:
              description: Optional open, busy or limited; a process-local observation, not a reservation.
              schema:
                type: string
            X-HB-Capacity:
              description: Optional process-local heavy/bytes active, limit and remaining counts plus observed epoch seconds. Cached observations may be old.
              schema:
                type: string
        '413':
          description: Request body exceeds the limit
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
          headers:
            X-HB-Backoff:
              description: Optional v1 backoff contract marker; rollout defaults off.
              schema:
                type: string
            X-HB-Admission:
              description: Optional open, busy or limited; a process-local observation, not a reservation.
              schema:
                type: string
            X-HB-Capacity:
              description: Optional process-local heavy/bytes active, limit and remaining counts plus observed epoch seconds. Cached observations may be old.
              schema:
                type: string
        '429':
          description: Per-client rate limit
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
          headers:
            X-HB-Backoff:
              description: Optional v1 backoff contract marker; rollout defaults off.
              schema:
                type: string
            X-HB-Admission:
              description: Optional open, busy or limited; a process-local observation, not a reservation.
              schema:
                type: string
            X-HB-Capacity:
              description: Optional process-local heavy/bytes active, limit and remaining counts plus observed epoch seconds. Cached observations may be old.
              schema:
                type: string
        '503':
          description: Execution disabled or Bay Run unavailable
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
          headers:
            X-HB-Backoff:
              description: Optional v1 backoff contract marker; rollout defaults off.
              schema:
                type: string
            X-HB-Admission:
              description: Optional open, busy or limited; a process-local observation, not a reservation.
              schema:
                type: string
            X-HB-Capacity:
              description: Optional process-local heavy/bytes active, limit and remaining counts plus observed epoch seconds. Cached observations may be old.
              schema:
                type: string
      x-idempotency-key:
        supported: false
        behavior: This endpoint does not implement Idempotency-Key; the header is ignored. Do not assume that retrying a write is safe.
      x-request-example:
        method: POST
        url: https://huggingbay.xyz/api/v1/bakeoff
        headers:
          Content-Type: application/json
        body:
          task: toxicity
          examples:
          - input: Have a nice day
            label: non_toxic
        parameters: []
        prerequisites:
        - This example is not executed by documentation checks. Review the operation and obtain any required user consent before sending it.
        verification: Request template. Not a captured live response.
        curl: 'curl -sS -X POST ''https://huggingbay.xyz/api/v1/bakeoff'' -H ''Content-Type: application/json'' --data-raw ''{"task":"toxicity","examples":[{"input":"Have a nice day","label":"non_toxic"}]}'''
      x-codeSamples:
      - lang: Shell
        label: curl request
        source: 'curl -sS -X POST ''https://huggingbay.xyz/api/v1/bakeoff'' -H ''Content-Type: application/json'' --data-raw ''{"task":"toxicity","examples":[{"input":"Have a nice day","label":"non_toxic"}]}'''
      x-rate-limit:
        policy: '#/x-rate-limit'
        summary: Write and protocol operations can have separate route-specific limits. Read Retry-After and retry_after_s when present; do not infer a write allowance from the public read budget.
      x-error-contract:
        note: API JSON failures use the documented response schema. Read code, message and next; retry only when the response allows it. Auth, invalid input and missing records need a caller change.
        responses:
          '400':
            description: Invalid task, JSON, or examples
            mediaTypes:
            - application/json
            schemas:
              application/json:
                type: object
                additionalProperties: true
          '413':
            description: Request body exceeds the limit
            mediaTypes:
            - application/json
            schemas:
              application/json:
                type: object
                additionalProperties: true
          '429':
            description: Per-client rate limit
            mediaTypes:
            - application/json
            schemas:
              application/json:
                type: object
                additionalProperties: true
          '503':
            description: Execution disabled or Bay Run unavailable
            mediaTypes:
            - application/json
            schemas:
              application/json:
                type: object
                additionalProperties: true
      tags:
      - Bakeoff
    servers:
    - url: https://huggingbay.xyz
  /api/v1/bakeoff/{id}:
    get:
      operationId: getSharedBakeoff
      summary: Read an aggregate result encoded in a bakeoff share token; does not rerun it
      security: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: A real share token returned by bakeoff; do not invent one.
      responses:
        '200':
          description: Aggregate result with generic call placeholders
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
          headers:
            X-HB-Backoff:
              description: Optional v1 backoff contract marker; rollout defaults off.
              schema:
                type: string
            X-HB-Admission:
              description: Optional open, busy or limited; a process-local observation, not a reservation.
              schema:
                type: string
            X-HB-Capacity:
              description: Optional process-local heavy/bytes active, limit and remaining counts plus observed epoch seconds. Cached observations may be old.
              schema:
                type: string
        '404':
          description: Invalid or undecodable token
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
          headers:
            X-HB-Backoff:
              description: Optional v1 backoff contract marker; rollout defaults off.
              schema:
                type: string
            X-HB-Admission:
              description: Optional open, busy or limited; a process-local observation, not a reservation.
              schema:
                type: string
            X-HB-Capacity:
              description: Optional process-local heavy/bytes active, limit and remaining counts plus observed epoch seconds. Cached observations may be old.
              schema:
                type: string
      x-request-example:
        method: GET
        url: https://huggingbay.xyz/api/v1/bakeoff/example
        headers: {}
        parameters:
        - name: id
          in: path
          value: example
        prerequisites:
        - Use an identifier returned by the matching list, search or create operation. Sample identifiers are not a promise that a record exists.
        verification: Request template. Not a captured live response.
        curl: curl -sS 'https://huggingbay.xyz/api/v1/bakeoff/example'
      x-codeSamples:
      - lang: Shell
        label: curl request
        source: curl -sS 'https://huggingbay.xyz/api/v1/bakeoff/example'
      x-rate-limit:
        policy: '#/x-rate-limit'
        summary: Public read budgets apply by client IP and route group. This operation can have a smaller route-specific budget. Read Retry-After on 429 or retryable 503 responses.
      x-error-contract:
        note: API JSON failures use the documented response schema. Read code, message and next; retry only when the response allows it. Auth, invalid input and missing records need a caller change.
        responses:
          '404':
            description: Invalid or undecodable token
            mediaTypes:
            - application/json
            schemas:
              application/json:
                type: object
                additionalProperties: true
      description: 'Read an aggregate result encoded in a bakeoff share token; does not rerun it.


        **Inputs.** Path, query and header fields are listed below. No request body is required.


        **Outputs.** See each status below for its media type, schema and headers. A missing record or unavailable capability is not a successful empty result.


        **Errors.** API JSON failures use the documented response schema. Read code, message and next; retry only when the response allows it. Auth, invalid input and missing records need a caller change.


        **Rate limits.** Public read budgets apply by client IP and route group. This operation can have a smaller route-specific budget. Read Retry-After on 429 or retryable 503 responses.


        **Example setup.** Use an identifier returned by the matching list, search or create operation. Sample identifiers are not a promise that a record exists.'
      tags:
      - Bakeoff
    servers:
    - url: https://huggingbay.xyz
  /v1/bakeoff:
    x-bay-run-visibility: internal/advanced
    post:
      summary: Run Bakeoff Route
      description: Infer the task family, evaluate curated models, and publish the winner.
      operationId: run_bakeoff_route_v1_bakeoff_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BakeoffRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BakeoffToolResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
      x-bay-run-optional-authentication: true
      x-bay-run-anonymous-next-call-grant:
        token_type: bakeoff_next_call
        scope: bakeoff:next_call
        issued_when: anonymous bake-off field strength is explicitly strong
        binding:
        - HTTP method
        - canonical path
        - winner model
        - canonical JSON body SHA-256
        - bake-off id
        - bake-off request hash
        one_time: true
        replay_authority: cross-instance digest-only atomic consumption
        maximum_ttl_seconds: 600
        ordinary_demo_session_authority: false
      x-bay-run-challenger:
        field: challenger_model
        identity: quarantine-admitted GCS-mirrored Hugging Face owner/repo
        scoring: scored from the mirror, using bounded load-on-demand when it is not resident
        cold_model_loading: true
        loading_source: GCS mirror only; never live Hugging Face
        metadata_check: quarantine-gated Bay Run mirror catalog
        timeout_seconds: 90.0
        quota: ordinary replay-aware bake-off quota plus a separate per-principal challenger counter
        daily_limit_per_principal: 2
      x-bay-run-visibility: internal/advanced
      tags:
      - Bakeoff
    servers:
    - url: https://run.huggingbay.xyz
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    EscalateToFrontierResponse:
      properties:
        schema:
          type: string
          title: Schema
          default: bay-run.escalate-to-frontier.v1
        reason:
          type: string
          enum:
          - no_specialists
          - weak_field
          title: Reason
        suggested_action:
          type: string
          const: fallback_to_frontier
          title: Suggested Action
          default: fallback_to_frontier
        family:
          type: string
          maxLength: 128
          minLength: 1
          title: Family
        alternatives:
          items:
            additionalProperties: true
            type: object
          type: array
          maxItems: 32
          title: Alternatives
      additionalProperties: false
      type: object
      required:
      - reason
      - family
      title: EscalateToFrontierResponse
      description: Typed fail-closed handoff when Bay Run cannot prove a specialist route.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ComparisonCardResponse:
      properties:
        schema:
          type: string
          title: Schema
          default: bay-run.comparison-card.v1
        available:
          type: boolean
          title: Available
        p50_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: P50 Ms
        est_usd:
          type: string
          title: Est Usd
        f1:
          anyOf:
          - type: number
          - type: 'null'
          title: F1
        f1_ci:
          anyOf:
          - type: number
          - type: 'null'
          title: F1 Ci
        n_labels:
          anyOf:
          - type: integer
          - type: 'null'
          title: N Labels
        frontier_comparison:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Frontier Comparison
        comparison_basis:
          type: string
          const: measured_route_only
          title: Comparison Basis
          default: measured_route_only
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
        text:
          anyOf:
          - type: string
          - type: 'null'
          title: Text
        html:
          anyOf:
          - type: string
          - type: 'null'
          title: Html
      additionalProperties: false
      type: object
      required:
      - available
      - est_usd
      title: ComparisonCardResponse
      description: Measured route-only comparison; frontier claims stay explicitly absent.
    BakeoffExample:
      properties:
        input:
          type: string
          maxLength: 20000
          minLength: 1
          title: Input
        expected:
          type: string
          maxLength: 20000
          minLength: 1
          title: Expected
      additionalProperties: false
      type: object
      required:
      - input
      - expected
      title: BakeoffExample
      description: The intentionally tiny public labeled-example contract.
    BakeoffRequest:
      properties:
        task_description:
          type: string
          maxLength: 1000
          minLength: 3
          title: Task Description
        examples:
          anyOf:
          - items:
              $ref: '#/components/schemas/BakeoffExample'
            type: array
            maxItems: 100
            minItems: 3
          - type: 'null'
          title: Examples
        paste:
          anyOf:
          - type: string
            maxLength: 5000000
          - type: 'null'
          title: Paste
        csv:
          anyOf:
          - type: string
            maxLength: 5000000
          - type: 'null'
          title: Csv
        hf_dataset_id:
          anyOf:
          - type: string
            maxLength: 193
            minLength: 3
          - type: 'null'
          title: Hf Dataset Id
        public:
          type: boolean
          title: Public
          default: false
        challenger_model:
          anyOf:
          - type: string
            maxLength: 193
            minLength: 3
          - type: 'null'
          title: Challenger Model
      additionalProperties: false
      type: object
      required:
      - task_description
      title: BakeoffRequest
      description: 'One-call bake-off with prompt examples or a bounded labeled source.


        ``examples`` remains the compact prompt-only compatibility shape.  Serious

        fields should send ``paste``, ``csv``, or ``hf_dataset_id`` so Bay Run can

        hold out a real test split instead of treating the five prompt examples as

        evidence.'
    BakeoffToolResponse:
      properties:
        winner:
          anyOf:
          - type: string
          - type: 'null'
          title: Winner
        scorecard:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Scorecard
        candidate_summary:
          additionalProperties: true
          type: object
          title: Candidate Summary
        partial:
          type: boolean
          title: Partial
        weak:
          type: boolean
          title: Weak
        field_strength:
          additionalProperties: true
          type: object
          title: Field Strength
        receipt:
          additionalProperties: true
          type: object
          title: Receipt
        receipt_hash:
          type: string
          title: Receipt Hash
        request_hash:
          type: string
          title: Request Hash
        bakeoff_id:
          type: string
          title: Bakeoff Id
        public:
          type: boolean
          title: Public
        public_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Public Url
        public_status:
          type: string
          enum:
          - published_strong
          - private_incomplete_proof
          title: Public Status
          default: private_incomplete_proof
        watermark:
          anyOf:
          - type: string
          - type: 'null'
          title: Watermark
        task_kind:
          type: string
          title: Task Kind
        task_family:
          type: string
          title: Task Family
        candidate_models:
          items:
            type: string
          type: array
          title: Candidate Models
        candidate_roles:
          additionalProperties:
            type: string
          type: object
          title: Candidate Roles
        challenger_model:
          anyOf:
          - type: string
          - type: 'null'
          title: Challenger Model
        winner_role:
          type: string
          title: Winner Role
        challenger_gate:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Challenger Gate
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        next_call:
          additionalProperties: true
          type: object
          title: Next Call
        next_call_grant:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Next Call Grant
        bakeoff_quota:
          additionalProperties: true
          type: object
          title: Bakeoff Quota
        challenger_bakeoff_quota:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Challenger Bakeoff Quota
        author_claim:
          additionalProperties: true
          type: object
          title: Author Claim
        durable_free_key:
          additionalProperties: true
          type: object
          title: Durable Free Key
        task_fingerprint:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Fingerprint
        dataset_fingerprint:
          anyOf:
          - type: string
          - type: 'null'
          title: Dataset Fingerprint
        dataset_source:
          additionalProperties: true
          type: object
          title: Dataset Source
        pareto_frontier:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Pareto Frontier
        confidence_intervals:
          additionalProperties: true
          type: object
          title: Confidence Intervals
        quality_policy:
          type: string
          title: Quality Policy
          default: pareto_quality_latency_cost
        route_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Route Id
        escalate_to_frontier:
          anyOf:
          - $ref: '#/components/schemas/EscalateToFrontierResponse'
          - type: 'null'
        comparison_card:
          anyOf:
          - $ref: '#/components/schemas/ComparisonCardResponse'
          - type: 'null'
      additionalProperties: false
      type: object
      required:
      - scorecard
      - candidate_summary
      - partial
      - weak
      - field_strength
      - receipt
      - receipt_hash
      - request_hash
      - bakeoff_id
      - public
      - public_url
      - task_kind
      - task_family
      - candidate_models
      - candidate_roles
      - winner_role
      - created_at
      - next_call
      - bakeoff_quota
      - author_claim
      - durable_free_key
      title: BakeoffToolResponse
      description: Explicit MCP output contract for the one-call bake-off.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Hugging Bay bearer token for account, publisher, or authorized operator endpoints. Public discovery endpoints do not require a token. Get a reader token self-serve (no prior auth, no signup): POST /api/account/reader-token, then send it as Authorization: Bearer <token>. Full walkthrough at /quickstart#get-a-key.'
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth access token, bay_live_ durable free key, or configured bearer
      description: Bay Run OAuth access token, email-free revocable bay_live_ demo key, or configured operator/demo bearer.
    DeveloperApiKey:
      type: http
      scheme: bearer
      bearerFormat: bayr1.<credential_id>.<one-time-secret>
      description: OAuth-owned, revocable developer key. The raw secret is shown only on create/rotate and stored solely as a dedicated-pepper HMAC digest. Owner-management scopes require operator-attested enrollment; public OAuth alone cannot issue them. billing:write controls checkout, policy, and approval. billing:spend is the separate agent-spend authority and must be paired with inference:invoke. Keep OAuth and billing:write keys out of agent harnesses.
    OperatorBearer:
      type: http
      scheme: bearer
      description: Platform operator secret accepted only on explicitly documented owner-management operations. It is not an OAuth access token and must never be placed in an agent harness.
x-refined-from:
- huggingbay-xyz-openapi.json


# --- truncated at 32 KB (56 KB total) ---
# Full source: https://artifacts.apis.io/huggingbay-xyz/openapi/huggingbay-xyz-bakeoff-api-openapi.yml