Skip to main content
The Twin API turns an agent trace into a synthetic twin. Every value that identifies a person, a private organisation, an account or a secret is replaced at every place it occurs with one consistent synthetic value of the same kind. The trace’s structure and format are kept. One trace file in, one twinned file out, in the same format.

​
Base URL

Twin is one tool of the Kennet API, served under that base URL. Requests and responses are JSON, except the upload (multipart) and the twin’s content (the file itself). The OpenAPI document is at https://api.metaphi.ai/v1/kennet/openapi.json and needs no key.

​
Versioning

The API has one dated version, 2026-10-11. Every response carries the header Metaphi-Version: 2026-10-11, and webhook events carry "api_version": "2026-10-11". You may send Metaphi-Version on a request to pin the version you built against. An unknown value is refused with 400 unknown_api_version. If you send no header, the request runs on the current version.

​
Authentication

Send your secret key as a bearer token on every request:
Keep keys on your server. A key needs access to twins, or every request answers 403 insufficient_scope. A revoked key stops working within a minute.

​
Test mode

A test key runs the real pipeline at no charge. Test mode differs from live in four ways:
  • Each file is at most 256 KiB.
  • An organization starts at most 20 test runs in 24 hours.
  • Every object says "livemode": false.
  • Test and live are kept apart. A test key never sees live twins, webhook endpoints or idempotency keys, and a live key never sees test ones.

​
Limits

Going over a run limit answers 429 with a Retry-After header. Ask your account contact to raise your organization’s limits.

​
Quickstart

A trace takes a few minutes. Poll with backoff, starting at a few seconds, or register a webhook to be told when it ends.