HTTP API reference

Base URL: https://reglegbrief.com/whisk/api/v1

Interactive docs

Swagger UI — try requests, see live responses
ReDoc — cleaner static reference
OpenAPI JSON — machine-readable schema (for code generators)

Endpoints

`POST /spellcheck` — check text (manual mode)

Request body:
{
  "text": "Ths is a smple sentnce.",
  "language": "en",
  "ignore": []          // optional; lowercased words to skip
}

Response 200:
{
  "language": "en",
  "total_words": 5,
  "misspellings": [
    {
      "word": "ths",
      "offset": 0,
      "length": 3,
      "suggestions": ["this", "the", "thus", "tho", "thy"],
      "kind": "spell"
    },
    ...
  ]
}

`POST /spellcheck/apply` — auto-fix (auto mode)

Request body: (same as /spellcheck)

Response 200:
{
  "language": "en",
  "total_words": 5,
  "corrected_text": "This is a simple sentence.",
  "changes": [
    {"offset": 0, "before": "Ths", "after": "This", "kind": "spell"},
    {"offset": 9, "before": "smple", "after": "simple", "kind": "spell"},
    {"offset": 15, "before": "sentnce", "after": "sentence", "kind": "spell"}
  ],
  "unresolved": []      // findings with no suggestion
}

`GET /spellcheck/languages`

Response 200:
{
  "supported": ["af", "ar", "be", ..., "vi"],
  "count": 49,
  "engine": "hunspell"
}

`GET /health`

Response 200:
{
  "status": "ok",
  "version": "0.3.0",
  "uptime_seconds": 12345,
  "languages": {"available": 49, "loaded_in_memory": 8},
  "bigrams_en_loaded": 258437
}

`POST /keys` — generate API key (self-serve)

See /whisk/keys/ for the friendly form.

Headers

Request

Content-Type: application/json — required on POST
X-Api-Key: rlbwhisk_live_... — optional, unlocks 10,000/hr instead of 100/hr

Response

X-Request-ID: req_<16hex> — quote in support tickets
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Retry-After — on 429, seconds to wait
Cache-Control: no-store — bodies are never cached by CDN or browser

Errors

Every non-2xx returns the same shape:

{
  "error": {
    "code": "invalid_language",
    "message": "Language 'xx' not available on this server.",
    "request_id": "req_abc123..."
  }
}

Status	Code	Meaning
400	`bad_request`	Malformed input
401	`invalid_api_key`	Missing/invalid/revoked key
422	`validation_error`	Request body fails schema
429	`rate_limit_exceeded`	Slow down; check `Retry-After`
500	`internal_error`	Report the `request_id`
503	`service_unavailable`	Try again in a moment

CORS

Permissive by default — any origin can call the API. Suitable for browser code with the caveat that a client-side API key is publicly visible; use the anonymous tier or a lightweight backend proxy for prod.

Versioning

The /api/v1/* namespace is stable. Breaking changes ship as /api/v2/* with at least 6 months' overlap. Legacy /api/* (unversioned) still works during the v0.3 transition but is undocumented and slated for removal.