Create Workspace Data Definition

POST

workspaces

{workspace_id}

data-definitions

curl --request POST \
  --url https://platform-us.mixpanel.com/v1/workspaces/{workspace_id}/data-definitions \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "event_name": "<string>",
  "description": "<string>",
  "display_name": "<string>",
  "tags": [
    "<string>"
  ],
  "owners": [
    {
      "id": "<string>"
    }
  ]
}
'

import requests

url = "https://platform-us.mixpanel.com/v1/workspaces/{workspace_id}/data-definitions"

payload = {
    "name": "<string>",
    "event_name": "<string>",
    "description": "<string>",
    "display_name": "<string>",
    "tags": ["<string>"],
    "owners": [{ "id": "<string>" }]
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    event_name: '<string>',
    description: '<string>',
    display_name: '<string>',
    tags: ['<string>'],
    owners: [{id: '<string>'}]
  })
};

fetch('https://platform-us.mixpanel.com/v1/workspaces/{workspace_id}/data-definitions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://platform-us.mixpanel.com/v1/workspaces/{workspace_id}/data-definitions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'event_name' => '<string>',
    'description' => '<string>',
    'display_name' => '<string>',
    'tags' => [
        '<string>'
    ],
    'owners' => [
        [
                'id' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://platform-us.mixpanel.com/v1/workspaces/{workspace_id}/data-definitions"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"event_name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"owners\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://platform-us.mixpanel.com/v1/workspaces/{workspace_id}/data-definitions")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"event_name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"owners\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://platform-us.mixpanel.com/v1/workspaces/{workspace_id}/data-definitions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"event_name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"owners\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "name": "<string>",
  "event_name": "<string>",
  "display_name": "<string>",
  "description": "<string>",
  "status": "visible",
  "verified": true,
  "last_verified_at": "2023-11-07T05:31:56Z",
  "last_verified_by": {
    "type": "user",
    "id": "<string>",
    "display_name": "<string>"
  },
  "tags": [
    "<string>"
  ],
  "owners": [
    {
      "type": "user",
      "id": "<string>",
      "display_name": "<string>",
      "resolved": true
    }
  ],
  "merged_into": {
    "id": "<string>",
    "name": "<string>"
  },
  "first_tracked_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "type": "event",
  "definition": null
}

{
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "instance": "<string>",
  "detail": "<string>",
  "error_id": "<string>",
  "errors": [
    {
      "type": "<string>",
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "ctx": {}
    }
  ]
}

{
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "instance": "<string>",
  "detail": "<string>",
  "error_id": "<string>"
}

Closed Beta
Available to a limited set of invited customers. Contact your account team to join. The request and response contract may change before general availability (GA).

Authorizations

Authorization

string

header

required

This endpoint uses Service Account authentication.

Headers

Mixpanel-Version

string

default:2026-08-13

Optional date-based API version pin.

If omitted, the request is served by the latest API version, and the caller accepts that a future release may introduce a breaking change to the response contract. If set to a supported version date, that version's contract is honored and will not receive a breaking change.

Idempotency-Key

string

Optional, client-provided key guaranteeing the operation is idempotent on success: if a request is replayed, the response includes Idempotent-Replayed: true.

Reusing a key with a different request body, or while a request with the same key is still in flight, returns a 409.

Use a unique, random value for each request (a UUID v4 works well).

Maximum string length: 255

Path Parameters

workspace_id

string

required

The unique identifier for the workspace.

Body

application/json

CreateDataDefinitionWithoutBodyRequest
CreateCustomEventDataDefinitionRequest
CreateCustomPropertyDataDefinitionRequest
CreateBehaviorDataDefinitionRequest
CreateMetricDataDefinitionRequest
CreateCohortDataDefinitionRequest

An event or event property, which has no definition body.

name

string

required

The definition's name.

Required string length: 1 - 255

type

enum<string>

required

The kind of definition.

Available options:

event,

event_property

event_name

string | null

The parent event of an event property.

Maximum string length: 255

description

string | null

The definition's description.

display_name

string | null

The name shown in the UI.

Maximum string length: 255

Response

Created

An event or event property, which has no definition body.

string

required

Opaque definition ID, stable across renames.

name

string

required

The definition's name.

event_name

string | null

required

The parent event of an event property.

display_name

string | null

required

The name shown in the UI.

description

string | null

required

The definition's description.

status

enum<string>

required

Whether the definition is visible, hidden, or blocked.

Available options:

visible,

hidden,

blocked

verified

boolean

required

Whether the definition is verified.

last_verified_at

string<date-time> | null

required

When the definition was last verified.

last_verified_by

DataDefinitionVerifier · object | null

required

Who last verified the definition.

Show child attributes

tags

string[]

required

The definition's tag names.

owners

DataDefinitionOwner · object[]

required

The definition's owners.

Show child attributes

merged_into

DataDefinitionSummary · object | null

required

The definition this one is merged into.

Show child attributes

first_tracked_at

string<date-time> | null

required

When data for the definition was first seen.

created_at

string<date-time>

required

When the definition was created.

updated_at

string<date-time>

required

When the definition was last updated.

type

enum<string>

required

The kind of definition.

Available options:

event,

event_property

definition

null

required

Always null for this kind of definition.

Create Workspace Data Definition

curl --request POST \
  --url https://platform-us.mixpanel.com/v1/workspaces/{workspace_id}/data-definitions \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "event_name": "<string>",
  "description": "<string>",
  "display_name": "<string>",
  "tags": [
    "<string>"
  ],
  "owners": [
    {
      "id": "<string>"
    }
  ]
}
'

import requests

url = "https://platform-us.mixpanel.com/v1/workspaces/{workspace_id}/data-definitions"

payload = {
    "name": "<string>",
    "event_name": "<string>",
    "description": "<string>",
    "display_name": "<string>",
    "tags": ["<string>"],
    "owners": [{ "id": "<string>" }]
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    event_name: '<string>',
    description: '<string>',
    display_name: '<string>',
    tags: ['<string>'],
    owners: [{id: '<string>'}]
  })
};

fetch('https://platform-us.mixpanel.com/v1/workspaces/{workspace_id}/data-definitions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://platform-us.mixpanel.com/v1/workspaces/{workspace_id}/data-definitions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'event_name' => '<string>',
    'description' => '<string>',
    'display_name' => '<string>',
    'tags' => [
        '<string>'
    ],
    'owners' => [
        [
                'id' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://platform-us.mixpanel.com/v1/workspaces/{workspace_id}/data-definitions"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"event_name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"owners\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://platform-us.mixpanel.com/v1/workspaces/{workspace_id}/data-definitions")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"event_name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"owners\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://platform-us.mixpanel.com/v1/workspaces/{workspace_id}/data-definitions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"event_name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"owners\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "name": "<string>",
  "event_name": "<string>",
  "display_name": "<string>",
  "description": "<string>",
  "status": "visible",
  "verified": true,
  "last_verified_at": "2023-11-07T05:31:56Z",
  "last_verified_by": {
    "type": "user",
    "id": "<string>",
    "display_name": "<string>"
  },
  "tags": [
    "<string>"
  ],
  "owners": [
    {
      "type": "user",
      "id": "<string>",
      "display_name": "<string>",
      "resolved": true
    }
  ],
  "merged_into": {
    "id": "<string>",
    "name": "<string>"
  },
  "first_tracked_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "type": "event",
  "definition": null
}

{
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "instance": "<string>",
  "detail": "<string>",
  "error_id": "<string>",
  "errors": [
    {
      "type": "<string>",
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "ctx": {}
    }
  ]
}

{
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "instance": "<string>",
  "detail": "<string>",
  "error_id": "<string>"
}

MIXPANEL APIs

INGESTION API

IDENTITY API

QUERY API

EVENT EXPORT API

LEXICON SCHEMAS API

DATA PIPELINES API

SERVICE ACCOUNTS API

ANNOTATIONS API

GDPR API

WAREHOUSE CONNECTORS API

FEATURE FLAGS API

FEATURE FLAGS MANAGEMENT API

EXPERIMENTS API

PLATFORM API

Create Workspace Data Definition

Authorizations

Headers

Path Parameters

Body

Response