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.
openapi: 3.1.0
info:
title: Bem Buckets Schema Inference API
version: 1.0.0
description: "Buckets are named partitions of the knowledge graph within an\naccount+environment. Entities, mentions, and relations are scoped to a\nbucket so a single account+environment can host multiple isolated graphs\n— for example one per data source or workspace.\n\nEvery account+environment has exactly one **default** bucket, used by\nunscoped flows. The default bucket can be renamed but never deleted.\n\nUse these endpoints to create, list, fetch, rename, and delete buckets:\n\n- **`POST /v3/buckets`** creates a non-default bucket.\n- **`GET /v3/buckets`** lists buckets with cursor pagination\n (`startingAfter` / `endingBefore` over `bucketID`).\n- **`PATCH /v3/buckets/{bucketID}`** updates `name` and/or `description`.\n- **`DELETE /v3/buckets/{bucketID}`** soft-deletes a bucket. A non-empty\n bucket is rejected with `409 Conflict` unless `?cascade=true` is\n passed; the default bucket can never be deleted."
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:
InferSchemaMultipartFormData:
type: object
properties:
file:
description: The file to analyze and infer a JSON schema from.
required:
- file
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.
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
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.
securitySchemes:
API Key:
type: apiKey
in: header
name: x-api-key
description: Authenticate using API Key in request header