REST API for managing data plans and data plan versions in a workspace, and for validating an event batch against a plan without ingesting it. Each plan version is a set of data points, where a data point is a match rule plus a JSON Schema validator. OAuth 2.0 client-credentials bearer auth.
openapi: 3.0.2
info:
title: mParticle Data Planning API
version: 2.0.0
contact:
email: product@mparticle.com
url: 'https://www.mparticle.com/contact'
name: mParticle Developer Experience
description: The Data Planning API for mParticle.com
termsOfService: 'https://www.mparticle.com/legal/website-terms-of-service/'
servers:
- url: 'https://api.mparticle.com/platform/v2/workspaces/{workspace_id}/plans'
variables:
workspace_id:
default: '0'
description: The Id of the worskspace that contains the targetted data plans
security:
- bearerAuth: []
tags:
- name: Data Plan
description: Endpoints for managing Data Plans
- name: Data Plan Version
description: Endpoints for versioning Data Plans
paths:
/:
get:
description: Query all data plans
operationId: get-plans
tags:
- Data Plan
responses:
'200':
$ref: '#/components/responses/DataPlanListResponse'
'400':
description: Bad Request
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Not Found
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Get All Plans
post:
description: Create a data plan
operationId: create-plan
tags:
- Data Plan
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DataPlan'
examples: {}
responses:
'200':
$ref: '#/components/responses/DataPlanVersionResponse'
'400':
$ref: '#/components/responses/BadSchema'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Create Data Plan
parameters: []
'/{plan_id}':
get:
description: 'Get a single data plan '
operationId: get-plan
tags:
- Data Plan
parameters:
- $ref: '#/components/parameters/plan_id'
responses:
'200':
$ref: '#/components/responses/DataPlanResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Get a Single Plan
delete:
description: Delete a single plan
operationId: delete-plan
tags:
- Data Plan
parameters:
- $ref: '#/components/parameters/plan_id'
responses:
'204':
description: Empty response
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/DataPlanNotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Delete Data Plan
patch:
description: Update a plan
operationId: update-plan
tags:
- Data Plan
parameters:
- $ref: '#/components/parameters/plan_id'
responses:
'200':
$ref: '#/components/responses/DataPlanResponse'
'400':
$ref: '#/components/responses/BadSchema'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/DataPlanNotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
requestBody:
content:
application/json:
schema:
description: ''
type: object
x-examples:
example-1:
data_plan_name: description
properties:
data_plan_name:
type: string
data_plan_description:
type: string
description: ''
summary: Update Data Plan
'/{plan_id}/versions/{plan_version}':
get:
description: Get a single plan version
operationId: get-plan-version
tags:
- Data Plan Version
parameters:
- $ref: '#/components/parameters/plan_id'
- $ref: '#/components/parameters/plan_version'
responses:
'200':
$ref: '#/components/responses/DataPlanVersionResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/DataPlanVersionNotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Get a Single Data Plan Version
patch:
description: Update a plan version
operationId: update-plan-version
tags:
- Data Plan Version
parameters:
- $ref: '#/components/parameters/plan_id'
- $ref: '#/components/parameters/plan_version'
responses:
'200':
$ref: '#/components/responses/DataPlanVersionResponse'
'400':
$ref: '#/components/responses/BadSchema'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/DataPlanVersionNotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
requestBody:
content:
application/json:
schema:
type: object
properties:
activated_environment:
$ref: '#/components/schemas/ActivatedEnvironment'
version_description:
type: string
version_document:
$ref: '#/components/schemas/VersionDocument'
quarantine_feed_id:
type: number
description: ''
summary: Update Data Plan Version
delete:
description: Delete a plan version
operationId: delete-plan-version
tags:
- Data Plan Version
parameters:
- $ref: '#/components/parameters/plan_id'
- $ref: '#/components/parameters/plan_version'
responses:
'204':
description: Empty response
'400':
$ref: '#/components/responses/DeletePlanVersionBadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/DataPlanVersionNotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Delete Data Plan Version
'/{plan_id}/versions':
post:
description: Create a data plan version
operationId: create-plan-version
tags:
- Data Plan Version
parameters:
- $ref: '#/components/parameters/plan_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DataPlanVersion'
responses:
'200':
$ref: '#/components/responses/DataPlanVersionResponse'
'400':
$ref: '#/components/responses/BadSchema'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Create a Data Plan Version
/validate:
post:
description: Validate an event batch against a Data Plan document
operationId: validate-plan-document
parameters: []
responses:
'200':
$ref: '#/components/responses/ValidateDataPlanResponse'
'400':
$ref: '#/components/responses/ValidateDataPlanBadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Validate Event Batch
requestBody:
content:
application/json:
schema:
type: object
properties:
document:
$ref: '#/components/schemas/VersionDocument'
batch:
$ref: '#/components/schemas/Mparticle_S2s_Events_Oas_Batch'
tags:
- Data Plan
components:
parameters:
plan_id:
name: plan_id
in: path
description: Slug ID of the data plan
required: true
schema:
type: string
plan_version:
name: plan_version
in: path
description: Version of the plan to fetch
required: true
schema:
type: integer
workspace_id:
name: workspace_id
in: path
description: Workspace ID
required: true
schema:
type: integer
responses:
BadRequest:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorList'
BadSchema:
description: Bad Schema
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/SchemaErrorList'
- $ref: '#/components/schemas/ErrorList'
DataPlanListResponse:
description: Data plan list
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DataPlan'
examples:
example-1:
value:
- data_plan_id: string
data_plan_name: string
created_on: '2019-08-24T14:15:22Z'
created_by: string
last_modified_on: '2019-08-24T14:15:22Z'
last_modified_by: string
description: string
data_plan_versions:
- version: 0
version_description: string
created_on: '2019-08-24T14:15:22Z'
created_by: string
last_modified_on: '2019-08-24T14:15:22Z'
last_modified_by: string
version_document:
data_points:
- description: string
match:
type: unknown
criteria:
screen_name: string
validator:
type: json_schema
definition: {}
active_transformation_ids:
- 0
active_transformation_ids:
- 0
activated_environment: development
DataPlanResponse:
description: Data plan created
content:
application/json:
schema:
$ref: '#/components/schemas/DataPlan'
DataPlanVersionResponse:
description: Data plan version
content:
application/json:
schema:
$ref: '#/components/schemas/DataPlanVersion'
Forbidden:
description: Forbidden
TooManyRequests:
description: Too Many Requests
headers:
Retry-After:
description: Seconds to wait until the next request attempt
schema:
type: integer
Unauthorized:
description: Unauthorized
DataPlanNotFound:
description: Not Found
content:
application/json:
schema:
description: ''
type: object
properties:
errors:
type: array
uniqueItems: true
minItems: 1
items:
required:
- message
properties:
message:
type: string
minLength: 1
required:
- errors
x-examples:
example-1:
errors:
- message: >-
The specified plan ID plan_1 in workspace 1234 was not
found.
examples:
example-1:
value:
errors:
- message: >-
The specified plan ID plan_1 in workspace 1234 was not
found.
headers: {}
DataPlanVersionNotFound:
description: Not Found
content:
application/json:
schema:
description: ''
type: object
x-examples:
example-1:
errors:
- message: >-
The specified version 10 in plan ID plan_1 was not found
in workspace 1234.
properties:
errors:
type: array
uniqueItems: true
minItems: 1
items:
type: object
properties:
message:
type: string
minLength: 1
enum:
- >-
The specified plan ID {plan_id} in workspace
{workspace_id} was not found.
- >-
The specified version {version_id} in plan ID
{plan_id} was not found in workspace {workspace_id}.
required:
- message
required:
- errors
examples:
example-1:
value:
errors:
- message: >-
The specified version 10 in plan ID plan_1 was not found
in workspace 1234.
DeletePlanVersionBadRequest:
description: Example response
content:
application/json:
schema:
description: ''
type: object
properties:
errors:
type: array
uniqueItems: true
minItems: 1
items:
type: object
properties:
message:
type: string
minLength: 1
enum:
- >-
Unable to delete plan version - plans must contain at
least one plan version.
- >-
Unable to delete plan version - this version is active
in prod and cannot be deleted.
- >-
Unable to delete plan version. Plan versions with an
associated quarantine feed can only be deleted through
the UI.
required:
- message
required:
- errors
examples:
example-1:
value:
errors:
- message: >-
Unable to delete plan version - plans must contain at
least one plan version.
ValidateDataPlanBadRequest:
description: Example response
content:
application/json:
schema:
description: ''
type: object
properties:
errors:
type: array
uniqueItems: true
minItems: 1
items:
type: object
properties:
message:
type: string
minLength: 1
enum:
- A required value was missing.
- Invalid Event Batch.
- Invalid Document.
- Account configuration error.
- Invalid data plan document.
- >-
Data plan exceeds maximum of
{max_data_points_per_plan} with {data_points.length}
data points.
required:
- message
required:
- errors
examples:
example-1:
value:
errors:
- message: A required value was missing.
ValidateDataPlanResponse:
description: Example response
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
type: object
properties:
data:
allOf:
- type: object
properties:
match:
$ref: '#/components/schemas/DataPointMatch'
validation_errors:
type: array
items:
type: object
properties:
validation_error_type:
type: string
enum:
- unknown
- unplanned
- missing_required
- invalid_value
key:
type: string
example: event name or attribute name
error_pointer:
type: string
example: '#/data/custom_attributes/foo-attr-1'
expected:
type: string
example: >-
null for unplanned entities, the entity
name for missing required entities, a data
type (e.g. "number") for invalid data
types, etc
actual:
type: string
example: >-
the entity name for unplanned entities,
null for missing required entities, a data
type (e.g. "string") for invalid data
types, etc
action_expected:
type: string
enum:
- unknown
- allow
- drop_event
- drop_attribute
- drop_batch
schema_keyword:
$ref: '#/components/schemas/SchemaKeyword'
validated_event_id:
type: number
validated_source_message_id:
type: string
executed_transformations:
type: object
properties:
transformation_id:
type: number
transformation_status:
type: string
enum:
- success
- failure
- unchanged
- quarantined
transformation_error_type:
type: string
enum:
- valid
- invalid
- unrecognized_data_point
- events_schema_violated
transformation_error_message:
type: string
transformation_error_pointer:
type: string
- $ref: >-
#/components/schemas/Mparticle_S2s_Events_Oas_CommonEventData
batch:
type: object
schemas:
ActivatedEnvironment:
type: string
enum:
- none
- development
- production
description: >-
Data plan can be active in development, production & development (production), or neither.
'none' indicates it's inactive.
Criteria:
anyOf:
- $ref: '#/components/schemas/ScreenViewEventCriteria'
- $ref: '#/components/schemas/CustomEventCriteria'
- $ref: '#/components/schemas/UserAttributeCriteria'
- $ref: '#/components/schemas/CommerceActionEventCriteria'
CustomEventCriteria:
properties:
event_name:
type: string
custom_event_type:
type: string
enum:
- unknown
- navigation
- location
- search
- transaction
- user_content
- user_preference
- social
- other
- media
required:
- event_name
- custom_event_type
DataPlan:
x-examples: {}
type: object
properties:
data_plan_id:
type: string
data_plan_name:
type: string
data_plan_description:
type: string
data_plan_versions:
$ref: '#/components/schemas/DataPlanVersionList'
created_on:
type: string
format: date-time
created_by:
type: string
last_modified_on:
type: string
format: date-time
last_modified_by:
type: string
DataPlanVersion:
type: object
properties:
version:
type: integer
version_description:
type: string
created_on:
type: string
format: date-time
created_by:
type: string
last_modified_on:
type: string
format: date-time
last_modified_by:
type: string
version_document:
$ref: '#/components/schemas/VersionDocument'
activated_environment:
$ref: '#/components/schemas/ActivatedEnvironment'
data_plan_id:
type: string
quarantine_feed_id:
type: number
nullable: true
readOnly: true
DataPlanVersionList:
type: array
items:
$ref: '#/components/schemas/DataPlanVersion'
DataPoint:
type: object
properties:
description:
type: string
match:
$ref: '#/components/schemas/DataPointMatch'
validator:
$ref: '#/components/schemas/DataPointValidator'
required:
- match
- validator
DataPointMatch:
properties:
type:
$ref: '#/components/schemas/MatchType'
criteria:
$ref: '#/components/schemas/Criteria'
required:
- type
- criteria
title: ''
DataPointValidator:
properties:
type:
type: string
default: json_schema
enum:
- json_schema
definition:
type: object
description: This should be a valid JSON schema
required:
- type
- definition
Error:
type: object
properties:
message:
type: string
ErrorList:
type: object
properties:
errors:
type: array
items:
oneOf:
- $ref: '#/components/schemas/Error'
MatchType:
type: string
enum:
- unknown
- screen_view
- custom_event
- user_attributes
- user_identities
- product_action
- promotion_action
- product_impression
SchemaError:
type: object
allOf:
- $ref: '#/components/schemas/Error'
properties:
match_key:
type: string
value:
type: string
schema_pointer:
type: string
event_pointer:
type: string
keyword:
type: string
error_type:
type: string
required:
- message
- match_key
- error_type
SchemaErrorList:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/SchemaError'
ScreenViewEventCriteria:
properties:
screen_name:
type: string
required:
- screen_name
UserAttributeCriteria:
type: object
ValidationErrorType:
type: string
enum:
- unknown
- unplanned
- missing_required
- invalid_value
VersionDocument:
type: object
description: 'This is the actual data plan, since a data plan can have many versions.'
properties:
data_points:
type: array
items:
$ref: '#/components/schemas/DataPoint'
active_transformation_ids:
type: array
items:
type: number
readOnly: true
transformations:
$ref: '#/components/schemas/DataPlanTransformation'
CommerceActionEventCriteria:
title: CommerceActionEventCriteria
type: object
properties:
action:
oneOf:
- $ref: '#/components/schemas/ProductAction'
- $ref: '#/components/schemas/PromotionAction'
description: Data point match criteria object for commerce action events
ProductAction:
type: string
title: ProductAction
enum:
- add_to_cart
- remove_from_cart
- checkout
- checkout_option
- click
- view_detail
- purchase
- refund
- add_to_wishlist
- remove_from_wish_list
PromotionAction:
type: string
title: PromotionAction
enum:
- view
- click
DataPlanTransformation:
title: DataPlanTransformation
type: object
properties:
transformation_id:
type: number
transformation_name:
type: string
error_pointer:
type: string
validation_error_types:
type: array
items:
type: string
enum:
- unknown
- unplanned
- missing_required
- invalid_value
schema_keywords:
type: array
items:
$ref: '#/components/schemas/SchemaKeyword'
json_patch:
type: array
items:
$ref: '#/components/schemas/DataPlanPatch'
description:
type: string
SchemaKeyword:
type: string
title: SchemaKeyword
enum:
- none
- additionalItems
- additionalProperties
- allOf
- anyOf
- const
- contains
- contentEncoding
- contentMediaType
- default
- definitions
- dependencies
- dependentRequired
- dependentSchemas
- else
- enum
- exclusiveMaximum
- exclusiveMinimum
- format
- id
- if
- items
- maxContains
- maximum
- maximum
- maxLength
- maxProperties
- minContains
- minimum
- minItems
- minLength
- minProperties
- multipleOf
- not
- oneOf
- pattern
- patternProperties
- properties
- propertyNames
- readOnly
- required
- then
- type
- unevaluatedItems
- unevaluatedProperties
- uniqueItems
- writeOnly
- $anchor
- $defs
- $id
- $recursiveAnchor
- $recursiveRef
- $ref
- $schema
- $vocabulary
- timeLimit
- $comment
- description
- examples
- title
DataPlanPatch:
title: DataPlanPatch
type: object
properties:
op:
type: string
enum:
- unknown
- add
- remove
- replace
- copy
- move
- test
from:
type: string
path:
type: string
value:
type: string
Mparticle_S2s_Events_Oas_ApplicationInformation:
properties:
application_name:
type: string
application_version:
type: string
application_build_number:
type: string
install_referrer:
type: string
package:
type: string
os:
type: string
default: Unknown
enum:
- Unknown
- IOS
- Android
- WindowsPhone
- MobileWeb
- UnityIOS
- UnityAndroid
- Desktop
- TVOS
- Roku
- OutOfBand
- Alexa
- SmartTV
- FireTV
- Xbox
apple_search_ads_attributes:
type: object
additionalProperties:
type: object
additionalProperties:
type: string
additionalProperties: false
Mparticle_S2s_Events_Oas_AttributionInfo:
properties:
service_provider:
type: string
publisher:
type: string
campaign:
type: string
required:
- service_provider
- publisher
- campaign
additionalProperties: false
Mparticle_S2s_Events_Oas_BaseEvent:
properties:
data:
$ref: '#/components/schemas/Mparticle_S2s_Events_Oas_CommonEventData'
event_type:
$ref: '#/components/schemas/Mparticle_S2s_Events_Oas_EventType'
Mparticle_S2s_Events_Oas_Batch:
additionalProperties: false
type: object
properties:
source_request_id:
type: string
context:
$ref: '#/components/schemas/Mparticle_S2s_Events_Oas_BatchContext'
events:
type: array
description: >-
Provide a list of event objects - such as CustomEvent,
ScreenViewEvent, or CommerceEvent
items:
$ref: '#/components/schemas/Mparticle_S2s_Events_Oas_BaseEvent'
device_info:
$ref: '#/components/schemas/Mparticle_S2s_Events_Oas_DeviceInformation'
application_info:
$ref: '#/components/schemas/Mparticle_S2s_Events_Oas_ApplicationInformation'
user_attributes:
type: object
additionalProperties:
type: object
deleted_user_attributes:
type: array
items:
type: string
user_identities:
type: object
additionalProperties: false
properties:
other:
type: string
customer_id:
type: string
facebook:
type: string
twitter:
type: string
google:
type: string
microsoft:
type: string
yahoo:
type: string
email:
type: string
alias:
type: string
facebook_custom_audience_id:
type: string
other_id_2:
type: string
other_id_3:
type: string
other_id_4:
type: string
other_id_5:
type: string
other_id_6:
type: string
other_id_7:
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mparticle/refs/heads/main/openapi/mparticle-dataplanning-openapi-original.yml