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.

projectId · number · required

Your Mixpanel project ID

Example Request

cURL

curl "https://mixpanel.com/api/app/projects/123/schemas" \
  -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET

---

Create/Replace Schema

Upload or update a schema for an event or profile.

projectId · number · required

Your Mixpanel project ID

entityType · string · required

Type of entity: event or profile

name · string · required

Name of the event or profile property

description · string

Description of the entity

properties · object

Properties schema definition

Show properties[propertyName]

type · string · required

Property type: string, number, boolean, array, object, integer, null

description · string

Property description

metadata.com.mixpanel.displayName · string

Display name in Mixpanel UI

metadata.com.mixpanel.hidden · boolean

Hide property in UI

metadata.com.mixpanel.dropped · boolean

Drop property at ingestion (events only)

Example Request

cURL

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"
      }
    }
  }'

---

Batch Upload Schemas

Upload multiple schemas at once.

entries · array · required

Array of schema entries

Show entries[]

entityType · string

event or profile

name · string

Event or property name

schema · object

Schema definition (same as single upload)

truncate · boolean

Delete entire data dictionary before inserting

Default: false

Example Request

Python

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())

---

Delete Schema

Remove a schema from the project.

projectId · number · required

Your Mixpanel project ID

entityType · string · required

event or profile

name · string · required

Name of the event or profile

Example Request

cURL

curl "https://mixpanel.com/api/app/projects/123/schemas/event/OldEvent" \
  -X DELETE \
  -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET

Best Practices

Sync schemas from your tracking plan

Keep schemas in sync with your source code:

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)

Use clear descriptions

Provide context for analysts:

{
  "description": "Fired when user completes checkout and payment is confirmed",
  "properties": {
    "amount": {
      "type": "number",
      "description": "Total purchase amount in USD, including taxes and shipping"
    }
  }
}

Leverage metadata for UI customization

Control how properties appear in Mixpanel:

{
  "properties": {
    "user_internal_id": {
      "type": "string",
      "metadata": {
        "com.mixpanel": {
          "hidden": true,
          "displayName": "Internal User ID"
        }
      }
    }
  }
}