Build with Wordly API.

Quickstart

Create a free account, verify your email using the six-digit code, and copy the API key shown once in your developer dashboard.

1. 1
   Create an account

   Register with only an email address and password.

2. 2
   Verify your email

   Enter the code sent by [email protected]. Verification grants 50 free credits.

3. 3
   Store your API key

   Copy the generated wly_live_... key and keep it in a server-side environment variable.

4. 4
   Make a test request

   Call the account endpoint to verify authentication and see the remaining balance.

curl "https://api.wordlyenglish.com/v1/account" \
  -H "Authorization: Bearer $WORDLY_API_KEY" \
  -H "Accept: application/json"

{
  "data": {
    "message": "Authenticated",
    "credits_remaining": 50
  },
  "meta": { "lang": "en" }
}

Base URL and versioning

All production endpoints are served from the following versioned base URL:

Breaking response or behavior changes will use a new path version. Additive fields may be introduced within v1, so clients should ignore response properties they do not recognize.

Authentication

Authenticated endpoints require an API key in the HTTP Authorization header using the Bearer scheme.

Authorization: Bearer wly_live_your_api_key

Localized API messages

Set the response language with ?lang=tr or the standard Accept-Language header. Query parameters take precedence. Every JSON response declares the selected locale in Content-Language and meta.lang. Error codes remain stable in English for programmatic handling; only the human-readable message is localized.

curl "https://api.wordlyenglish.com/v1/account?lang=tr" \
  -H "Authorization: Bearer $WORDLY_API_KEY" \
  -H "Accept-Language: tr-TR"

Supported language codes: en, tr, de, fr, es, it, pt, nl, pl, ru, uk, ar, fa, he, hi, bn, ur, zh, ja, ko, id, ms, vi, th, sv, no, da, fi, cs, ro.

Credits and billing

Each successful metered request consumes the documented number of credits. Email-verified accounts receive 50 free credits once. Credits are deducted atomically, so concurrent requests cannot spend the same balance twice. Balance lookup through GET /v1/account is free.

Use GET /v1/account when you need the current balance. Other endpoint responses include the operation charge but omit the remaining balance. When the balance is insufficient, the API returns HTTP 402 and does not process the operation.

{
  "error": {
    "code": "credits_exhausted",
    "message": "Your credit balance is exhausted. Add a package or enable pay-as-you-go to continue.",
    "upgrade_url": "/app.php?page=billing"
  }
}

API key lifecycle

Create separate keys for development, staging, and production. Wordly stores only a cryptographic hash of each key; the complete value is displayed once at creation.

• Name keys by environment or service.
• Use environment variables or a managed secret store.
• Revoke a key immediately if it may have been exposed.
• Rotate keys without reusing old values.
• Do not send keys in query strings.

Response format

Successful responses use a top-level data object and may include a meta object. Errors always use a top-level error object with a stable machine-readable code and a human-readable message.

{
  "data": { ... },
  "meta": {
    "credits_used": 1,
    "request_id": "..."
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "..."
  }
}

Keep the request_id when contacting support about a successful billed request. JSON is UTF-8 encoded and clients should send Accept: application/json.

Production endpoints

Vocabulary endpoints

GET /v1/words/{word}

Returns an exact word match. Use languages=tr,de,fr to return only requested translations. Catalog or translated records cost 1 credit; fully enriched profiles cost 5 credits.

curl "https://api.wordlyenglish.com/v1/words/water?languages=tr,de" \
  -H "Authorization: Bearer $WORDLY_API_KEY"

GET /v1/words/search

Search with q and optional level, part_of_speech, category, limit, and cursor. Limits range from 1 to 50. Pass meta.next_cursor into the next request.

curl "https://api.wordlyenglish.com/v1/words/search?q=app&level=advanced&limit=20" \
  -H "Authorization: Bearer $WORDLY_API_KEY"

GET /v1/words/random

Returns 1–20 random words. Filter by level, part_of_speech, or category. Each returned slot costs one credit.

POST /v1/words/batch

Looks up between 1 and 50 unique words in a single request. The response preserves request order and marks every item with found.

curl -X POST "https://api.wordlyenglish.com/v1/words/batch?lang=tr" \
  -H "Authorization: Bearer $WORDLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"words":["water","opportunity"],"languages":["tr","de"]}'

GET /v1/languages

Returns all 30 supported interface and API-message locales. Vocabulary translations are returned only when available. This endpoint is public and costs zero credits.

Rate limit

Each API key is limited to 120 accepted requests per rolling minute. Responses include X-RateLimit-Limit and X-RateLimit-Remaining. A 429 rate_limit_exceeded response includes Retry-After: 60.

Response field reference

Every stable response variable is described below. Additive fields may appear later, so clients should ignore fields they do not recognize.

Vocabulary object

Meta object

Error object

Errors

Recommended retry policy

Do not retry 401, 402, or 404 automatically. For transient 5xx responses, use exponential backoff with jitter and a strict retry cap. Never create an unbounded retry loop because each accepted authenticated request may consume credits.

JavaScript / Node.js

const response = await fetch('https://api.wordlyenglish.com/v1/account', {
  headers: {
    Authorization: `Bearer ${process.env.WORDLY_API_KEY}`,
    Accept: 'application/json'
  }
});

const body = await response.json();
if (!response.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

console.log(body.data.credits_remaining);

Python

import os
import requests

response = requests.get(
    'https://api.wordlyenglish.com/v1/account',
    headers={
        'Authorization': f'Bearer {os.environ["WORDLY_API_KEY"]}',
        'Accept': 'application/json',
    },
    timeout=15,
)
response.raise_for_status()
print(response.json()['data']['credits_remaining'])

PHP

$curl = curl_init('https://api.wordlyenglish.com/v1/account');
curl_setopt_array($curl, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 15,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WORDLY_API_KEY'),
    'Accept: application/json',
  ],
]);

$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

if ($status >= 400) {
  throw new RuntimeException('Wordly API request failed');
}
$data = json_decode($body, true, flags: JSON_THROW_ON_ERROR);

Dart / Flutter

Do not ship the Wordly key inside a Flutter application. The example belongs in a trusted Dart backend or server function.

final response = await http.get(
  Uri.parse('https://api.wordlyenglish.com/v1/account'),
  headers: {
    'Authorization': 'Bearer ${Platform.environment['WORDLY_API_KEY']}',
    'Accept': 'application/json',
  },
);

final body = jsonDecode(response.body) as Map<String, dynamic>;
if (response.statusCode >= 400) {
  throw Exception((body['error'] as Map)['code']);
}

Production checklist

• Proxy Wordly requests through a trusted backend.
• Set connection and response timeouts.
• Handle 401, 402, 404, and 5xx separately.
• Query GET /v1/account when your application needs the current balance.
• Log endpoint, status, latency, and request_id without logging the API key.
• Use separate keys per environment and rotate them periodically.
• Cache stable vocabulary responses in your backend when appropriate.