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

# Lexicon Schemas

> Sync your data dictionary with Mixpanel

# Lexicon Schemas API

Use schemas to populate Mixpanel Lexicon and provide additional context for your data.

## Base URL

```
https://mixpanel.com/api/app/projects/{projectId}/schemas
```

## List Schemas

Get all schemas in a project.

<ParamField path="projectId" type="number" required>
  Your Mixpanel project ID
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://mixpanel.com/api/app/projects/123/schemas" \
    -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET
  ```

  ```python Python theme={null}
  import requests
  from requests.auth import HTTPBasicAuth

  response = requests.get(
      'https://mixpanel.com/api/app/projects/123/schemas',
      auth=HTTPBasicAuth('SERVICE_ACCOUNT_USERNAME', 'SERVICE_ACCOUNT_SECRET')
  )

  schemas = response.json()
  print(f"Total schemas: {len(schemas['results'])}")
  ```
</CodeGroup>

***

## Create/Replace Schema

Upload or update a schema for an event or profile.

<ParamField path="projectId" type="number" required>
  Your Mixpanel project ID
</ParamField>

<ParamField path="entityType" type="string" required>
  Type of entity: `event` or `profile`
</ParamField>

<ParamField path="name" type="string" required>
  Name of the event or profile property
</ParamField>

<ParamField body="description" type="string">
  Description of the entity
</ParamField>

<ParamField body="properties" type="object">
  Properties schema definition

  <Expandable title="properties[propertyName]">
    <ParamField body="type" type="string" required>
      Property type: `string`, `number`, `boolean`, `array`, `object`, `integer`, `null`
    </ParamField>

    <ParamField body="description" type="string">
      Property description
    </ParamField>

    <ParamField body="metadata.com.mixpanel.displayName" type="string">
      Display name in Mixpanel UI
    </ParamField>

    <ParamField body="metadata.com.mixpanel.hidden" type="boolean">
      Hide property in UI
    </ParamField>

    <ParamField body="metadata.com.mixpanel.dropped" type="boolean">
      Drop property at ingestion (events only)
    </ParamField>
  </Expandable>
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://mixpanel.com/api/app/projects/123/schemas/event/Purchase" \
    -X POST \
    -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET \
    -H "Content-Type: application/json" \
    -d '{
      "description": "User completed a purchase",
      "properties": {
        "amount": {
          "type": "number",
          "description": "Purchase amount in USD"
        },
        "item_name": {
          "type": "string",
          "description": "Name of purchased item"
        },
        "currency": {
          "type": "string",
          "description": "Currency code"
        }
      }
    }'
  ```

  ```python Python theme={null}
  import requests
  from requests.auth import HTTPBasicAuth

  schema = {
      "description": "User completed a purchase",
      "properties": {
          "amount": {
              "type": "number",
              "description": "Purchase amount in USD"
          },
          "item_name": {
              "type": "string",
              "description": "Name of purchased item"
          },
          "currency": {
              "type": "string",
              "description": "Currency code"
          }
      }
  }

  response = requests.post(
      'https://mixpanel.com/api/app/projects/123/schemas/event/Purchase',
      auth=HTTPBasicAuth('SERVICE_ACCOUNT_USERNAME', 'SERVICE_ACCOUNT_SECRET'),
      json=schema
  )

  print(response.json())
  ```
</CodeGroup>

***

## Batch Upload Schemas

Upload multiple schemas at once.

<ParamField body="entries" type="array" required>
  Array of schema entries

  <Expandable title="entries[]">
    <ParamField body="entityType" type="string">
      `event` or `profile`
    </ParamField>

    <ParamField body="name" type="string">
      Event or property name
    </ParamField>

    <ParamField body="schema" type="object">
      Schema definition (same as single upload)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="truncate" type="boolean">
  Delete entire data dictionary before inserting

  Default: `false`
</ParamField>

### Example Request

<CodeGroup>
  ```python Python theme={null}
  import requests
  from requests.auth import HTTPBasicAuth

  payload = {
      "entries": [
          {
              "entityType": "event",
              "name": "Signed Up",
              "schema": {
                  "description": "User registration event",
                  "properties": {
                      "method": {
                          "type": "string",
                          "description": "Signup method: email, google, facebook"
                      }
                  }
              }
          },
          {
              "entityType": "event",
              "name": "Purchase",
              "schema": {
                  "description": "Purchase completed",
                  "properties": {
                      "amount": {
                          "type": "number",
                          "description": "Purchase amount"
                      }
                  }
              }
          }
      ],
      "truncate": False
  }

  response = requests.post(
      'https://mixpanel.com/api/app/projects/123/schemas',
      auth=HTTPBasicAuth('USERNAME', 'SECRET'),
      json=payload
  )

  print(response.json())
  ```
</CodeGroup>

***

## Delete Schema

Remove a schema from the project.

<ParamField path="projectId" type="number" required>
  Your Mixpanel project ID
</ParamField>

<ParamField path="entityType" type="string" required>
  `event` or `profile`
</ParamField>

<ParamField path="name" type="string" required>
  Name of the event or profile
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://mixpanel.com/api/app/projects/123/schemas/event/OldEvent" \
    -X DELETE \
    -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET
  ```
</CodeGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Sync schemas from your tracking plan">
    Keep schemas in sync with your source code:

    ```python theme={null}
    import json

    # Load tracking plan
    with open('tracking_plan.json') as f:
        plan = json.load(f)

    # Upload to Mixpanel
    entries = []
    for event in plan['events']:
        entries.append({
            'entityType': 'event',
            'name': event['name'],
            'schema': {
                'description': event['description'],
                'properties': event['properties']
            }
        })

    upload_schemas(entries)
    ```
  </Accordion>

  <Accordion title="Use clear descriptions">
    Provide context for analysts:

    ```json theme={null}
    {
      "description": "Fired when user completes checkout and payment is confirmed",
      "properties": {
        "amount": {
          "type": "number",
          "description": "Total purchase amount in USD, including taxes and shipping"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Leverage metadata for UI customization">
    Control how properties appear in Mixpanel:

    ```json theme={null}
    {
      "properties": {
        "user_internal_id": {
          "type": "string",
          "metadata": {
            "com.mixpanel": {
              "hidden": true,
              "displayName": "Internal User ID"
            }
          }
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>