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

# Enrich entity

> Generate structured fields for an entity from context and a JSON Schema.

Submits entity context and a JSON Schema. The response returns enrichment data that follows the requested schema when possible.

The root schema must have `type: "object"` and at least one entry in `properties`. Lev8 accepts schemas up to 256 KiB, 12 levels, and 200 cumulative properties.

## Example

```bash theme={null}
curl "https://app.lev8.com/v1/enrich" \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $LEV8_API_KEY" \
  --data '{
    "entity_context": "Company: OpenAI\nWebsite: https://openai.com",
    "enrich_fields": {
      "type": "object",
      "properties": {
        "company_summary": {"type": "string"},
        "ceo": {"type": "string"}
      },
      "required": ["company_summary", "ceo"]
    }
  }'
```

## Response

```json theme={null}
{
  "success": true,
  "answer": {
    "company_summary": "OpenAI is an AI research and product company.",
    "ceo": "Sam Altman"
  }
}
```

If the workflow completes without a generated result, the response can use `success: false`:

```json theme={null}
{
  "success": false,
  "answer": {
    "answer": "No result generated from enrich"
  }
}
```

## Generate fields with Pydantic

```python theme={null}
from pydantic import BaseModel, Field


class CompanyEnrichFields(BaseModel):
    company_summary: str = Field(description="Company summary")
    ceo: str = Field(description="Current CEO")


entity_context = "Company: OpenAI\nWebsite: https://openai.com"
enrich_fields = CompanyEnrichFields.model_json_schema()

payload = {
    "entity_context": entity_context,
    "enrich_fields": enrich_fields,
}
```


## OpenAPI

````yaml POST /v1/enrich
openapi: 3.1.0
info:
  title: lev8 API
  version: '1.0'
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://app.lev8.com
security:
  - ApiKeyAuth: []
paths:
  /v1/enrich:
    post:
      summary: Enrich entity
      description: Generate structured fields for an entity from context and a JSON Schema.
      operationId: enrichEntity
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Optional stable key for this logical request. When omitted, lev8
            generates one and returns it in the response Header.
          schema:
            type: string
            maxLength: 128
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichRequest'
            example:
              entity_context: |-
                Company: OpenAI
                Website: https://openai.com
              enrich_fields:
                type: object
                properties:
                  company_summary:
                    type: string
                  ceo:
                    type: string
                required:
                  - company_summary
                  - ceo
      responses:
        '200':
          description: Enrichment result.
          headers:
            Idempotency-Key:
              description: The supplied or server-generated idempotency key.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichResponse'
        '401':
          description: Missing or invalid API key.
        '402':
          description: Insufficient credits.
        '403':
          description: API key is forbidden or lacks Enrich access.
        '409':
          description: >-
            Idempotency conflict or no completed response is available to
            replay.
        '422':
          description: Validation failed.
        '429':
          description: Concurrency limit reached.
        '500':
          description: Server error.
        '503':
          description: Enrich is not enabled.
components:
  schemas:
    EnrichRequest:
      type: object
      additionalProperties: false
      required:
        - entity_context
        - enrich_fields
      properties:
        entity_context:
          type: string
          minLength: 1
          description: >-
            Context for the entity to enrich, such as name, website, social
            handles, or an existing description. Maximum 16 KiB after trimming.
          x-default: |-
            Company: OpenAI
            Website: https://openai.com
          example: |-
            Company: OpenAI
            Website: https://openai.com
        enrich_fields:
          type: object
          required:
            - type
            - properties
          properties:
            type:
              type: string
              const: object
            properties:
              type: object
              minProperties: 1
              additionalProperties: true
          description: >-
            Object JSON Schema that describes the fields to generate. Maximum
            256 KiB, 12 levels, and 200 cumulative properties.
          additionalProperties: true
          example:
            type: object
            properties:
              company_summary:
                type: string
              ceo:
                type: string
            required:
              - company_summary
              - ceo
    EnrichResponse:
      type: object
      additionalProperties: false
      required:
        - success
        - answer
      properties:
        success:
          type: boolean
          example: true
        answer:
          type: object
          description: >-
            Enrichment result. Successful responses try to match the requested
            `enrich_fields` JSON Schema.
          additionalProperties: true
          example:
            company_summary: OpenAI is an AI research and product company.
            ceo: Sam Altman
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      x-default: lev8_live_...

````