🔐 Passpraise API Documentation

Generate memorable passphrases programmatically

← Back to Generator | General Documentation

Quick Navigation

Getting Started

The Passpraise API allows you to generate memorable passphrases based on notable people from history. All endpoints are RESTful and return JSON responses.

Base URL

https://passpraise.com/api/

Quick Example

curl "https://passpraise.com/api/?action=generate&count=1"

Authentication

The Passpraise API is completely free and does not require authentication or API keys. Simply make requests to the endpoints.

Rate Limiting

⚡ Rate Limits

100 requests per hour per IP address

Rate limit information is included in response headers:

  • X-RateLimit-Limit: Maximum requests per window
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when the rate limit resets

Rate Limit Exceeded Response

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "limit": 100,
  "window": 3600,
  "reset_in_seconds": 2847
}

API Endpoints

The API provides three main actions:

Generate Passphrases

GET/POST /api/?action=generate

Generate one or more passphrases with customizable options.

Parameters

Parameter Type Default Description
count integer 1 Number of passphrases to generate (1-20)
length integer 5 Minimum character length per part
numElements integer 3 Number of parts in the passphrase (2-5)
requireUppercase boolean false Require at least one uppercase letter
requireLowercase boolean false Require at least one lowercase letter
requireNumber boolean false Require at least one number
requireSpecial boolean false Require at least 2 special characters
includeSeparator boolean true Include separators between words
excludeChars string "" Space-separated characters to exclude (e.g., "~ % ^")
includeFirstName boolean true Include first name in passphrase
includeLastName boolean true Include last name in passphrase
includeBirthYear boolean true Include birth year in passphrase
includeAwards boolean true Include awards in passphrase
includeTitle boolean true Include title/occupation in passphrase
includeCountry boolean true Include country in passphrase
includeField boolean true Include field of work in passphrase
includeInitials boolean true Include initials in passphrase
continent string null Filter by continent
country string null Filter by country
field string null Filter by field of work
century string null Filter by century (1700s, 1800s, 1900s, 2000s)
hasAwards boolean false Filter to only people with awards

Example Request (GET)

GET /api/?action=generate&count=3&requireNumber=true&country=United%20States

Example Request (POST)

{
  "action": "generate",
  "count": 3,
  "requireNumber": true,
  "requireUppercase": true,
  "includeSeparator": true,
  "country": "United States",
  "field": "Science"
}

Example Response (Single)

{
  "passphrase": "Marie-1867-Curie",
  "info": {
    "name": "Marie Curie",
    "continent": "Europe",
    "country": "Poland",
    "field": "Science",
    "birth_year": 1867,
    "death_year": 1934,
    "achievement": "First woman to win a Nobel Prize",
    "bio": "Pioneering physicist and chemist...",
    "awards": ["Nobel Prize in Physics", "Nobel Prize in Chemistry"],
    "wikipedia": "https://en.wikipedia.org/wiki/Marie_Curie"
  },
  "separator": "-"
}

Example Response (Multiple)

[
  {
    "passphrase": "Ada-1815-Lovelace",
    "info": { ... },
    "separator": "-"
  },
  {
    "passphrase": "Grace-1906-Hopper",
    "info": { ... },
    "separator": "-"
  }
]

Get Available Filters

GET /api/?action=filters

Retrieve all available filter options from the database.

Example Request

GET /api/?action=filters

Example Response

{
  "continents": ["Africa", "Asia", "Europe", "North America", "South America", "Oceania"],
  "countries": ["United States", "United Kingdom", "France", "Germany", ...],
  "fields": ["Science", "Literature", "Politics", "Arts", "Technology", ...],
  "centuries": ["1700s", "1800s", "1900s", "2000s"]
}

Get Database Statistics

GET /api/?action=stats

Get statistical information about the database.

Example Request

GET /api/?action=stats

Example Response

{
  "total_people": 1247,
  "continents": {
    "Europe": 523,
    "North America": 412,
    "Asia": 187,
    ...
  },
  "fields": {
    "Science": 342,
    "Literature": 198,
    "Politics": 156,
    ...
  },
  "centuries": {
    "1900s": 687,
    "1800s": 312,
    "2000s": 156,
    "1700s": 92
  }
}

Code Examples

cURL

# Simple GET request
curl "https://passpraise.com/api/?action=generate&count=5"

# POST request with JSON
curl -X POST "https://passpraise.com/api/" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "generate",
    "count": 3,
    "requireNumber": true,
    "requireUppercase": true,
    "field": "Science"
  }'

JavaScript (Browser)

// Using fetch API
async function generatePassphrase() {
  const response = await fetch('https://passpraise.com/api/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      action: 'generate',
      count: 5,
      requireNumber: true,
      requireUppercase: true,
      includeSeparator: true
    })
  });
  
  const data = await response.json();
  console.log(data);
  return data;
}

generatePassphrase();

Python

import requests

# Simple GET request
response = requests.get('https://passpraise.com/api/', params={
    'action': 'generate',
    'count': 5
})
data = response.json()
print(data)

# POST request with options
response = requests.post('https://passpraise.com/api/', json={
    'action': 'generate',
    'count': 3,
    'requireNumber': True,
    'requireUppercase': True,
    'field': 'Science',
    'includeSeparator': True
})
data = response.json()
print(data)

PHP

<?php
// Using cURL
$ch = curl_init('https://passpraise.com/api/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'action' => 'generate',
    'count' => 5,
    'requireNumber' => true,
    'requireUppercase' => true,
    'field' => 'Science'
]));

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);
?>

Node.js

// Using axios
const axios = require('axios');

async function generatePassphrase() {
  try {
    const response = await axios.post('https://passpraise.com/api/', {
      action: 'generate',
      count: 5,
      requireNumber: true,
      requireUppercase: true,
      field: 'Science'
    });
    
    console.log(response.data);
    return response.data;
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

generatePassphrase();

Error Handling

The API uses standard HTTP status codes and returns error messages in JSON format.

HTTP Status Codes

Code Meaning Description
200 OK Request successful
400 Bad Request Invalid parameters or no matching data
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error occurred

Error Response Format

{
  "error": "Error type",
  "message": "Detailed error message"
}

Common Errors

// No matching data
{
  "error": "No data matches the specified filters"
}

// Invalid action
{
  "error": "Invalid action. Use: generate, filters, or stats"
}

// Rate limit exceeded
{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "limit": 100,
  "window": 3600,
  "reset_in_seconds": 2847
}

Support & Feedback

For questions, issues, or feature requests, please visit our main site or check the general documentation.

© 2025 Passpraise. Open Source & Zero-Knowledge.