Bygg med Wordly API.

Hurtigstart

Opprett en gratis konto, bekreft e-posten din med den sekssifrede koden, og kopier API-nøkkelen som vises én gang i utviklerdashbordet.

1. 1
   Opprett en konto

   Registrer deg med kun e-postadresse og passord.

2. 2
   Bekreft e-posten din

   Skriv inn koden sendt av [email protected]. Verification grants 50 free credits.

3. 3
   Lagre API-nøkkelen din

   Kopier den genererte wly_live_... nøkkel og hold den i en miljøvariabel på serversiden.

4. 4
   Lag en testforespørsel

   Ring kontoendepunktet for å bekrefte autentisering og se den gjenværende saldoen.

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 og versjonering

Alle produksjonsendepunkter serveres fra følgende versjonsbaserte basis-URL:

Brytende respons eller atferdsendringer vil bruke en ny baneversjon. Additive felt kan bli introdusert innenfor v1, so clients should ignore response properties they do not recognize.

Autentisering

Autentiserte endepunkter krever en API-nøkkel i HTTP Authorization header ved å bruke bærerskjemaet.

Authorization: Bearer wly_live_your_api_key

Lokaliserte API-meldinger

Still inn svarspråket med ?lang=tr eller standarden Accept-Language overskrift. Søkeparametere har forrang. Hvert JSON-svar erklærer den valgte lokaliteten i Content-Language og 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"

Støttede språkkoder: 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.

Kreditter og 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 og behandler ikke operasjonen.

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

Lag separate nøkler for utvikling, iscenesettelse og produksjon. Wordly lagrer kun en kryptografisk hash av hver nøkkel; hele verdien vises én gang ved opprettelse.

• Navngi nøkler etter miljø eller tjeneste.
• Bruk miljøvariabler eller en administrert hemmelig butikk.
• Trekk tilbake en nøkkel umiddelbart hvis den kan ha blitt utsatt.
• Roter nøkler uten å gjenbruke gamle verdier.
• Ikke send nøkler i spørrestrenger.

Svarformat

Vellykkede svar bruker et toppnivå data objekt og kan omfatte en meta objekt. Feil bruker alltid et toppnivå error objekt med en stabil maskinlesbar code og en menneskelig lesbar message.

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

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

Behold request_id når du kontakter brukerstøtten om en vellykket fakturert forespørsel. JSON er UTF-8-kodet og klienter bør sende Accept: application/json.

Produksjons endepunkter

Ordforråds endepunkter

GET /v1/words/{word}

Returnerer et eksakt ordtreff. Bruk languages=tr,de,fr å returnere kun forespurte oversettelser. Katalog eller oversatte poster koster 1 kreditt; fullstendig berikede profiler koster 5 studiepoeng.

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 og valgfritt level, part_of_speech, category, limit, and cursor. Limits range from 1 to 50. Pass meta.next_cursor inn i neste forespørsel.

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

GET /v1/words/random

Returnerer 1–20 tilfeldige ord. Filtrer etter level, part_of_speech, or category. Each returned slot costs one credit.

POST /v1/words/batch

Slår opp mellom 1 og 50 unike ord i en enkelt forespørsel. Svaret bevarer forespørselsrekkefølgen og merker hver vare 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

Returnerer alle 30 støttede grensesnitt og API-meldingslokaliteter. Ordforrådsoversettelser returneres bare når de er tilgjengelige. Dette endepunktet er offentlig og koster null studiepoeng.

Satsgrense

Hver API-nøkkel er begrenset til 120 aksepterte forespørsler per rullende minutt. Svarene inkluderer X-RateLimit-Limit og X-RateLimit-Remaining. A 429 rate_limit_exceeded svar inkluderer 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

Feil

Anbefalt policy for forsøk på nytt

Ikke prøv på nytt 401, 402, or 404 automatisk. For forbigående 5xx svar, bruk eksponentiell backoff med jitter og en streng prøvetaking. Opprett aldri en ubegrenset forsøksløkke fordi hver godkjent autentisert forespørsel kan forbruke kreditter.

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

Ikke send Wordly-nøkkelen i en Flutter-applikasjon. Eksemplet hører hjemme i en pålitelig Dart-backend eller serverfunksjon.

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

Sjekkliste for produksjon

• Proxy Wordly-forespørsler gjennom en pålitelig backend.
• Angi tidsavbrudd for tilkobling og respons.
• Håndtak 401, 402, 404, and 5xx separat.
• Query GET /v1/account when your application needs the current balance.
• Logg endepunkt, status, ventetid og request_id uten å logge API-nøkkelen.
• Bruk separate nøkler per miljø og roter dem med jevne mellomrom.
• Cache stable vocabulary responses in your backend when appropriate.