> ## Documentation Index
> Fetch the complete documentation index at: https://docs.breadbowl.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Score transient documents

> Ranks one to 50 request-local documents for one query without adding them to an index. An aggregate usage event is recorded, but the submitted query, documents, chunks, and derived representations are not persisted as indexed content.




## OpenAPI

````yaml /openapi/openapi.yaml post /v1/score
openapi: 3.1.0
info:
  title: BreadBowl Embed API (Alpha)
  version: 0.1.0-alpha
  description: >
    REST API for managed multi-vector retrieval and transient document scoring.


    BreadBowl Embed accepts source text and returns ranked document and chunk
    references. It does not return conventional embedding vectors.
servers:
  - url: https://embed.breadbowl.ai
    description: Production API
security:
  - bearerAuth: []
tags:
  - name: Service health
    description: Unauthenticated liveness and readiness checks
  - name: Indexes
    description: Create and discover tenant-scoped indexes
  - name: Documents
    description: Upsert and delete indexed documents
  - name: Retrieval
    description: Search an index or score a transient candidate set
  - name: Usage
    description: Inspect current UTC-month usage and assigned limits
paths:
  /v1/score:
    post:
      tags:
        - Retrieval
      summary: Score transient documents
      description: >
        Ranks one to 50 request-local documents for one query without adding
        them to an index. An aggregate usage event is recorded, but the
        submitted query, documents, chunks, and derived representations are not
        persisted as indexed content.
      operationId: scoreDocuments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScoreRequest'
            example:
              query: What is the refund window?
              documents:
                - doc_id: a
                  text: Refund requests are accepted within 30 days.
                  metadata:
                    source: policy
                - doc_id: b
                  text: Orders usually ship in two business days.
                  metadata:
                    source: shipping
              return_components: false
      responses:
        '200':
          description: Documents ranked by descending score
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              example:
                results:
                  - doc_id: a
                    chunk_id: transient_0
                    chunk_index: 0
                    score: 0.88
                    metadata:
                      source: policy
                  - doc_id: b
                    chunk_id: transient_1
                    chunk_index: 1
                    score: 0.21
                    metadata:
                      source: shipping
                usage:
                  input_tokens: 27
                  document_count: 2
                  chunk_count: 0
                  candidate_count: 2
                  latency_ms: 74
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    ScoreRequest:
      type: object
      additionalProperties: false
      required:
        - query
        - documents
      properties:
        query:
          type: string
          minLength: 1
          description: Non-empty query, at most 8 KiB encoded as UTF-8.
        documents:
          type: array
          minItems: 1
          maxItems: 50
          description: Transient documents to rank; IDs must be unique within the request.
          items:
            $ref: '#/components/schemas/DocumentInput'
        return_components:
          type: boolean
          default: false
          description: Include optional diagnostic component scores when available.
    SearchResponse:
      type: object
      additionalProperties: false
      required:
        - results
        - usage
      properties:
        results:
          type: array
          description: Results ordered by descending final score.
          items:
            $ref: '#/components/schemas/SearchResult'
        usage:
          $ref: '#/components/schemas/RequestUsage'
    DocumentInput:
      type: object
      additionalProperties: false
      required:
        - doc_id
        - text
      properties:
        doc_id:
          type: string
          minLength: 1
          maxLength: 255
          description: Idempotency identity within one index.
        text:
          type: string
          minLength: 1
          description: Non-empty source text, at most 100 KiB encoded as UTF-8.
        metadata:
          allOf:
            - $ref: '#/components/schemas/Metadata'
          default: {}
    SearchResult:
      type: object
      additionalProperties: false
      required:
        - doc_id
        - chunk_id
        - chunk_index
        - score
        - metadata
      properties:
        doc_id:
          type: string
        chunk_id:
          type: string
        chunk_index:
          type: integer
          minimum: 0
        score:
          type: number
          description: Final relevance score used to order this response.
        qk_score:
          type: number
          description: Optional diagnostic component score.
        qkv_score:
          type: number
          description: Optional diagnostic component score.
        metadata:
          $ref: '#/components/schemas/Metadata'
    RequestUsage:
      type: object
      additionalProperties: false
      required:
        - input_tokens
        - document_count
        - chunk_count
        - candidate_count
        - latency_ms
      properties:
        input_tokens:
          type: integer
          minimum: 0
        document_count:
          type: integer
          minimum: 0
        chunk_count:
          type: integer
          minimum: 0
        candidate_count:
          type: integer
          minimum: 0
        latency_ms:
          type: integer
          minimum: 0
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              type: string
              examples:
                - validation_error
            message:
              type: string
            issues:
              type: array
              description: Optional field-level validation details.
              items: {}
    Metadata:
      type: object
      additionalProperties: true
      description: Customer-defined top-level JSON metadata.
  headers:
    RequestId:
      description: Correlation ID for logging and support. This is not a credential.
      schema:
        type: string
        minLength: 1
  responses:
    Unauthorized:
      description: API key is missing, invalid, or revoked
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: authentication_failed
              message: Authentication failed
    Forbidden:
      description: Tenant is suspended
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: tenant_suspended
              message: Tenant is suspended
    ValidationError:
      description: Request failed validation or would exceed the document allowance
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: validation_error
              message: Request validation failed
              issues: []
    RateLimited:
      description: Request, concurrency, or monthly token limit was reached
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          description: Minimum seconds before retrying.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rate:
              value:
                error:
                  code: rate_limit_exceeded
                  message: Tenant request rate exceeded
            concurrency:
              value:
                error:
                  code: concurrency_limit_exceeded
                  message: Tenant concurrency limit exceeded
            usage:
              value:
                error:
                  code: usage_limit_exceeded
                  message: Monthly input-token allowance exhausted
    InternalError:
      description: Unexpected service failure
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: internal_error
              message: Internal server error
    ServiceUnavailable:
      description: Service cannot process the request temporarily
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: service_unavailable
              message: Service is temporarily unavailable
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: BreadBowl Embed API key
      description: Tenant-scoped API key beginning with `qkv_live_`.

````