Sandbox

Sandbox mode gives you an isolated test environment to build and validate your integration before going to production. Sandbox tenants have a 1,000 entity limit and can be reset at any time without affecting production data.

How it works

Sandbox tenants are identified by test API keys prefixed with kn_test_. All API endpoints work identically in sandbox mode - same request format, same response format, same matching engine. The only differences are the entity limit and the availability of the reset endpoint.

Check sandbox status

See your current usage against the sandbox limit.

curl

curl https://api.kanoniv.com/v1/sandbox/status \
  -H "X-API-Key: kn_test_..."

Python

from kanoniv import Client

client = Client(api_key="kn_test_...")
status = client.sandbox.status()
print(status)

TypeScript

import { KanonivClient } from '@kanoniv/sdk';

const client = new KanonivClient({ apiKey: 'kn_test_...' });
const status = await client.sandbox.status();
console.log(status);

Go

client := kanoniv.NewClient(kanoniv.WithAPIKey("kn_test_..."))
status, err := client.Sandbox.Status(ctx)
fmt.Printf("Sandbox: %v, Entities: %d/%d\n", status.IsSandbox, status.EntityCount, status.EntityLimit)

Response (200 OK):

{
  "is_sandbox": true,
  "entity_count": 247,
  "entity_limit": 1000,
  "source_count": 3
}

Field	Type	Description
is_sandbox	boolean	Always true for sandbox tenants.
entity_count	integer	Current number of external entities.
entity_limit	integer	Maximum entities allowed (1,000).
source_count	integer	Number of data sources.

Reset sandbox

Wipe all data in your sandbox and start fresh. This deletes all entities, sources, specs, jobs, webhooks, and related data. The operation is atomic - either everything is deleted or nothing is.

curl

curl -X POST https://api.kanoniv.com/v1/sandbox/reset \
  -H "X-API-Key: kn_test_..."

Python

result = client.sandbox.reset()
print(result)  # {"message": "Sandbox data cleared successfully.", "entities_deleted": 247}

TypeScript

const result = await client.sandbox.reset();
console.log(result.message, result.entities_deleted);

Go

result, err := client.Sandbox.Reset(ctx)
fmt.Printf("%s (%d deleted)\n", result.Message, result.EntitiesDeleted)

Response (200 OK):

{
  "message": "Sandbox data cleared successfully.",
  "entities_deleted": 247
}

The reset clears all tenant data including:

• External entities and canonical entities
• Identity links and merge history
• Match audit records and feedback labels
• Webhooks and webhook deliveries
• Jobs and batch runs
• Data sources and identity plans
• Entity events
• Redis reverse index cache

Access control

Sandbox endpoints are only accessible with test API keys (kn_test_ prefix). Calling these endpoints with a production key returns a 400 error:

{
  "type": "https://api.kanoniv.com/errors/bad-request",
  "title": "Bad request",
  "status": 400,
  "detail": "This endpoint is only available for sandbox tenants. Use a kn_test_ API key."
}

Best practices

1. Use sandbox for integration testing. Build and test your webhook handlers, ingestion pipelines, and reconciliation workflows against sandbox before connecting to production.

2. Reset between test runs. Call the reset endpoint at the start of each test suite to ensure a clean slate.

3. Test with realistic data volumes. The 1,000 entity limit is enough to validate matching rules, survivorship policies, and edge cases without requiring a paid plan.

4. Use idempotency keys in sandbox too. Test your retry logic and idempotency key generation in sandbox to catch issues before production.

Endpoints

Method	Path	Description
GET	/v1/sandbox/status	Check sandbox usage and limits
POST	/v1/sandbox/reset	Delete all sandbox data