Bygg med Wordly API.

Snabbstart

Skapa ett gratis konto, verifiera din e-post med den sexsiffriga koden och kopiera API-nyckeln som visas en gång i din utvecklarpanel.

1. 1
   Skapa ett konto

   Registrera dig med endast en e-postadress och lösenord.

2. 2
   Verifiera din e-post

   Ange koden skickad av [email protected]. Verification grants 50 free credits.

3. 3
   Lagra din API-nyckel

   Kopiera det genererade wly_live_... nyckel och behåll den i en miljövariabel på serversidan.

4. 4
   Gör en testförfrågan

   Ring kontoslutpunkten för att verifiera autentiseringen och se det återstående saldot.

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" }
}

Bas-URL och versionshantering

Alla produktionsslutpunkter betjänas från följande versionsbaserade bas-URL:

Brytande svar eller beteendeförändringar kommer att använda en ny sökvägsversion. Additiva fält kan införas inom v1, so clients should ignore response properties they do not recognize.

Autentisering

Autentiserade slutpunkter kräver en API-nyckel i HTTP Authorization header med hjälp av bärarschemat.

Authorization: Bearer wly_live_your_api_key

Lokaliserade API-meddelanden

Ställ in svarsspråket med ?lang=tr eller standarden Accept-Language sidhuvud. Frågeparametrar har företräde. Varje JSON-svar deklarerar den valda lokalen i Content-Language och 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"

Språkkoder som stöds: 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.

Krediter och fakturering

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 och bearbetar inte operationen.

{
  "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

Skapa separata nycklar för utveckling, iscensättning och produktion. Wordly lagrar endast en kryptografisk hash för varje nyckel; hela värdet visas en gång vid skapandet.

• Namnge nycklar efter miljö eller tjänst.
• Använd miljövariabler eller en hanterad hemlig butik.
• Återkalla en nyckel omedelbart om den kan ha blivit utsatt.
• Rotera nycklar utan att återanvända gamla värden.
• Skicka inte nycklar i frågesträngar.

Svarsformat

Framgångsrika svar använder en toppnivå data objekt och kan innefatta en meta objekt. Fel använder alltid en toppnivå error objekt med en stabil maskinläsbar code och en läsbar för människor message.

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

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

Behåll request_id när du kontaktar support om en lyckad faktureringsförfrågan. JSON är UTF-8-kodad och klienter bör skicka Accept: application/json.

Produktionsslutpunkter

Ordförrådens slutpunkter

GET /v1/words/{word}

Returnerar en exakt ordmatchning. Använd languages=tr,de,fr för att endast returnera begärda översättningar. Katalog eller översatta poster kostar 1 poäng; helt berikade profiler kostar 5 poäng.

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

GET /v1/words/search

Sök med q och valfritt level, part_of_speech, category, limit, and cursor. Limits range from 1 to 50. Pass meta.next_cursor till nästa begäran.

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

GET /v1/words/random

Returnerar 1–20 slumpmässiga ord. Filtrera efter level, part_of_speech, or category. Each returned slot costs one credit.

POST /v1/words/batch

Slår upp mellan 1 och 50 unika ord i en enda begäran. Svaret bevarar beställningsordningen och markerar varje artikel med 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

Returnerar alla 30 gränssnitt och API-meddelanden som stöds. Ordförrådsöversättningar returneras endast när de är tillgängliga. Denna slutpunkt är offentlig och kostar noll poäng.

Prisgräns

Varje API-nyckel är begränsad till 120 accepterade förfrågningar per rullande minut. Svaren inkluderar X-RateLimit-Limit och X-RateLimit-Remaining. A 429 rate_limit_exceeded svar inkluderar 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

Fel

Rekommenderad policy för ett nytt försök

Försök inte igen 401, 402, or 404 automatiskt. För övergående 5xx svar, använd exponentiell backoff med jitter och ett strikt tak för försök igen. Skapa aldrig en obegränsad återförsöksslinga eftersom varje godkänd autentiserad begäran kan förbruka krediter.

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

Skicka inte Wordly-nyckeln i en Flutter-applikation. Exemplet hör hemma i en pålitlig Dart-backend eller serverfunktion.

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']);
}

Produktionschecklista

• Proxy Wordly-förfrågningar via en pålitlig backend.
• Ställ in anslutnings- och svarstidsgränser.
• Handtag 401, 402, 404, and 5xx separat.
• Query GET /v1/account when your application needs the current balance.
• Logga slutpunkt, status, latens och request_id utan att logga API-nyckeln.
• Använd separata nycklar per miljö och rotera dem med jämna mellanrum.
• Cache stable vocabulary responses in your backend when appropriate.