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

# Search an index

> Returns relevance-ranked chunk references from one index. Original source text is not included; hydrate documents from your own datastore using `doc_id`.

The optional `filter` performs exact matches against top-level metadata fields. Filters are not an authorization boundary.




## OpenAPI

````yaml /openapi/openapi.yaml post /v1/indexes/{index_id}/search
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/indexes/{index_id}/search:
    post:
      tags:
        - Retrieval
      summary: Search an index
      description: >
        Returns relevance-ranked chunk references from one index. Original
        source text is not included; hydrate documents from your own datastore
        using `doc_id`.


        The optional `filter` performs exact matches against top-level metadata
        fields. Filters are not an authorization boundary.
      operationId: searchIndex
      parameters:
        - $ref: '#/components/parameters/IndexId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            examples:
              defaultSearch:
                value:
                  query: How do I rotate an API key?
              filteredSearch:
                value:
                  query: How do I request a refund?
                  top_k: 10
                  candidate_k: 100
                  filter:
                    locale: en
                    status: published
                  return_components: false
      responses:
        '200':
          description: Ranked search results, which may be empty
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              example:
                results:
                  - doc_id: help-center:api-keys
                    chunk_id: chk_000003
                    chunk_index: 3
                    score: 0.82
                    metadata:
                      source: help-center
                      locale: en
                      status: published
                usage:
                  input_tokens: 9
                  document_count: 0
                  chunk_count: 1
                  candidate_count: 42
                  latency_ms: 96
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    IndexId:
      name: index_id
      in: path
      required: true
      description: Tenant-scoped index UUID returned by index creation.
      schema:
        type: string
        format: uuid
  schemas:
    SearchRequest:
      type: object
      additionalProperties: false
      required:
        - query
      properties:
        query:
          type: string
          minLength: 1
          description: Non-empty query, at most 8 KiB encoded as UTF-8.
        top_k:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          description: Maximum final results returned.
        candidate_k:
          type: integer
          minimum: 1
          maximum: 500
          default: 100
          description: Retrieval breadth considered before final ranking.
        filter:
          type: object
          additionalProperties: true
          description: Exact matches on top-level metadata fields.
        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'
    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
    NotFound:
      description: Tenant-scoped resource was not found
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: not_found
              message: Not found
    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_`.

````