Wordsets API
Wordset Endpoints
GET/api/v1/wordsets/:wordsetId
Requires API key
Fetch a wordset by its ID. Returns the wordset metadata and all words, with optional server-side filtering and scrambling. Every request requires an API key. Public wordsets accept any valid key; private wordsets require the creator's key.
Query Parameters
| Name | Description |
|---|---|
minLength | integerOnly return words with at least this many letters. |
maxLength | integerOnly return words with at most this many letters. |
category | stringFilter words to a specific category. Case-insensitive match. |
limit | integerMaximum number of words to return. Useful for paginating or sampling. |
random | booleanSet to true to shuffle the word order. Applied before limit. |
scramble | booleanSet to true to scramble the letters of each word. Great for building anagram or unscramble puzzles. |
Request
bash
curl "https://api.playanagrama.com/api/v1/wordsets/ws_abc123?category=fruits&limit=5&random=true" \
-H "Authorization: Bearer ak_your_key_here"Response Fields
| Name | Description |
|---|---|
wordsetId | stringThe unique identifier for this wordset. |
name | stringThe wordset name set by the creator. |
description | stringOptional description of the wordset. May be empty. |
isPublic | booleanWhether any valid API key can access this wordset. Private wordsets require the creator's key. |
words | object[]Array of word objects. Each has word (string), optional hint (string), and optional category (string). |
wordCount | integerNumber of words returned (after filters are applied). |
totalWordCount | integerTotal number of words in the wordset (before filtering). |
createdAt | stringISO 8601 timestamp of when the wordset was created. |
Response 200
JSON
{
"wordsetId": "ws_abc123",
"name": "Fruit Words",
"description": "Common fruit names for vocabulary practice",
"isPublic": true,
"words": [
{
"word": "mango",
"hint": "Tropical stone fruit",
"category": "tropical"
},
{
"word": "grape",
"hint": "Grows on vines",
"category": "temperate"
},
{
"word": "lemon",
"hint": "Sour citrus",
"category": "citrus"
}
],
"wordCount": 3,
"totalWordCount": 12,
"createdAt": "2026-02-08T14:30:00.000Z"
}Response 200 — with scramble=true
JSON
{
"wordsetId": "ws_abc123",
"name": "Fruit Words",
"description": "Common fruit names for vocabulary practice",
"isPublic": true,
"words": [
{
"word": "goanm",
"hint": "Tropical stone fruit",
"category": "tropical"
},
{
"word": "arpge",
"hint": "Grows on vines",
"category": "temperate"
},
{
"word": "lnmoe",
"hint": "Sour citrus",
"category": "citrus"
}
],
"wordCount": 3,
"totalWordCount": 12,
"createdAt": "2026-02-08T14:30:00.000Z"
}Response 403 — private wordset
JSON
{
"error": {
"code": "FORBIDDEN",
"message": "This wordset is private. Use the creator's API key to access it."
}
}Response 404
JSON
{
"error": {
"code": "WORDSET_NOT_FOUND",
"message": "Wordset not found."
}
}Filters are applied server-side in this order:
minLength → maxLength → category → random → limit → scramble. Each API call counts as one request toward the wordset's usage stats.Was this page helpful?