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

# Create an index

> Creates a tenant-scoped index. Names are unique within a tenant. The returned model version is immutable for that index; create and reingest into a new index when moving to another version.

Omit `model` unless the BreadBowl Embed team has explicitly instructed you to select a supported model.




## OpenAPI

````yaml /openapi/openapi.yaml post /v1/indexes
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:
    post:
      tags:
        - Indexes
      summary: Create an index
      description: >
        Creates a tenant-scoped index. Names are unique within a tenant. The
        returned model version is immutable for that index; create and reingest
        into a new index when moving to another version.


        Omit `model` unless the BreadBowl Embed team has explicitly instructed
        you to select a supported model.
      operationId: createIndex
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIndexRequest'
            examples:
              defaults:
                summary: Use default model and chunking
                value:
                  name: production
                  text_retention: none
              customChunking:
                summary: Specify token-window chunking
                value:
                  name: support-docs-v2
                  text_retention: none
                  chunking:
                    strategy: token_window
                    max_tokens: 384
                    overlap_tokens: 64
                    minimum_chunk_tokens: 32
                  metadata_schema:
                    source:
                      type: string
                    locale:
                      type: string
      responses:
        '200':
          description: Index created
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Index'
              example:
                id: 739c40ce-fa7e-4ba1-bcc2-46632fd13088
                name: production
                model: breadbowl-embed-alpha
                model_version: version-2026-07
                text_retention: none
                chunking:
                  strategy: token_window
                  max_tokens: 384
                  overlap_tokens: 64
                  minimum_chunk_tokens: 32
                metadata_schema: {}
                status: ready
                created_at: '2026-07-15T16:27:28.765Z'
        '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:
    CreateIndexRequest:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          description: Human-readable name unique within the authenticated tenant.
        model:
          type: string
          minLength: 1
          description: >-
            Optional supported model name. Omit unless instructed during
            onboarding.
        text_retention:
          type: string
          enum:
            - none
          default: none
        chunking:
          $ref: '#/components/schemas/ChunkingConfig'
        metadata_schema:
          type: object
          additionalProperties: true
          default: {}
          description: Descriptive customer metadata schema recorded with the index.
    Index:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - model
        - model_version
        - text_retention
        - chunking
        - metadata_schema
        - status
        - created_at
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          minLength: 1
        model:
          type: string
          minLength: 1
        model_version:
          type: string
          minLength: 1
          description: Immutable serving version for this index.
        text_retention:
          type: string
          enum:
            - none
        chunking:
          allOf:
            - $ref: '#/components/schemas/ResolvedChunkingConfig'
        metadata_schema:
          type: object
          additionalProperties: true
        status:
          type: string
          enum:
            - creating
            - ready
            - error
        created_at:
          type: string
          format: date-time
    ChunkingConfig:
      type: object
      additionalProperties: false
      properties:
        strategy:
          type: string
          enum:
            - token_window
          default: token_window
        max_tokens:
          type: integer
          minimum: 1
          default: 384
        overlap_tokens:
          type: integer
          minimum: 0
          default: 64
          description: Must be lower than `max_tokens`.
        minimum_chunk_tokens:
          type: integer
          minimum: 0
          default: 32
          description: Must not exceed `max_tokens`.
    ResolvedChunkingConfig:
      type: object
      additionalProperties: false
      required:
        - strategy
        - max_tokens
        - overlap_tokens
        - minimum_chunk_tokens
      properties:
        strategy:
          type: string
          enum:
            - token_window
        max_tokens:
          type: integer
          minimum: 1
        overlap_tokens:
          type: integer
          minimum: 0
        minimum_chunk_tokens:
          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: {}
  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_`.

````