API Quickstart

Resolve your first entity in 60 seconds. All you need is an API key.

Prerequisites

• A Kanoniv API key (sign up for a free sandbox)

1. Resolve an entity

Send a record. The engine creates a canonical entity and returns its ID.

curl

curl -X POST https://api.kanoniv.com/v1/resolve/realtime \
  -H "X-API-Key: kn_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source_name": "crm",
    "external_id": "contact_123",
    "data": {
      "email": "[email protected]",
      "name": "John Smith",
      "company": "Acme Labs"
    }
  }'

Python

from kanoniv import Client

client = Client(api_key="kn_...")
result = client.resolve_rt.realtime(
    source_name="crm",
    external_id="contact_123",
    data={"email": "[email protected]", "name": "John Smith", "company": "Acme Labs"},
)
print(result.entity_id, result.is_new)  # 550e8400-... True

Response:

{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_new": true,
  "confidence": 1.0,
  "version": 1
}

2. Resolve the same person from a different source

A billing agent sends the same person. The engine matches to the existing entity.

curl -X POST https://api.kanoniv.com/v1/resolve/realtime \
  -H "X-API-Key: kn_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source_name": "stripe",
    "external_id": "cus_8847",
    "data": {
      "email": "[email protected]",
      "name": "J. Smith",
      "company": "ACME LABS INC"
    }
  }'

{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_new": false,
  "confidence": 0.95,
  "version": 2
}

Same entity_id. The engine matched on email (exact) and company (fuzzy). Two sources, one entity.

3. Mutate the entity

Update fields with optimistic locking. Pass expected_version to prevent silent overwrites.

curl -X PATCH https://api.kanoniv.com/v1/entities/550e8400-.../mutate \
  -H "X-API-Key: kn_..." \
  -H "Content-Type: application/json" \
  -d '{
    "patch": { "title": "CEO" },
    "expected_version": 2
  }'

{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "version": 3,
  "mutation_type": "update_fields"
}

If another agent updated the entity between your read and write, you get a 409 Conflict with the current version. Retry with the new version - no data loss.

4. Look up an entity

Query by source and external ID:

curl https://api.kanoniv.com/v1/resolve?system=crm&id=contact_123 \
  -H "X-API-Key: kn_..."

Or look up in bulk (up to 1,000 at once):

curl -X POST https://api.kanoniv.com/v1/resolve/bulk \
  -H "X-API-Key: kn_..." \
  -H "Content-Type: application/json" \
  -d '{
    "lookups": [
      {"source_name": "crm", "external_id": "contact_123"},
      {"source_name": "stripe", "external_id": "cus_8847"}
    ]
  }'

5. Check stats

CLI

pip install kanoniv[cloud]
kanoniv login
kanoniv stats

curl

curl https://api.kanoniv.com/v1/stats \
  -H "X-API-Key: kn_..."

Next steps

• API Reference - Full endpoint documentation
• Python SDK - Client library with typed responses
• MCP Server - Give AI agents identity primitives
• Mutations & Versioning - Optimistic locking and entity history
• Events - Subscribe to identity state transitions