Upgrading to v2

This guide covers breaking changes, renamed tools, and migration steps for upgrading from v1 to v2 of the Watt API.

Migration Checklist

Address these changes in priority order:

Priority	Change	Action
1	Endpoint change	Update from `/v1/mcp` to `/v2/mcp`
2	Tool renaming	Update all tool names in your integration
3	Terminology changes	Update field references: person → entity, cluster → trait
4	Parameter changes	Update input parameters to match new schemas
5	Output changes	Update response parsing for new field names
6	New tools	Adopt new tools for improved workflows

Endpoint

V2 uses a single versioned endpoint:

Version	Endpoint
V1	`/v1/mcp`
V2	`/v2/mcp`

Authentication methods (OAuth, API key) remain the same. Only the path changes. Note that V2 does not have a separate /m2m endpoint — the /v2/mcp endpoint accepts both OAuth and API key authentication.

Tool Renaming

Every core tool has been renamed in V2:

V1 Tool	V2 Tool	Purpose
`resolve_identities`	`entity_resolve`	Identity resolution
`get_person`	`entity_enrich`	Profile enrichment
`find_persons`	`entity_find`	Audience discovery
`list_clusters`	`trait_list`	Browse traits by domain
`get_cluster`	`trait_get`	Trait analytics
`search_clusters`	`trait_search`	Semantic trait search
`generate_url_for_upload`	`generate_upload_url`	Presigned upload URL
`generate_download_url`	`generate_download_url`	Presigned download URL
`submit_feedback`	`submit_feedback`	Feedback submission (unchanged)

Terminology Changes

V2 uses entity/trait terminology consistently:

V1 Term	V2 Term	Description
`person`	`entity`	An individual or business record
`person_id`	`entity_id`	Unique identifier for a record
`cluster`	`trait`	A behavioral or demographic attribute
`cluster_id`	`trait_id`	Numeric trait identifier
`cluster_hash`	`trait_hash`	Stable string trait identifier
`cluster_name`	`trait_name`	Human-readable trait name
`multi_identifiers`	`identifiers`	Multi-criterion identifier array

entity_type Parameter

V2 tools require an entity_type parameter ("person" or "business") on most tools. V1 tools implicitly operated on persons only.

// V1
{ "person_ids": ["12345", "12346"] }

// V2
{ "entity_type": "person", "entity_ids": ["12345", "12346"] }

Parameter Changes

entity_resolve (was resolve_identities)

Change	V1	V2
Identifier array	`multi_identifiers`	`identifiers`
Output contact types	N/A	`identifier_types` (default: `["email"]`)
Entity type	Implicit (person)	`entity_type` required

// V1
{
  "multi_identifiers": [
    { "id_type": "email", "hash_type": "plaintext", "values": ["jane@acme.com"] }
  ]
}

// V2
{
  "entity_type": "person",
  "identifiers": [
    { "id_type": "email", "hash_type": "plaintext", "values": ["jane@acme.com"] }
  ],
  "identifier_types": ["email", "phone"]
}

entity_enrich (was get_person)

Change	V1	V2
ID parameter	`person_ids`	`entity_ids`
Entity type	Implicit	`entity_type` required
CSV input	N/A	`csv_resource_uri` + `entity_id_column`

// V1
{ "person_ids": ["12345"], "domains": ["demographic", "interest"] }

// V2
{
  "entity_type": "person",
  "entity_ids": ["12345"],
  "domains": ["demographic", "interest"]
}

entity_find (was find_persons)

Change	V1	V2
Criteria	`expression` with cluster IDs/hashes	`expression` with trait IDs/hashes
Export identifiers	`export_identifiers`	`identifier_type` or `identifier_types`
Location unit	`radius_km`	`radius` + `unit` (km or miles)
Entity type	Implicit	`entity_type` required

// V1
{
  "expression": "cluster_hash:abc123 AND cluster_hash:def456",
  "location": { "latitude": 37.77, "longitude": -122.42, "radius_km": 5 },
  "export_identifiers": ["email", "phone"]
}

// V2
{
  "entity_type": "person",
  "expression": "abc123 AND def456",
  "location": { "latitude": 37.77, "longitude": -122.42, "radius": 5, "unit": "km" },
  "identifier_types": ["email", "phone"]
}

Note: V2 expressions use trait hashes directly without the cluster_hash: prefix.

trait_list (was list_clusters)

Change	V1	V2
Domain filter	`domain` (single)	`domains` (array)
ID lookup	`cluster_ids`	`trait_ids`, `trait_hashes`, or `trait_names`
Include all	N/A	`include_all` flag
Entity type	Implicit	`entity_type` required

trait_get (was get_cluster)

Change	V1	V2
ID parameter	`cluster_id` or `cluster_hash`	`trait_id`, `trait_hash`, or `trait_name` + `domain`
Analytics	Always full	`analytics_depth` (`summary` or `full`)
Entity type	Implicit	`entity_type` required

Output Changes

Field Renaming

All output fields follow the new terminology:

V1 Output Field	V2 Output Field
`person_id`	`entity_id`
`cluster_id`	`trait_id`
`cluster_hash`	`trait_hash`
`cluster_name`	`trait_name`
`cluster_value`	`trait_value`
`cluster_domain`	`domain`
`persons` / `results`	`entities` / `sample`

Workflow ID

V2 always returns workflow_id and tool_trace_id in every response (via BaseToolOutputSchema). Pass workflow_id between related calls for session tracking.

New Tools

V2 introduces several tools with no V1 equivalent:

entity_relations

Find parent-child relationships between entities (e.g., people at a company, subsidiaries of a business).

{
  "entity_type": "person",
  "entity_ids": ["12345"],
  "relationship": "parent",
  "related_entity_type": "business"
}

See entity_relations.

resolve_and_enrich_rows

Streaming CSV pipeline that combines identity resolution and enrichment in a single operation. Replaces the manual resolve_identities → get_person pattern for CSV workflows.

{
  "entity_type": "person",
  "csv_resource_uri": "workflow://550e8400.../uploads/customers.csv",
  "email_columns": ["email"],
  "domains": ["demographic", "interest"]
}

See resolve_and_enrich_rows.

geocode_location

Convert location descriptions to coordinates for use with location filters.

{
  "location": "San Francisco, CA"
}

See geocode_location.

Watt SDK

V2 introduces the @wattdata/sdk package for building agentic workflows. Built on Vercel's AI SDK v6, the SDK connects to Watt's MCP tools — you provide API keys, and the agent handles tool discovery, orchestration, and multi-step reasoning.

See the SDK Integration guide for full documentation.

ICP Analysis Workflow Changes

The V1 analyze_customers tool has been decomposed into two composable steps in V2:

V1 (single tool):

analyze_customers (upload CSV → resolve → enrich → group → analyze)

V2 (composable pipeline):

entity_resolve → group_entities_by_trait → calculate_trait_lift → entity_find

This gives you more control over each step and allows reusing intermediate results. See the ICP Analysis guide for the full V2 workflow.

Testing Your Migration

Update endpoint URLs from /v1/mcp to /v2/mcp
Rename all tool calls per the tool renaming table
Add entity_type to all tool calls
Update identifier parameters (multi_identifiers → identifiers, person_ids → entity_ids)
Update expression syntax (remove cluster_hash: prefix, use trait hashes directly)
Update output parsing for renamed fields (person_id → entity_id, etc.)
Test export workflows — format options are the same (csv, json, jsonl)
Verify location filters — now use radius + unit instead of radius_km

Getting Help

If you encounter issues during migration:

Review the MCP Tool Reference for updated schemas
Check error messages for specific validation details
Use submit_feedback to report data quality issues
Contact support for integration assistance

On this page