GET /api/v1/words/{id}

Fetch one entry

Fetch one entry.

One entry in full: every definition, spelling variant, dialect form, example sentence, related word, alternative script and pronunciation the record holds.

The id segment accepts the numeric id or the URL slug, so /api/v1/words/4127 and /api/v1/words/ulo both resolve.

Metered under the words quota key, shared with the search endpoint.

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

Parameters

Parameters as the OpenAPI document declares them. Nothing is required unless the table says so.
Name	In	Type	Required	Description
`id`	path	string	Required	Numeric id or URL slug of the entry.
`language`	query	string	Optional	ISO 639-3 code or URL slug. Default `ibo`.

Example request

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

curl "https://ozituma.com/api/v1/words/ulo" \
  -H "X-API-Key: $OZITUMA_API_KEY"

The same request, raw

GET /api/v1/words/ulo HTTP/1.1
Host: ozituma.com
Accept: application/json
X-API-Key: ozt_live_your_key_here

Example response

{
  "id": 4127,
  "language": "igbo",
  "headword": "ụlọ",
  "exactForm": "ulo",
  "slug": "ulo",
  "pronunciation": null,
  "isCommon": true,
  "isVerified": true,
  "frequencyRank": null,
  "glosses": ["house", "home"],
  "partOfSpeech": "Noun",
  "matchType": "headword",
  "score": 1,
  "definitions": [
    {
      "text": "A building in which people live.",
      "label": null,
      "position": 1,
      "partOfSpeech": { "code": "NNC", "name": "Noun" }
    }
  ],
  "dialects": [],
  "forms": [],
  "scripts": [],
  "examples": [],
  "related": [],
  "audio": [],
  "attribution": {
    "sourceName": "Igbo API",
    "sourceUrl": "https://github.com/nkowaokwu/igbo_api",
    "license": "Apache-2.0",
    "licenseUrl": "https://www.apache.org/licenses/LICENSE-2.0",
    "citation": null
  }
}

Illustrative values in the shape components.schemas.WordDetail declares: an allOf of WordSummary and the detail fields. Collections the record has nothing for come back as empty arrays and attribution may be null.

Errors

Responses the OpenAPI document lists

Status	What the document says
`200`	The entry
`401`	Missing or invalid API key
`404`	No such entry
`429`	Daily quota exceeded for your plan

Codes this route can return

Status	Code	When
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.
404	`not_found`	No entry matches that id or slug, or no word of the day exists for the requested language.
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 describes the 200 response as WordDetail. The example follows that schema.
The document lists 200, 401, 404 and 429 for this operation. The route can also return 400 (unsupported_language) and 500 (internal_error), which the document does not list.