GET /api/v1/words

Search words

Search the dictionary.

Full-text search across headwords, alternate spellings, dialect spellings and English definitions in one call. The route mirrors the Igbo API's primary endpoint, so an existing client can migrate by changing a base URL.

An omitted keyword is a valid request: the endpoint browses high-frequency words instead of returning an error.

The route is metered under the words quota key. GET /api/v1/words/{id} and GET /api/v1/word-of-the-day draw on that same key.

Path: /api/v1/words
Authentication: X-API-Key required — how it works
Rate limit: Counted against the "words" endpoint in plan_limit.
Operation id: searchWords

Parameters

Parameters as the OpenAPI document declares them. Nothing is required unless the table says so.
Name	In	Type	Required	Description
`keyword`	query	string	Optional	Free-text search. This is the name the Igbo API uses.
`q`	query	string	Optional	Short alias for `keyword`. The route reads `keyword` first; if both are sent, `q` is ignored.
`language`	query	string	Optional	ISO 639-3 code or URL slug. Default `ibo`. An unknown value returns `unsupported_language`.
`page`	query	integer	Optional	Page number, minimum 1, default 1. The implementation rejects a value above 10,000 with `invalid_parameter`.
`limit`	query	integer	Optional	Results per page, 1–100, default 20.
`strict`	query	boolean	Optional	`true` matches exact headwords only.
`dialect`	query	string	Optional	Dialect code, e.g. `ONI`.
`wordClasses`	query	string (CSV)	Optional	Grammar categories, comma-separated, e.g. `NNC,AV`.
`tags`	query	string (CSV)	Optional	Tag slugs, comma-separated, e.g. `proverb`.
`common`	query	boolean	Optional	`true` returns only high-frequency words.

Pagination

This endpoint is paginated with page and limit, and its response is the shared paginated envelope. Pagination explained →

Example request

The curl works against the live API once OZITUMA_API_KEY holds your key.

curl "https://ozituma.com/api/v1/words?q=mmiri&limit=2" \
  -H "X-API-Key: $OZITUMA_API_KEY"

The same request, raw

GET /api/v1/words?q=mmiri&limit=2 HTTP/1.1
Host: ozituma.com
Accept: application/json
X-API-Key: ozt_live_your_key_here

Example response

{
  "data": [
    {
      "id": 5192,
      "language": "igbo",
      "headword": "mmiri",
      "exactForm": "mmiri",
      "slug": "mmiri",
      "pronunciation": null,
      "isCommon": true,
      "isVerified": true,
      "frequencyRank": null,
      "glosses": ["liquid"],
      "partOfSpeech": "Noun",
      "matchType": "headword",
      "score": 1185
    }
  ],
  "total": 93,
  "page": 1,
  "perPage": 2,
  "hasMore": true
}

Illustrative values in the shape components.schemas.PaginatedWords declares. Each element of data is a WordSummary, so it carries the thirteen fields listed there and no others.

Errors

Responses the OpenAPI document lists

Status	What the document says
`200`	Matching entries
`401`	Missing or invalid API key
`429`	Daily quota exceeded for your plan

Codes this route can return

Status	Code	When
400	`invalid_parameter`	A query or body parameter is missing, malformed, or outside its range. The message names the parameter.
400	`unsupported_language`	The `language` value is not an active language code or URL slug. The message lists the codes that are available.
401	`missing_api_key`	No key was sent. `readApiKey` looks for `X-API-Key` first, then `Authorization: Bearer <key>`, and rejects the request when neither carries a value.
401	`invalid_api_key`	The key is not known, has been revoked, has expired, or its developer is suspended. `authenticateApiKey` returns null for all four, so revocation is reported through this code.
429	`quota_exceeded`	The key has used its whole daily allowance for the metered endpoint. The response carries `Retry-After` in seconds until 00:00 UTC and a `details` object with `plan`, `endpoint`, `used` and `limit`.
500	`internal_error`	An unexpected server error. The message is generic on purpose; a stack trace or a SQL error is never returned to a caller.

The body of every failure is the same. Errors explained →

Where the document and the implementation differ

Read from the route source and the OpenAPI document together. Where the two disagree, this is what each one says.

The document declares keyword and q as two parameters; the route reads keyword first and falls back to q.
The document lists 200, 401 and 429 for this operation. The route can also return 400 (invalid_parameter, unsupported_language) and 500 (internal_error), which the document does not list.