API Integration

This guide covers best practices for integrators using the Watt Data MCP tools as a direct JSON-RPC API rather than through an LLM client like Claude Desktop.

API Endpoints

The API supports versioned endpoints:

• /v1/mcp - Versioned endpoint (recommended)
• /v1/mcp/m2m - Versioned M2M endpoint (recommended)
• /mcp - Legacy endpoint (supported for backward compatibility)
• /mcp/m2m - Legacy M2M endpoint (supported for backward compatibility)

Use versioned endpoints for new integrations to ensure stability across API updates.

Data Volatility Guidelines

Understanding data volatility is critical for building reliable integrations. Different identifiers have different stability characteristics and caching requirements.

Cluster IDs and Hashes

Cluster data can be referenced in two ways:

Cluster Hash (Recommended):

• cluster_hash is a stable hash based on domain, name, and value
• Does not change when the identity graph is reprocessed
• Safe to cache and use in saved queries
• Returned by list_clusters and search_clusters

Cluster ID (Legacy):

• cluster_id is a numeric identifier that may change during data reprocessing
• Subject to volatility when new signals are integrated or data is updated
• Use only for immediate queries, not for long-term storage

Recommended Approach - Use search_clusters:

Use the search_clusters tool to discover clusters on-demand using natural language descriptions. This provides the most flexibility and automatically adapts to data changes without caching concerns.

If Caching Clusters:

When building saved queries or long-term integrations:

• Use cluster_hash for stable references
• Cache cluster_hash values indefinitely
• If using cluster_id, cache for at most 1 hour
• Implement empty-result detection logic that refreshes from list_clusters or search_clusters

Person IDs

Person IDs should be treated as subject to change at any time. They must never be cached or persisted.

Requirements:

• Do not cache person IDs
• Do not persist person IDs
• Do not use person IDs as stable references
• Always use original identifiers (email, phone, address, MAID) as stable keys

To Retrieve Updated Information:

Call resolve_identities with the original identifiers to obtain current person IDs for each query.

Why This Matters:

Person IDs may change as the identity graph is updated. Storing person IDs leads to stale references that point to incorrect or non-existent records.

Integration Best Practices

Stateless Query Patterns

1. Use search_clusters for cluster discovery - Describe your target audience in natural language instead of maintaining cluster mappings
2. Resolve identities at query time - Never cache person IDs; resolve fresh for each query
3. Use original identifiers as stable keys - Email, phone, address are your persistent references
4. Use cluster_hash for saved queries - Store cluster references using stable hashes instead of volatile IDs
5. Treat each API session as independent - Minimal state should persist between queries

Recommended Workflow

For audience discovery:

1. Use search_clusters with natural language description of target audience
2. Extract cluster IDs from results
3. Use cluster IDs in find_persons boolean expressions
4. Export results if needed (CSV, JSON, JSONL)

For identity enrichment:

1. Call resolve_identities with email, phone, or address
2. Extract person IDs from resolution results
3. Call get_person with person IDs and desired domains
4. Use enriched data immediately (do not persist person IDs)

Error Recovery

1. On empty results from search_clusters, try broader or alternative query terms
2. On "cluster not found" errors, refresh cluster cache and retry
3. On empty results from get_person, re-resolve identities and retry
4. Implement exponential backoff for transient failures

Workflow Sessions

Use workflow_id to correlate related queries within a single user interaction, but do not persist workflow state beyond the immediate session.

Next Steps

• Review Getting Started for authentication, workflow sessions, and export formats
• Explore individual tool documentation for detailed parameters and examples
• Review workflow guides for complete implementation examples