Bem Schema Inference API

openapi: 3.2.0
info:
  title: Bem Schema Inference API
  version: 1.0.0
  description: 'Infer JSON Schemas from uploaded documents using AI.


    Upload a file (PDF, image, spreadsheet, email, etc.) and receive a general-purpose JSON Schema

    that captures the document''s structure. The inferred schema can be used directly as the

    `outputSchema` when creating Extract functions.


    The schema is designed to be broadly applicable to documents of the same type, not just

    the specific file uploaded.'
servers:
- url: https://api.bem.ai
  description: US Region API
  variables: {}
- url: https://api.eu1.bem.ai
  description: EU Region API
  variables: {}
security:
- API Key: []
tags:
- name: Schema Inference
  description: 'Infer JSON Schemas from uploaded documents using AI.


    Upload a file (PDF, image, spreadsheet, email, etc.) and receive a general-purpose JSON Schema

    that captures the document''s structure. The inferred schema can be used directly as the

    `outputSchema` when creating Extract functions.


    The schema is designed to be broadly applicable to documents of the same type, not just

    the specific file uploaded.'
paths:
  /v3/infer-schema:
    post:
      operationId: v3-infer-schema
      summary: Infer Schema from File
      description: "**Analyze a file and infer a JSON Schema from its contents.**\n\nAccepts a file via multipart form upload and uses Gemini to analyze the document,\nreturning a description of its contents, an inferred JSON Schema capturing all\nextractable fields, and document classification metadata.\n\nThe returned schema is designed to be reusable across many similar documents of the\nsame type, not just the specific file uploaded. It can be used directly as the\n`outputSchema` when creating a Transform function.\n\nThe endpoint also detects whether the file contains multiple bundled documents\nand classifies the content nature (textual, visual, audio, video, or mixed).\n\n## Supported file types\n\nPDF, PNG, JPEG, HEIC, HEIF, WebP, CSV, XLS, XLSX, DOCX, JSON, HTML, XML, EML,\nplain text, WAV, MP3, M4A, MP4.\n\n## File size limit\n\nMaximum file size is **20 MB**.\n\n## Examples\n\nUsing curl:\n```bash\ncurl -X POST https://api.bem.ai/v3/infer-schema \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -F \"file=@invoice.pdf\"\n```\n\nUsing the Bem CLI:\n```bash\nbem infer-schema create --file @invoice.pdf\n```"
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferSchemaResponseV3'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
      tags:
      - Schema Inference
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/InferSchemaMultipartFormData'
            encoding:
              file:
                contentType: '*/*'
components:
  schemas:
    InferSchemaAnalysis:
      type: object
      required:
      - fileName
      - contentType
      - sizeBytes
      - fileType
      - description
      - isMultiDocument
      - documentTypes
      - contentNature
      properties:
        fileName:
          type: string
          description: Original filename of the uploaded file.
          title: File Name
        contentType:
          type: string
          description: MIME content type of the uploaded file.
          title: Content Type
        sizeBytes:
          type: integer
          description: Size of the uploaded file in bytes.
          title: Size in Bytes
        fileType:
          type: string
          description: High-level file category (e.g. "document", "image", "spreadsheet", "email").
          title: File Type
        description:
          type: string
          description: 2-3 sentence description of what the file contains.
        schema:
          type: object
          unevaluatedProperties: {}
          description: Inferred JSON Schema representing all extractable data fields.
        isMultiDocument:
          type: boolean
          description: Whether the file contains multiple separate documents bundled together.
        documentTypes:
          type: array
          items:
            $ref: '#/components/schemas/DocumentTypeInfo'
          description: List of distinct document types found in the file with counts.
        contentNature:
          type: string
          description: 'Classification of the primary content.

            One of: `textual`, `visual`, `audio`, `video`, `mixed`.'
      description: Analysis result returned by the infer-schema endpoint.
    InferSchemaResponseV3:
      type: object
      required:
      - filename
      - analysis
      properties:
        filename:
          type: string
          description: Original filename of the uploaded file.
        analysis:
          allOf:
          - $ref: '#/components/schemas/InferSchemaAnalysis'
          description: Full analysis result including description, schema, and document classification.
      description: Response from the infer-schema endpoint.
    DocumentTypeInfo:
      type: object
      required:
      - name
      - count
      - description
      properties:
        name:
          type: string
          description: Short snake_case name (e.g. "invoice", "receipt", "utility_bill").
        count:
          type: integer
          description: Number of instances of this document type in the file.
        description:
          type: string
          description: Brief description of this document type.
      description: Describes a distinct document type found in the file.
    InferSchemaMultipartFormData:
      type: object
      properties:
        file:
          description: The file to analyze and infer a JSON schema from.
      required:
      - file
    HTTPError:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Error message describing what went wrong
        code:
          type: integer
          description: HTTP status code
        details:
          type: object
          unevaluatedProperties: {}
          description: Additional error details (optional)
          title: Error Details
      description: Standard HTTP error response
  securitySchemes:
    API_Key:
      type: apiKey
      in: header
      name: x-api-key
      description: Authenticate using API Key in request header