GET
/person
Generate people (query parameters)
Generate one or more fictional people for a given country and gender using query parameters. Requires a valid X-APIKEY header.
Query parameters
| Parameter | Notes |
|---|---|
country | Required. Two-letter country code (e.g. ZA). |
gender | Required. male or female. |
count | Optional. 1–100. Defaults to 1. |
Example
GET /person?country=ZA&gender=female&count=2 X-APIKEY: your-api-key
POST
/person
Generate people (JSON body)
Generate one or more fictional people using a JSON request body. Identical generation behaviour to GET /person.
Request body
{
"countryCode": "ES",
"gender": "male",
"count": 5
}
Notes
countryCode— required, two lettersgender— required,maleorfemalecount— optional, 1–100
POST
/country/:countryCode/names
Bulk upload country names
Upload male first names, female first names, and surnames for an existing country. Requires an API key with upload permission.
Example URL
POST /country/ZA/names X-APIKEY: your-upload-key
Each collection supports
mode: "add"— append to existing namesmode: "replace"— replace all existing names
GET
/health
Service health
Returns the service status and deployment timestamp. No authentication required.
Request
Nothing required. No headers, body, or query parameters.
Response
{
"service": "sample",
"status": "ok",
"deployed_at": "unknown"
}
GET
/db/health
Database health
Verifies the API can acquire a connection from the MySQL pool and execute a query. Returns 503 if the connection fails.
Request
Nothing required. No headers, body, or query parameters.
Response
{
"service": "sample",
"status": "ok",
"deployed_at": null,
"message": "Database connection successful",
"database": "your_db"
}
Returns 503 with "status": "error" when the connection fails.