Public API reference

Docs and API Reference

TestRows exposes a small public JSON API for generating fake test data in scripts, QA pipelines, demos, and mock services. The documentation below only covers endpoints that currently exist in the codebase.

Overview Endpoints Errors Limits & headers

API overview

The public API is intentionally small and developer-friendly. All documented endpoints are unauthenticated `GET` routes that return JSON only, reuse the same generator contracts as the UI, and are intended for testing and non-production data workflows.

Method

GET

Auth

None

Response

JSON only

Count range

1-100

Intended usage

These endpoints are intended for test data, mock APIs, QA fixtures, and demo environments. They should not be treated as production identity or contact data.

Quick start

1. Pick one of the five documented endpoints below.
2. Add a `count` value and any generator-specific query params.
3. Call the endpoint with a standard `GET` request.
4. Use the returned JSON for fixtures, tests, demos, or seeded QA flows.

/api/uuid?count=3

/api/user?count=2&includeAddress=true

/api/address?count=2&country=GB

Available endpoints

The following endpoints are the only public API routes currently implemented in the codebase. Each section below reflects the actual query params exposed by the corresponding generator definition.

/api/uuid

UUID Generator

Open tool →

Generate UUID v4 batches for fixtures, record IDs, seeded data, and integration tests.

Jump to endpoint details →

/api/user

Random User Generator

Open tool →

Return fake user profiles with optional address, phone, company, and DOB fields.

Jump to endpoint details →

/api/address

Random Address Generator

Open tool →

Create realistic addresses for checkout, billing, shipping, and form-validation workflows.

Jump to endpoint details →

/api/email

Random Email Generator

Open tool →

Generate test email addresses for auth flows, notifications, imports, and seeded QA data.

Jump to endpoint details →

/api/phone

Random Phone Number Generator

Open tool →

Generate phone records for contact fields, telecom validation, and automation scenarios.

Jump to endpoint details →

/api/uuid

UUID Generator

Generate UUID v4 batches for fixtures, record IDs, seeded data, and integration tests.

Example request

/api/uuid?count=3&uppercase=true

Query param	Type	Default	Accepted values	Notes
count	number	10	1 to 100	Invalid or missing values fall back to the default, then the result is clamped into the supported range.
format	string	json	json	Only JSON transport is supported. Any other value returns HTTP 400.
version	string	v4	v4 (UUID v4)	Version 4 is supported now, with room to add more versions later.
uppercase	boolean	false	true, false	Return UUIDs in uppercase for systems that prefer case-normalized identifiers.
includeOnePerLine	boolean	true	true, false	Keep each generated UUID as a single line item for clean copy/paste and exports.
outputFormat	string	json	json (JSON), csv (CSV), sql (SQL)	Accepted because it mirrors the UI, but API responses are always JSON. Use the `format` query param only for transport format selection.

Example JSON response

{
  "generator": "uuid",
  "count": 1,
  "format": "json",
  "options": {
    "version": "v4",
    "uppercase": false,
    "includeOnePerLine": true,
    "outputFormat": "json"
  },
  "data": [
    {
      "uuid": "9f697101-f480-4ad5-8511-9b259590acb8",
      "display": "9f697101-f480-4ad5-8511-9b259590acb8",
      "urn": "urn:uuid:9f697101-f480-4ad5-8511-9b259590acb8",
      "version": 4,
      "format": "lowercase",
      "lineSeparated": true
    }
  ]
}

/api/user

Random User Generator

Return fake user profiles with optional address, phone, company, and DOB fields.

Example request

/api/user?count=2&country=US&includeAddress=true&includePhone=true

Query param	Type	Default	Accepted values	Notes
count	number	10	1 to 100	Invalid or missing values fall back to the default, then the result is clamped into the supported range.
format	string	json	json	Only JSON transport is supported. Any other value returns HTTP 400.
country	string	US	US (United States), CA (Canada), GB (United Kingdom), AU (Australia), BR (Brazil), FR (France), LU (Luxembourg), BE (Belgium), NL (Netherlands), DE (Germany), ES (Spain), IT (Italy), PT (Portugal), IE (Ireland)	Mirrors the matching generator option from the page UI.
gender	string	mixed	mixed (Mixed), female (Female), male (Male), other (Other)	Mirrors the matching generator option from the page UI.
includeAddress	boolean	true	true, false	Mirrors the matching generator option from the page UI.
includePhone	boolean	true	true, false	Mirrors the matching generator option from the page UI.
includeCompany	boolean	true	true, false	Mirrors the matching generator option from the page UI.
includeDOB	boolean	true	true, false	Mirrors the matching generator option from the page UI.
outputFormat	string	json	json (JSON), csv (CSV), sql (SQL)	Accepted because it mirrors the UI, but API responses are always JSON. Use the `format` query param only for transport format selection.

Example JSON response

{
  "generator": "user",
  "count": 1,
  "format": "json",
  "options": {
    "country": "US",
    "gender": "mixed",
    "includeAddress": true,
    "includePhone": true,
    "includeCompany": true,
    "includeDOB": true,
    "outputFormat": "json"
  },
  "data": [
    {
      "id": "a9315e98-55c9-4bfa-aea0-d7c3d6c04443",
      "firstName": "Elijah",
      "lastName": "Anderson",
      "fullName": "Elijah Anderson",
      "gender": "male",
      "username": "elijah.anderson586",
      "email": "elijah.anderson694@example.com",
      "phone": "+1 (312) 722-4663",
      "dateOfBirth": "1970-08-02",
      "company": "Northwind",
      "jobTitle": "QA Engineer",
      "address": "6007 Main Lane, Austin, IL, 30303, US",
      "addressLine1": "6007 Main Lane",
      "addressLine2": "",
      "city": "Austin",
      "stateProvince": "IL",
      "postalCode": "30303",
      "country": "US",
      "locale": "en-US"
    }
  ]
}

/api/address

Random Address Generator

Create realistic addresses for checkout, billing, shipping, and form-validation workflows.

Example request

/api/address?count=2&country=GB&includeApartment=true

Query param	Type	Default	Accepted values	Notes
count	number	10	1 to 100	Invalid or missing values fall back to the default, then the result is clamped into the supported range.
format	string	json	json	Only JSON transport is supported. Any other value returns HTTP 400.
country	string	US	US (United States), CA (Canada), GB (United Kingdom), AU (Australia), BR (Brazil), FR (France), LU (Luxembourg), BE (Belgium), NL (Netherlands), DE (Germany), ES (Spain), IT (Italy), PT (Portugal), IE (Ireland)	Mirrors the matching generator option from the page UI.
includePostalCode	boolean	true	true, false	Mirrors the matching generator option from the page UI.
includeApartment	boolean	false	true, false	Mirrors the matching generator option from the page UI.
includeState	boolean	true	true, false	Mirrors the matching generator option from the page UI.
outputFormat	string	json	json (JSON), csv (CSV), sql (SQL)	Accepted because it mirrors the UI, but API responses are always JSON. Use the `format` query param only for transport format selection.

Example JSON response

{
  "generator": "address",
  "count": 1,
  "format": "json",
  "options": {
    "country": "US",
    "includePostalCode": true,
    "includeApartment": false,
    "includeState": true,
    "outputFormat": "json"
  },
  "data": [
    {
      "line1": "9995 Lake Road",
      "line2": "",
      "city": "San Francisco",
      "stateProvince": "NY",
      "postalCode": "30303",
      "country": "US",
      "addressType": "general",
      "fullAddress": "9995 Lake Road, San Francisco, NY, 30303, US"
    }
  ]
}

/api/email

Random Email Generator

Generate test email addresses for auth flows, notifications, imports, and seeded QA data.

Example request

/api/email?count=3&domainType=qa&lowercaseOnly=true

Query param	Type	Default	Accepted values	Notes
count	number	10	1 to 100	Invalid or missing values fall back to the default, then the result is clamped into the supported range.
format	string	json	json	Only JSON transport is supported. Any other value returns HTTP 400.
domainType	string	mixed	mixed (Mixed), example (Example domains), testmail (Test mail domains), qa (QA domains)	Mirrors the matching generator option from the page UI.
useFirstLastStyle	boolean	true	true, false	Mirrors the matching generator option from the page UI.
includeNumericSuffix	boolean	true	true, false	Mirrors the matching generator option from the page UI.
lowercaseOnly	boolean	true	true, false	Mirrors the matching generator option from the page UI.
outputFormat	string	json	json (JSON), csv (CSV), sql (SQL)	Accepted because it mirrors the UI, but API responses are always JSON. Use the `format` query param only for transport format selection.

Example JSON response

{
  "generator": "email",
  "count": 1,
  "format": "json",
  "options": {
    "domainType": "mixed",
    "useFirstLastStyle": true,
    "includeNumericSuffix": true,
    "lowercaseOnly": true,
    "outputFormat": "json"
  },
  "data": [
    {
      "email": "avery.clark608@testmail.com",
      "localPart": "avery.clark608",
      "domain": "testmail.com",
      "style": "first.last"
    }
  ]
}

/api/phone

Random Phone Number Generator

Generate phone records for contact fields, telecom validation, and automation scenarios.

Example request

/api/phone?count=2&country=US&formatStyle=formatted&includeCountryCode=true

Query param	Type	Default	Accepted values	Notes
count	number	10	1 to 100	Invalid or missing values fall back to the default, then the result is clamped into the supported range.
format	string	json	json	Only JSON transport is supported. Any other value returns HTTP 400.
country	string	US	US (United States), CA (Canada), GB (United Kingdom), AU (Australia), BR (Brazil), FR (France), LU (Luxembourg), BE (Belgium), NL (Netherlands), DE (Germany), ES (Spain), IT (Italy), PT (Portugal), IE (Ireland)	Mirrors the matching generator option from the page UI.
formatStyle	string	formatted	formatted (Formatted), raw (Raw digits)	Mirrors the matching generator option from the page UI.
includeCountryCode	boolean	true	true, false	Mirrors the matching generator option from the page UI.
numberType	string	generic	generic (Generic), mobile (Mobile-style)	Mirrors the matching generator option from the page UI.
outputFormat	string	json	json (JSON), csv (CSV), sql (SQL)	Accepted because it mirrors the UI, but API responses are always JSON. Use the `format` query param only for transport format selection.

Example JSON response

{
  "generator": "phone",
  "count": 1,
  "format": "json",
  "options": {
    "country": "US",
    "formatStyle": "formatted",
    "includeCountryCode": true,
    "numberType": "generic",
    "outputFormat": "json"
  },
  "data": [
    {
      "display": "+1 (704) 611-4122",
      "rawDigits": "17046114122",
      "e164": "+17046114122",
      "international": "+1 (704) 611-4122",
      "national": "(704) 611-4122",
      "country": "US",
      "countryCode": "+1",
      "numberType": "generic",
      "areaCode": "704",
      "exchangeCode": "611",
      "lineNumber": "4122"
    }
  ]
}

Error behavior

HTTP 400 — bad request

Returned when an unsupported transport format is requested. The current implementation accepts only `format=json` or no `format` query param at all.

{
  "error": "Bad request",
  "message": "Unsupported format. API routes return JSON responses only."
}

HTTP 429 — rate limited

Returned when the in-memory per-IP rate limit is exceeded within the current one-minute window.

{
  "error": "Too many requests",
  "message": "Rate limit exceeded. Try again in about a minute."
}

Limits, headers, and caching

Rate limit

100 requests per 60 seconds per IP

The current limiter is in-memory, so limits are best-effort in a single runtime and are not yet distributed across instances.

X-RateLimit-Limit

X-RateLimit-Remaining

X-RateLimit-Reset

Retry-After (429 responses only)

Cache behavior

Successful and error responses include `Cache-Control: private, max-age=60, stale-while-revalidate=300`. Generated results are also memoized in memory for short-lived repeated requests with the same generator, options, and count.

Validation notes

`count` defaults to 10 and is clamped into the 1–100 range.
Generator-specific query params are parsed from the same field definitions used by the UI.
Boolean values should be sent as `true` or `false`.
Only the `format` query param controls response transport, and only `json` is accepted.

Response shape

Every public endpoint returns the same top-level JSON envelope so downstream scripts can parse responses consistently across generators.

generator

The generator key used by the endpoint, such as `uuid` or `user`.

count

The final record count after defaulting and clamping.

format

Always `json` for the current public API.

options

The resolved generator options after query parsing and defaulting.

data

An array of generated records.