← Back to Password Generator

📚 API Documentation

Welcome to the XKCD Password Generator API. This RESTful API allows you to programmatically generate secure, memorable passwords using the XKCD method.

Base URL: /api (relative to the application root)

🔑 Authentication

No authentication is required for basic usage. The API uses IP-based rate limiting to prevent abuse.

Rate Limits:

Password generation: 20 requests per minute
Other endpoints: 100 requests per hour

🚀 Endpoints

POST /api/generate

Generate one or more passwords with specified options.

Request Body

{
  "count": 1,                          // Number of passwords to generate (1-100)
  "word_count": 4,                   // Number of words per password (2-8)
  "target_length": 32,               // Target total length in characters (16-64)
  "wordlists": ["english"],          // Array of wordlist IDs
  "capitalization_mode": "random",   // lower, upper, title, alternating, random
  "separator": "",                   // Word separator: "", "-", "_", " ", "."
  "include_numbers": true,           // Include random numbers
  "max_numbers": 2,                  // Maximum numbers to add (0-5)
  "include_punctuation": true,       // Include punctuation
  "max_punctuation": 2,              // Maximum punctuation chars (0-5)
  "min_word_length": 4,              // Minimum word length (3-15)
  "max_word_length": 8,              // Maximum word length (3-15)
  "exclude_ambiguous": false         // Exclude 0, O, 1, l, I
}

Response

{
  "success": true,
  "data": {
    "passwords": [
      {
        "password": "CorrectHorseBatteryStaple",
        "words": ["correct", "horse", "battery", "staple"],
        "length": 25,
        "entropy": 120.5,
        "word_count": 4,
        "wordlists_used": ["english"]
      }
    ],
    "count": 1
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "api_version": "1.0.0"
  }
}

GET /api/wordlists

Get a list of available wordlists with metadata.

Response

{
  "success": true,
  "data": {
    "wordlists": [
      {
        "id": "english",
        "name": "Standard English",
        "description": "Common English dictionary words",
        "language": "en",
        "categories": ["standard", "common"]
      },
      {
        "id": "olde_english",
        "name": "Olde English",
        "description": "Middle English and archaic terms",
        "language": "en",
        "categories": ["historical", "archaic"]
      },
      {
        "id": "klingon",
        "name": "Klingon",
        "description": "tlhIngan Hol vocabulary",
        "language": "tlh",
        "categories": ["fictional", "constructed"]
      }
    ]
  }
}

GET /api/capitalization-modes

Get available capitalization modes with examples.

Response

{
  "success": true,
  "data": {
    "modes": [
      {
        "id": "lower",
        "name": "lowercase",
        "description": "All letters in lowercase",
        "example": "correcthorsebatterystaple"
      },
      {
        "id": "upper",
        "name": "UPPERCASE",
        "description": "All letters in uppercase",
        "example": "CORRECTHORSEBATTERYSTAPLE"
      },
      {
        "id": "title",
        "name": "Title Case",
        "description": "First letter of each word capitalized",
        "example": "CorrectHorseBatteryStaple"
      },
      {
        "id": "alternating",
        "name": "Alternating",
        "description": "Alternating uppercase and lowercase letters",
        "example": "CoRrEcThOrSeBaTtErYsTaPlE"
      },
      {
        "id": "random",
        "name": "Random",
        "description": "Random capitalization per word",
        "example": "CorrectHORSEbatterySTAPLE"
      }
    ]
  }
}

GET /api/presets

Get predefined configuration presets for common use cases.

Response

{
  "success": true,
  "data": {
    "presets": [
      {
        "id": "classic_xkcd",
        "name": "Classic XKCD",
        "description": "Traditional 4-word password",
        "config": {
          "word_count": 4,
          "target_length": 32,
          "capitalization_mode": "title",
          "include_numbers": false,
          "include_punctuation": false
        }
      },
      {
        "id": "high_security",
        "name": "High Security",
        "description": "Maximum security configuration",
        "config": {
          "word_count": 6,
          "target_length": 48,
          "capitalization_mode": "random",
          "include_numbers": true,
          "max_numbers": 3,
          "include_punctuation": true,
          "max_punctuation": 3
        }
      }
    ]
  }
}

POST /api/analyze

Analyze an existing password for security metrics.

Request Body

{
  "password": "CorrectHorseBatteryStaple"
}

Response

{
  "success": true,
  "data": {
    "analysis": {
      "length": 25,
      "entropy": 120.5,
      "character_types": {
        "lowercase": 20,
        "uppercase": 5,
        "digits": 0,
        "special": 0
      },
      "security_assessment": {
        "score": 10,
        "level": "excellent"
      }
    }
  }
}

💻 Code Examples

cURL

# Generate a password
curl -X POST http://localhost:5000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "word_count": 4,
    "target_length": 32,
    "wordlists": ["english"],
    "capitalization_mode": "title"
  }'

# Generate with multiple wordlists
curl -X POST http://localhost:5000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "word_count": 4,
    "wordlists": ["english", "olde_english"],
    "include_numbers": true,
    "max_numbers": 2
  }'

Python

import requests

# Generate a password
response = requests.post('http://localhost:5000/api/generate', json={
    'word_count': 4,
    'target_length': 32,
    'wordlists': ['english'],
    'capitalization_mode': 'title'
})

data = response.json()
if data['success']:
    password = data['data']['passwords'][0]['password']
    print(f"Generated password: {password}")
    print(f"Entropy: {data['data']['passwords'][0]['entropy']} bits")

# Get available wordlists
response = requests.get('http://localhost:5000/api/wordlists')
wordlists = response.json()['data']['wordlists']
for wl in wordlists:
    print(f"{wl['id']}: {wl['name']}")

JavaScript

// Generate a password
fetch('http://localhost:5000/api/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    word_count: 4,
    target_length: 32,
    wordlists: ['english'],
    capitalization_mode: 'title'
  })
})
.then(response => response.json())
.then(data => {
  if (data.success) {
    const password = data.data.passwords[0].password;
    console.log('Generated password:', password);
    console.log('Entropy:', data.data.passwords[0].entropy, 'bits');
  }
});

// Get available wordlists
fetch('http://localhost:5000/api/wordlists')
  .then(response => response.json())
  .then(data => {
    data.data.wordlists.forEach(wl => {
      console.log(`${wl.id}: ${wl.name}`);
    });
  });

⚠️ Error Handling

All errors follow a consistent format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}  // Optional additional details
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Common Error Codes

Code	Description	HTTP Status
`VALIDATION_ERROR`	Invalid input parameters	400
`RATE_LIMIT_EXCEEDED`	Too many requests	429
`GENERATION_ERROR`	Password generation failed	500
`NOT_FOUND`	Resource not found	404

🎯 Favorite Phrase Passwords API

Transform your favorite quotes, movie lines, or cultural references into secure passwords while preserving their meaning. These endpoints provide cultural context detection, proper noun protection, and meaning preservation scoring.

POST /api/phrases/analyze

Analyze a phrase for cultural context, proper nouns, and password generation suitability.

Request Body

Parameter	Type	Required	Description
`phrase`	string	Yes	The phrase to analyze (3-500 characters)

Response

{
  "success": true,
  "data": {
    "original_phrase": "May the force be with you",
    "word_count": 6,
    "character_count": 25,
    "unique_words": ["may", "the", "force", "be", "with", "you"],
    "cultural_markers": {
      "sci-fi": ["force", "jedi"]
    },
    "proper_nouns": [],
    "entropy": 2.25,
    "complexity_score": 0.6,
    "suggested_transformations": [
      {
        "type": "cultural",
        "description": "Preserve cultural references while enhancing security",
        "difficulty": "medium",
        "preserved_elements": ["sci-fi"]
      }
    ]
  },
  "meta": {
    "timestamp": "2026-01-20T10:30:00Z",
    "api_version": "1.1.0"
  }
}

POST /api/phrases/generate

Generate passwords from a favorite phrase with meaning preservation.

Request Body

Parameter	Type	Required	Description
`phrase`	string	Yes	The phrase to transform (3-500 characters)
`count`	integer	No	Number of passwords to generate (1-10, default: 3)
`modes`	array	No	Transformation modes: readable, balanced, secure (default: all)
`preserve_cultural`	boolean	No	Preserve cultural references (default: true)
`protect_proper_nouns`	boolean	No	Protect proper nouns (default: true)

Response

{
  "success": true,
  "data": {
    "analysis": {
      "original_phrase": "May the force be with you",
      "word_count": 6,
      "cultural_markers": {
        "sci-fi": ["force"]
      },
      "proper_nouns": [],
      "entropy": 2.25,
      "meaning_score": 0.85
    },
    "passwords": [
      {
        "password": "may-the-force-be-with-you",
        "mode": "readable",
        "meaning_score": 0.95,
        "details": {
          "word_retention": 1.0,
          "order_preservation": 1.0,
          "cultural_preservation": 1.0,
          "proper_noun_preservation": 1.0,
          "semantic_similarity": 0.75
        }
      },
      {
        "password": "May-the-FORCE-be-WITH-you",
        "mode": "balanced",
        "meaning_score": 0.85,
        "details": { ... }
      },
      {
        "password": "M@y-th3-F0RC3-b3-w1th-y0u!42",
        "mode": "secure",
        "meaning_score": 0.65,
        "details": { ... }
      }
    ],
    "warnings": []
  },
  "meta": {
    "timestamp": "2026-01-20T10:30:00Z",
    "api_version": "1.1.0"
  }
}

GET /api/phrases/cultural-contexts

Get available cultural context categories for detection.

Response

{
  "success": true,
  "data": {
    "cultural_contexts": [
      {
        "id": "sci-fi",
        "name": "Sci-Fi",
        "word_count": 25,
        "phrase_count": 10,
        "pattern_count": 7
      },
      {
        "id": "cyberpunk",
        "name": "Cyberpunk",
        "word_count": 24,
        "phrase_count": 9,
        "pattern_count": 7
      },
      {
        "id": "fantasy",
        "name": "Fantasy",
        "word_count": 22,
        "phrase_count": 9,
        "pattern_count": 7
      },
      {
        "id": "gaming",
        "name": "Gaming",
        "word_count": 24,
        "phrase_count": 10,
        "pattern_count": 6
      },
      {
        "id": "meme",
        "name": "Meme",
        "word_count": 24,
        "phrase_count": 12,
        "pattern_count": 4
      }
    ]
  },
  "meta": {
    "timestamp": "2026-01-20T10:30:00Z"
  }
}

GET /api/phrases/transformation-modes

Get available phrase transformation modes.

Response

{
  "success": true,
  "data": {
    "transformation_modes": [
      {
        "id": "readable",
        "name": "Readable",
        "description": "Easy to read and type, minimal transformations",
        "security_level": "medium",
        "example": "may-the-force-be-with-you"
      },
      {
        "id": "balanced",
        "name": "Balanced",
        "description": "Good balance of security and memorability",
        "security_level": "high",
        "example": "May-the-FORCE-be-WITH-you"
      },
      {
        "id": "secure",
        "name": "Secure",
        "description": "Maximum security with leet speak and special characters",
        "security_level": "very_high",
        "example": "M@y-th3-F0RC3-b3-w1th-y0u!42"
      }
    ]
  },
  "meta": {
    "timestamp": "2026-01-20T10:30:00Z"
  }
}

🎭 Cultural Context Categories

Category	Description	Example Markers
`sci-fi`	Science fiction movies, TV shows, and books	force, jedi, droid, cyber, warp, matrix
`cyberpunk`	Cyberpunk genre and technology	neon, chrome, synth, netrunner, hacker
`fantasy`	Fantasy literature and media	dragon, wizard, sword, magic, ring
`gaming`	Video games and gaming culture	gg, noob, pwned, headshot, level up
`meme`	Internet memes and viral content	doge, pepe, lol, yolo, much wow

📊 Meaning Preservation Scoring

The meaning preservation score (0.0 to 1.0) indicates how well a generated password maintains the original phrase's meaning and recognizability. Higher scores mean the password is more memorable and connected to the original phrase.

Score Range	Interpretation
0.8 - 1.0	Excellent - Password is highly recognizable
0.5 - 0.8	Good - Password maintains most meaning
0.3 - 0.5	Fair - Some meaning preserved
0.0 - 0.3	Poor - Little meaning preserved

🔒 Security Considerations

All passwords are generated using cryptographically secure random number generation
Passwords are never stored or logged
Rate limiting prevents abuse and ensures fair usage
HTTPS is recommended for production deployments
Consider the security level (entropy) when choosing password options

📊 Entropy Guidelines

Entropy (bits)	Security Level	Recommended Use
< 50	Weak	Not recommended
50-80	Moderate	Low-security applications
80-120	Strong	Most applications
> 120	Excellent	High-security applications

📚 API Documentation

🔑 Authentication

🚀 Endpoints

Request Body

Response

Response

Response

Response

Request Body

Response

💻 Code Examples

cURL

Python

JavaScript

⚠️ Error Handling

Common Error Codes

🎯 Favorite Phrase Passwords API

Request Body

Response

Request Body

Response

Response

Response

🎭 Cultural Context Categories

📊 Meaning Preservation Scoring

🔒 Security Considerations

📊 Entropy Guidelines

Share Password