Integration Guide

Last updated: April 26, 2026

Log2Spell is a single HTTP endpoint that takes a search query and returns a corrected version (or the original, if it's already correct). Integrate it at the front of your search flow — before your search engine — to catch misspellings the search engine itself wouldn't fix.

Where it fits — keep your existing fallback

Most search stacks only attempt correction after a zero-result query. The catch: most misspellings don't return zero — they return a different, worse set of results, so they never trip the null-result check and silently convert lower. That's the blind spot.

You don't replace anything. Log2Spell sits in front of search and corrects proactively from your own logs, catching exactly those misspellings that return poor (non-empty) results. Your existing null-result checker stays as the long-tail safety net. The union covers strictly more than either alone — additive, not rip-and-replace.

See the buy-vs-build ROI model →

Quick start

Once you've activated an endpoint, you'll have a tenant ID and an API key. Try it:

curl 'https://toaiz.ai/spell_api/t/YOUR_TENANT_ID/correct?q=nikee+shoes&key=YOUR_API_KEY'

Response:

{
  "input": "nikee shoes",
  "topCorrection": "nike shoes",
  "rankedCandidates": ["nike shoes", "nice shoes", "nikko shoes"],
  "confidence": 0.87,
  "safeToUse": true,
  "warning": ""
}

Authentication

Pass your API key one of two ways:

Query parameter: ?key=sk_xxxx
Header: X-API-Key: sk_xxxx

Header is recommended for production. Both methods work identically.

The `/correct` endpoint

Method: GET
URL: https://toaiz.ai/spell_api/t/{tenantId}/correct

Request parameters

Param	Type	Required	Description
`q`	string	yes	The search query as the user typed it.
`key`	string	yes (or header)	Your API key.

Response fields

Field	Type	Description
`input`	string	The query you sent, unchanged.
`topCorrection`	string	The best correction. If no correction is needed, equals `input`.
`rankedCandidates`	array	Up to 5 alternative corrections, ranked by confidence. Useful for "Did you mean..." suggestions when you don't want to auto-apply.
`confidence`	number 0–1	How confident the model is in the correction.
`safeToUse`	boolean	Whether to apply the correction automatically. See decision logic below.
`warning`	string	Empty on success. Contains an explanation if the request failed (auth error, expired endpoint, monthly limit reached, etc.).

Decision logic — how to use the response

The two key fields are topCorrection and safeToUse:

if (response.topCorrection === query) {
  // No correction needed; search as-is
  search(query);
} else if (response.safeToUse) {
  // High-confidence correction — apply silently
  search(response.topCorrection);
} else {
  // Lower confidence — search the original, but show a hint
  search(query);
  showDidYouMean(response.topCorrection);
}

Confidence scoring is tuned so that safeToUse=true implies very low false-positive risk. We err on the side of not auto-correcting when uncertain — bad corrections are worse than no correction, since the user already knows their query returned weak results.

Code examples

JavaScript (browser fetch)

async function spellCorrect(query) {
  const url = `https://toaiz.ai/spell_api/t/${TENANT_ID}/correct?q=${encodeURIComponent(query)}`;
  const res = await fetch(url, { headers: { 'X-API-Key': API_KEY } });
  return res.json();
}

Node.js

const fetch = require('node-fetch');

async function spellCorrect(query) {
  const url = `https://toaiz.ai/spell_api/t/${process.env.LOG2SPELL_TENANT}/correct`
            + `?q=${encodeURIComponent(query)}`;
  const res = await fetch(url, {
    headers: { 'X-API-Key': process.env.LOG2SPELL_KEY }
  });
  return res.json();
}

Python

import os, requests

def spell_correct(query):
    url = f"https://toaiz.ai/spell_api/t/{os.environ['LOG2SPELL_TENANT']}/correct"
    r = requests.get(url, params={"q": query},
                     headers={"X-API-Key": os.environ["LOG2SPELL_KEY"]},
                     timeout=2)
    return r.json()

Go

req, _ := http.NewRequest("GET",
    fmt.Sprintf("https://toaiz.ai/spell_api/t/%s/correct?q=%s",
        os.Getenv("LOG2SPELL_TENANT"), url.QueryEscape(query)), nil)
req.Header.Set("X-API-Key", os.Getenv("LOG2SPELL_KEY"))
resp, _ := http.DefaultClient.Do(req)

Refreshing your model

As your customers' vocabulary evolves, refresh your spell checker by re-uploading your latest query log:

curl -X POST 'https://toaiz.ai/spell_api/t/YOUR_TENANT_ID/refresh' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -F 'file=@latest_query_log.csv'

Same tenant ID, same API key, new model. We recommend refreshing weekly or monthly. The CSV format is frequency,query per line, or one query per line if you don't have frequency data.

Errors

For backwards compatibility, the API returns HTTP 200 even on errors. Always check the warning field:

Warning text contains	Meaning
"Invalid or missing API key"	Auth failed. Check the key.
"Monthly limit reached"	You've hit your plan's monthly quota. Upgrade or wait until the next cycle.
"Endpoint expired or not found"	Trial lease expired or tenant ID is wrong.

On any error, topCorrection equals input so your code can safely fall back to passing the original query through.

Best practices

Call before your search engine, not after. The whole point is to catch misspellings that would otherwise return weak results, not no results.
Set a tight timeout (1–2 seconds). If we're slow or unreachable, fall back to the original query — never block the search.
Cache aggressively if your traffic has heavy query repetition. Most queries repeat; you don't need to ask us twice for the same string.
Don't auto-correct unless safeToUse is true. A "Did you mean...?" suggestion is always safer than the wrong correction.
Log corrections you applied in your own analytics so you can measure impact (conversion lift on corrected queries).

Support

Questions, edge cases, or want to discuss a custom deployment? Email kakollu@gmail.com.

← Back to Log2Spell