Public Vocabulary API & Datasets — vocabulary-test.com

API Overview

The vocabulary-test.com API provides simple, lightweight REST endpoints designed for integration with AI search engines, educational mobile applications, flashcard generators, and custom developer workflows. The root of the production API is: https://vocabulary-test.com

Public Endpoints

GET /api/words/sample

Retrieve a randomized set of calibrated words along with their parts of speech, difficulty levels, phonetic guides, correct definitions, and distraction alternatives.

track Optional. String ("native" or "learner")
difficulty Optional. Integer (1-5 for native track, 1-6 corresponding to CEFR levels A1-C2 for learner)
limit Optional. Integer. Default is 5, maximum 20.

curl -X GET "https://vocabulary-test.com/api/words/sample?track=learner&difficulty=6&limit=1"

fetch("https://vocabulary-test.com/api/words/sample?track=learner&difficulty=6&limit=1")
  .then(res => res.json())
  .then(data => console.log(data));

import requests

url = "https://vocabulary-test.com/api/words/sample"
params = {"track": "learner", "difficulty": 6, "limit": 1}
response = requests.get(url, params=params)
print(response.json())

[
  {
    "word": "equivocal",
    "difficulty": 6,
    "pos": "adj.",
    "pron": "/ɪˈkwɪvək(ə)l/",
    "correct": "open to more than one interpretation; ambiguous",
    "distractors": [
      "highly aggressive or hostile",
      "completely transparent and easy to understand",
      "perfectly equal in weight or value"
    ],
    "track": "learner"
  }
]

GET /api/openapi.json

Returns the official OpenAPI 3.0 specification JSON file describing all current endpoints. Easily import this file into Swagger UI, Postman, Custom GPTs, or Claude Projects.

curl -X GET "https://vocabulary-test.com/openapi.json"

{
  "openapi": "3.0.3",
  "info": {
    "title": "Vocabulary Size Test Public API",
    "version": "1.0.0",
    "description": "Public endpoints and dynamic services..."
  },
  "servers": [
    { "url": "https://vocabulary-test.com" }
  ],
  "paths": { ... }
}

POST /api/send-email

Dispatches a beautifully-styled, academic HTML email summary of vocab scores and saved word flashcards directly to the user's inbox.

curl -X POST "https://vocabulary-test.com/api/send-email" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "track": "learner",
    "estimate": 12500,
    "levelName": "C1 (Advanced)",
    "words": [
      {"word": "ephemeral", "correct": "lasting a very short time"}
    ]
  }'

fetch("https://vocabulary-test.com/api/send-email", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "user@example.com",
    track: "learner",
    estimate: 12500,
    levelName: "C1 (Advanced)",
    words: [{ word: "ephemeral", correct: "lasting a very short time" }]
  })
}).then(res => res.json());

AI Integration Guides

Custom GPTs & Action Schema

To hook your Custom GPT to our vocabulary engine, simply copy the URL of our openapi.json spec and paste it into the "Import from URL" button inside your GPT's Action configuration panel.

Claude Projects

For Claude Projects or custom orchestrations, download our raw word databases and feed the openapi.json as Project Knowledge to allow Claude to generate real-time multiple-choice checklists for your specific vocabulary levels.

Want to Verify Your Own English Vocabulary?

Scientific two-phase assessment system · Free & Instant results

Take the Vocabulary Size Test →