KeySense AI — API Reference

KeySense AI detects keyboard layout errors and corrects them in milliseconds. The API accepts garbled text and returns the corrected version along with the detected layout.

Quick start

Send your first correction request in seconds:

curl -X POST https://api.keysense.tech/detect \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ks_live_..." \
  -d '{"text": "руддщ цщкдв"}'

{
  "decoded":       "hello world",
  "layout":        "ru-RU",
  "confidence":    0.97,
  "ai_used":       false,
  "processing_ms": 1
}

Authentication

All requests require an API key. Pass it in the X-API-Key header. You can generate keys from your dashboard.

# All requests must include this header:
X-API-Key: ks_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

POST /detect

Detect and correct a keyboard layout error in the given text.

Base URL

https://api.keysense.tech

Request body

Response format

{
  "decoded":          "hello world",
  "layout":           "ru-RU",
  "confidence":       0.97,
  "ai_used":          false,
  "processing_ms":    1,
  "word_coverage":    1.0,
  "phrase_coverage":  1.0,
  "keyboard_profile": { "profile": "ansi-104", "confidence": 0.85 },
  "candidates": [
    { "layout": "ru-RU",  "text": "hello world", "confidence": 0.97 },
    { "layout": "uk-UA",  "text": "hello world", "confidence": 0.89 }
  ]
}

Errors

All errors return a JSON body with an error field.

Rate limits

In addition to monthly correction limits, per-second rate limits protect service stability:

When rate limited you will receive a 429 response. Implement exponential back-off with jitter — the SDK does this automatically.

TypeScript / JavaScript SDK

The official SDK wraps the API with full TypeScript types, retry/backoff, and AbortSignal support.

Install

npm install @keysense/sdk
# or
pnpm add @keysense/sdk

Basic usage

import { KeySenseClient } from '@keysense/sdk';

const ks = new KeySenseClient({
  apiKey: process.env.KEYSENSE_API_KEY!,
  // apiUrl defaults to https://api.keysense.tech
});

// Basic correction
const result = await ks.detect('руддщ цщкдв');
console.log(result.decoded);     // "hello world"
console.log(result.layout);      // "ru-RU"
console.log(result.confidence);  // 0.97

// With AI fallback forced
const aiResult = await ks.detect('ηεββο ςορβδ', { useAI: true });
console.log(aiResult.decoded);   // "hello world"
console.log(aiResult.ai_used);   // true

With AbortSignal (timeout)

const controller = new AbortController();
setTimeout(() => controller.abort(), 3000); // 3s timeout

const result = await ks.detect('руддщ', {
  signal: controller.signal,
});

AI fallback

By default, KeySense AI uses a purely rule-based pipeline that requires no external calls. 94% of corrections complete in under 5ms without AI.

When rule-based confidence is below 0.70, the engine can automatically call the Claude AI model for a more accurate result. This is the "auto" mode.

Controlling AI use

Supported layouts (70+)

All layouts are detected in a single sweep. You do not need to specify the source layout.

Latency & accuracy

Latency

Accuracy methodology

The 94% figure refers to the fraction of real-world correction requests where the rule-based engine achieves a confidence score of ≥0.70 without invoking AI. It was measured against a mixed corpus of intentionally mis-typed English text across the top 20 supported layouts.

Confidence is calculated by a weighted scoring function that considers character coverage, vowel ratio, common bigrams, language dictionary coverage, and physical keyboard profile compatibility. A confidence of ≥0.70 is our threshold for a reliable correction.