Analytics Governance

Analytics Governance defines and validates the event taxonomy that product teams and agents use before data reaches dashboards or BI workflows.

What it does

The module stores workspace tracking-plan definitions for events, properties, owners, validation rules, and change history. It is separate from Data & Insights: governance describes what should be tracked, while Data & Insights stores Object Analytics, insight views, Custom BI assets, exports, and scheduled artifact definitions.

Public capabilities

Define analytics events.
Define reusable event properties.
List event definitions by owner or query.
Validate event payloads against the workspace tracking plan.
Keep governance changes tenant-scoped, audited, and available through REST and MCP.

Permissions

Use analytics:read to list event and property definitions. Use analytics:write to define events, define properties, and validate event payloads.

MCP tools

define_event

Define an analytics event in the workspace tracking plan.

MVP

Idempotent writesNo dry runStrict schema

Required scopes: analytics:write
API equivalent: POST /v1/analytics/events

Example prompt

Define an activation event called first_contact_created.

Input schema

Property	Type	Required	Description
name	string	Yes	Event name, such as workspace_created.
description	string	No	Human-readable event purpose.
owner	string	No	Person or team responsible for the event definition.
properties	array	No	Property keys expected on the event.
idempotency_key	string	No	Stable client-generated key that makes retries safe for this write.

Additional properties are rejected.

Example input

{
  "name": "first_contact_created",
  "description": "A workspace created its first CRM contact.",
  "owner": "growth",
  "properties": [
    "tenant_id",
    "workspace_id",
    "source"
  ]
}

Example response

{
  "event": {
    "id": "evt_123",
    "name": "first_contact_created"
  },
  "request_id": "req_139"
}

Common errors

missing_required_scopeHTTP 403

The token does not include the scope required for this operation.

validation_failedHTTP 422

The request payload failed schema validation.

idempotency_conflictHTTP 409

The idempotency key was reused with a different request body.

list_events

List analytics event definitions in the workspace tracking plan.

MVP

Read operationNo dry runStrict schema

Required scopes: analytics:read
API equivalent: GET /v1/analytics/events

Example prompt

List activation events owned by growth.

Input schema

Property	Type	Required	Description
query	string	No	Free-text search across event names and descriptions.
owner	string	No	Restrict results to one owner.
limit	integer · min 1 · max 100	No	Maximum number of events to return.
cursor	string	No	Opaque cursor from a previous response's next_cursor.

Additional properties are rejected.

Example input

{
  "owner": "growth",
  "limit": 25
}

Example response

{
  "events": [
    {
      "id": "evt_123",
      "name": "first_contact_created",
      "owner": "growth"
    }
  ],
  "request_id": "req_140"
}

Common errors

missing_required_scopeHTTP 403

The token does not include the scope required for this operation.

validation_failedHTTP 422

The request payload failed schema validation.

define_property

Define a reusable analytics property for the tracking plan.

MVP

Idempotent writesNo dry runStrict schema

Required scopes: analytics:write
API equivalent: POST /v1/analytics/properties

Example prompt

Define workspace_id as a required string property.

Input schema

Property	Type	Required	Description
key	string	Yes	Property key used in tracked events.
type	string · string \| number \| boolean \| datetime \| object \| array	Yes	Expected property value type.
description	string	No	Human-readable property meaning.
required	boolean · default false	No	Whether this property is required when associated with an event.
idempotency_key	string	No	Stable client-generated key that makes retries safe for this write.

Additional properties are rejected.

Example input

{
  "key": "workspace_id",
  "type": "string",
  "description": "Workspace identifier associated with the event.",
  "required": true
}

Example response

{
  "property": {
    "id": "prop_123",
    "key": "workspace_id",
    "type": "string"
  },
  "request_id": "req_141"
}

Common errors

missing_required_scopeHTTP 403

The token does not include the scope required for this operation.

validation_failedHTTP 422

The request payload failed schema validation.

idempotency_conflictHTTP 409

The idempotency key was reused with a different request body.

validate_event

Validate an event payload against the workspace tracking plan.

MVP

Read operationNo dry runStrict schema

Required scopes: analytics:read
API equivalent: POST /v1/analytics/events/validate

Example prompt

Validate a first_contact_created event payload.

Input schema

Property	Type	Required	Description
name	string	Yes	Event name to validate.
properties	object	Yes	Event payload properties to validate.

Additional properties are rejected.

Example input

{
  "name": "first_contact_created",
  "properties": {
    "tenant_id": "ten_123",
    "workspace_id": "wrk_123",
    "source": "mcp"
  }
}

Example response

{
  "valid": true,
  "errors": [],
  "request_id": "req_142"
}

Common errors

missing_required_scopeHTTP 403

The token does not include the scope required for this operation.

validation_failedHTTP 422

The request payload failed schema validation.

resource_not_foundHTTP 404

The requested resource does not exist in this workspace.