Skip to main content

​
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 "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

​
Example Request

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
​
truncate
boolean
Delete entire data dictionary before insertingDefault: false

​
Example Request

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 "https://mixpanel.com/api/app/projects/123/schemas/event/OldEvent" \
  -X DELETE \
  -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET

​
Best Practices

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)
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"
    }
  }
}
Control how properties appear in Mixpanel:
{
  "properties": {
    "user_internal_id": {
      "type": "string",
      "metadata": {
        "com.mixpanel": {
          "hidden": true,
          "displayName": "Internal User ID"
        }
      }
    }
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us