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:

Endpoint

V2 uses a single versioned endpoint:

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:

Terminology Changes

V2 uses entity/trait terminology consistently:

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)

// 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"]
}

CSV column mapping for resolution (lookup_columns)

Both entity_resolve and resolve_and_enrich_rows accept a CSV via csv_resource_uri. To tell the resolver which columns hold which identifier types, V2 uses a unified lookup_columns object. Earlier V2 betas exposed flat email_columns / phone_columns / address_columns / name_columns / linkedin_columns parameters; those are now rejected with a per-key error naming the lookup_columns.<key> replacement. Update existing callers to the nested shape:

// Earlier V2 beta — now rejected
{
  "email_columns": ["email"],
  "phone_columns": ["phone"],
  "address_columns": ["address1", "city", "state", "zip"]
}

// V2
{
  "lookup_columns": {
    "email":   { "names": ["email"] },
    "phone":   { "names": ["phone"] },
    "address": { "names": ["address1", "city", "state", "zip"] }
  }
}

lookup_columns also adds two identifier types not previously available:

• linkedin — resolves via social:linkedin (full URLs or bare slugs).
• domain — resolves businesses via website (bare domains or full URLs).

See Conventions → CSV Column Mapping for the full schema, multi-column address joining rules, and the address_parse_low_yield warning.

entity_enrich (was get_person)

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

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

entity_find (was find_persons)

// 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 browsing (was list_clusters)

list_clusters is replaced by trait:// MCP resources. Use resources_read with trait://person or trait://business URIs, with optional ?domain= and ?limit= query parameters.

trait_get (was get_cluster)

Output Changes

Field Renaming

All output fields follow the new terminology:

Workflow ID

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

New Tools

V2 introduces several tools with no V1 equivalent:

entity_relations

Find related entities using directional source → target queries (e.g., find employers of a person, or employees of a business).

{
  "source_entity_type": "person",
  "source_entity_ids": ["12345"],
  "relationship": "employs",
  "target_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-e29b-41d4-a716-446655440000/uploads/customers.csv",
  "lookup_columns": { "email": { "names": ["email"] } },
  "domains": ["demographic", "interest"],
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}

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

1. Update endpoint URLs from /v1/mcp to /v2/mcp
2. Rename all tool calls per the tool renaming table
3. Add entity_type to all tool calls
4. Update identifier parameters (multi_identifiers → identifiers, person_ids → entity_ids)
5. Update expression syntax (remove cluster_hash: prefix, use trait hashes directly)
6. Update output parsing for renamed fields (person_id → entity_id, etc.)
7. Test export workflows — format options are the same (csv, json, jsonl)
8. 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